tomasfil/blazedex

# BlazeDex — Blazor MCP Server [](LICENSE) [](https://dotnet.microsoft.com) [](https://github.com/modelcontextprotocol/csharp-sdk) [](https://github.com/tomasfil/blazedex/releases) [](https://github.com/tomasfil/blazedex/actions/workflows/ci.yml) **一个感知 Blazor/Razor 的 .NET 10 Model Context Protocol 服务器。** BlazeDex 通过 Roslyn 的完整编译管道对你的 Blazor 解决方案进行索引，并通过 Razor 源生成器的 `#line` 指令，将每一个组件的使用、事件处理程序绑定和路由精确回溯到 `.razor:line:column`。无需 grep。无需反射。无字符串匹配误报。 ## 为什么选择 BlazeDex ## 适合你的情况 - 你正在开发 Blazor 解决方案，并且使用 Claude Code（或任何其他支持 MCP 的 AI 代理） - 你希望在不使用 grep 的情况下，获得关于组件图的语义解答——用法、参数、渲染模式冲突、死代码等 - 你想要一个只读分析层，除非通过一个显式的编辑工具，否则它永远不会触碰你的源代码树 ## 不适合你的情况 - 你想要一个镜像特定组件库文档的 MCP 服务器（→ 参见 [Radzen MCP](https://www.radzen.com/blazor-mcp)、[Fluent UI Blazor MCP](https://dvoituron.com/2026/02/20/fluentui-blazor-mcp-server/)、[MudMCP](https://github.com/mcbodge/MudMCP)) - 你想要一个针对实时应用的基于反射的运行时检查器（→ 参见 [Components.MCP.Blazor](https://github.com/SimonLiebers-Dev/Components.MCP.Blazor)) - 你没有使用 .NET 10（这是必需的——我们需要读取 Razor 源生成器的输出） ## 快速开始 **1.** 下载最新版本并解压： ``` gh release download v0.1.0 -p "blazedex-mcp-v0.1.0-win-x64.zip" mkdir -p "/c/tools/blazedex-mcp" unzip -o blazedex-mcp-v0.1.0-win-x64.zip -d "/c/tools/blazedex-mcp" ``` **2.** 将此 `.mcp.json` 文件放入你的 **Blazor 项目**的代码库根目录： ``` { "mcpServers": { "blazedex": { "command": "dotnet", "args": ["C:\\tools\\blazedex-mcp\\BlazeDex.Mcp.dll"], "env": { "BLAZEDEX_SOLUTION": "C:\\path\\to\\YourApp.sln" } } } } ``` **3.** 向 Claude Code 提问关于你的 Blazor 代码的问题： ``` Find every usage of the WidgetExample component. ``` Claude 将调用 `find_component_usages("WidgetExample")` 并返回组件实例化的每一个 `.razor:line:column` 位置——通过 Razor 生成器的 `#line` 指令解析。无需 grep，注释中的字符串匹配不会产生误报，也不会混淆 `` 和 `MyButton.SomeStaticMethod()`。 完整的配置、环境变量和故障排除：参见第 3 节及以后的内容。 ## 1. TL;DR (太长不看) BlazeDex 通过 Roslyn 的 `MSBuildWorkspace` 索引 Blazor 解决方案，遍历 Razor 源生成器的 `*.razor.g.cs` 输出，并通过 stdio JSON-RPC 暴露 20 个工具，用于组件发现、用法追踪、API 内省、代码质量检查和一个安全的编辑操作。 具体来说：向 Claude 询问 `find_component_usages("WidgetExample")`，你将获得解决方案中每一个 `` 标记位置，包含精确的 `.razor:line:column` 源码位置，通过 Razor 生成器的 `#line` 指令解析。无需 grep。注释中的字符串匹配不会产生误报。没有扩展方法的混淆。也无需费心区分 `` 和 `MyButton.SomeStaticMethod()`。 这个单一示例是 BlazeDex 提供的最小价值单元。其他 19 个工具遵循相同的模式——基于 Roslyn、锚定源码，在代码损坏时呈现 yellow 而绝不是 red。 ## 2. 状态与兼容性 - **版本：** v0.1.0（首次公开发布）。 - **运行时：** 需要 .NET 10 SDK（`net10.0` 目标框架）。 - **MCP SDK：** ModelContextProtocol 1.2.0（官方 Anthropic SDK），stdio 传输。 - **Roslyn：** Microsoft.CodeAnalysis.CSharp.Workspaces 5.3.0 + Workspaces.MSBuild 5.3.0，`Microsoft.Build.*` 固定在 17.11.48（MSBL001 规避方案——参见故障排除）。 - **缓存：** 始终开启第 1 层内存缓存；用于热重启的第 2 层磁盘 SQLite 缓存（`Microsoft.Data.Sqlite` 10.0.5）。 - **测试环境：** 一个真实的 Blazor WebAssembly 解决方案（约 3 个项目，约 500 个 razor 文件，Roslyn 冷构建耗时 10–16 秒，远在规范 §10 小于 30 秒的预算之内）。所有 20 个工具均针对此语料库进行了端到端测试。 - **操作系统：** Windows 是主要支持的平台，也是 v0.1.0 中唯一经过独立验证的操作系统。macOS 和 Linux 理论上可以通过 `MSBuildLocator` 在启动时解析的便携版 MSBuild 运行时正常工作，但在 v0.1 中并未经过独立验证——如果你在非 Windows 主机上运行 BlazeDex，请提交 issue，以便我们记录相关的坑点。 - **测试目标架构：** 采用标准 `{Component}.razor` + `{Component}.razor.cs` 分部类约定的 Blazor WebAssembly。Blazor Server 和 Blazor United（Interactive Server / WebAssembly / Auto 渲染模式）可通过相同的生成器管道正确解析；特别是渲染模式检查目标是 Blazor United 模型。 - **线程模型：** 单进程 MCP 服务器，一次加载一个解决方案，在该解决方案内的各项目间进行扇出展开。 ## 3. 安装 你可以从 GitHub Releases 页面下载预构建的 zip 包，或者从源码构建。这两种方式都会生成相同的二进制文件布局——一个包含 `BlazeDex.Mcp.dll` 及其依赖项和运行时配置文件的自包含、依赖框架的发布文件夹。 ### 3.a 预构建版本（推荐） 使用 `gh` CLI 下载最新版本的 zip 包并将其解压到磁盘上的稳定位置。我们建议在 Windows 上使用 `C:\tools\blazedex-mcp\`，这样 `.mcp.json` 中的路径可以保持简短且可预测： ``` gh release download v0.1.0 -p "blazedex-mcp-v0.1.0-win-x64.zip" mkdir -p "/c/tools/blazedex-mcp" unzip -o blazedex-mcp-v0.1.0-win-x64.zip -d "/c/tools/blazedex-mcp" ``` 解压后，该目录应包含 `BlazeDex.Mcp.dll` 及其支持程序集。请使用以下命令进行验证： ``` ls "/c/tools/blazedex-mcp/BlazeDex.Mcp.dll" ``` ### 3.b 从源码构建 克隆代码仓库并以 Release 配置进行发布。`dotnet publish` 步骤会编译、链接所有依赖框架的资产，并将其复制到一个统一的输出文件夹中，你可以从任何 MCP 客户端引用该文件夹。 ``` git clone https://github.com/tomasfil/blazedex.git cd blazedex dotnet publish src/BlazeDex.Mcp -c Release -o artifacts/publish/BlazeDex.Mcp ``` `artifacts/publish/BlazeDex.Mcp/` 文件夹现在是自包含的——你可以将其复制到任何地方，如果你想与预构建版本保持相同的磁盘布局，也可以将其放入 `C:\tools\blazedex-mcp\`。 如果你打算持续跟进上游更改，请将克隆的代码仓库保留在原位，并在每次 `git pull` 之后重新运行 `dotnet publish` 命令。只要当前没有 MCP 客户端进程占用打开的 DLL，发布到同一输出目录将干净地覆盖之前的构建。 ## 4. 配置 BlazeDex 是通过你的**目标** Blazor 代码库（即你希望索引的解决方案所在的代码库）中的 `.mcp.json` 文件进行按项目配置的，外加一小部分环境变量，用于将服务器指向正确的 `.sln` 或 `.csproj`。 MCP 服务器本身从不从项目文件中读取任何内容——它的配置完全继承自 Claude Code（或其他 MCP 客户端）启动它的宿主 shell 环境。 ### 4.a `.mcp.json` 模板 将此代码仓库中的 `docs/mcp.json.example` 复制到你目标项目的 `.mcp.json` 中并调整路径。一个最简化的 Windows 配置如下所示： ``` { "mcpServers": { "blazedex": { "command": "dotnet", "args": ["C:\\tools\\blazedex-mcp\\BlazeDex.Mcp.dll"], "env": { "BLAZEDEX_SOLUTION": "C:\\path\\to\\YourApp.sln" } } } } ``` `command` 字段调用 .NET 运行时，`args` 数组将其指向已发布的 `BlazeDex.Mcp.dll`，而 `env` 块将目标解决方案路径注入到生成的进程中。`env` 块是按项目限定配置最可靠的方法——它与代码库一起传递，且从不依赖于用户环境的副作用。 ### 4.b 环境变量 环境变量的完整参考位于 `docs/env.md` 中。你可以设置的四个变量是： - **`BLAZEDEX_SOLUTION`** — 你的 `.sln` 文件的完整路径。**首选。** 加载解决方案中的每个项目，并暴露解决方案级别的查询（跨项目组件使用、依赖图漂移处理、整个图的渲染模式检查）。 - **`BLAZEDEX_PROJECT`** — 单个 `.csproj` 的完整路径。单项目回退方案。当解决方案太大或损坏严重而无法整体加载时非常有用；你会失去跨项目查询功能，但所选项目内的一切功能仍可使用。 - **`BLAZEDEX_WATCHER`** — 设置为 `0` 或 `false` 可禁用被动的 `FileSystemWatcher` 快速路径提示。基于 stat 的指纹检查仍会在每次调用时运行，因此正确性不受影响——只是禁用了进程内的延迟提示。 - **`BLAZEDEX_VERIFIED_CLEAN_WINDOW_MS`** — 快速路径窗口的毫秒数（默认为 `250`）。当监听器在此窗口内报告了干净状态时，下一次工具调用将跳过 stat-walk。如果你怀疑快速的系统文件更改正逃过此窗口，请降低该值。 ### 4.c 继承你的 Shell 环境 MCP 服务器从启动它的进程继承环境变量。如果你只在单个 shell 中设置了 `BLAZEDEX_SOLUTION`，则从另一个 shell 启动的 Claude Code 将无法看到它。 在 Windows 上，将 `BLAZEDEX_SOLUTION` 设置为**用户环境变量**（`setx BLAZEDEX_SOLUTION "C:\path\to\YourApp.sln"`）并重启你的编辑器，或者如上所述通过 `.mcp.json` 的 `env` 块显式传递它。通过 `.mcp.json` 传递是最可预测的方法，因为配置随项目一起移动。 在 macOS 和 Linux 上，在 `~/.zshrc` 或 `~/.bashrc`（取决于你的编辑器继承了哪个）中导出变量，并重启编辑器会话。在所有平台上，按项目配置的 `.mcp.json` `env` 块仍然是最可靠的方法。 ## 5. 首次运行 ### 5.a 冷构建 针对全新进程的第一次工具调用会触发已配置解决方案的完整 Roslyn 冷构建。 在测试语料库（约 3 个项目，约 500 个 razor 文件）上，这需要 **10–16 秒**，并且远在规范 §10 **<30 秒** 的预算之内。较大的解决方案随项目数量和文件数量大致呈线性扩展。 冷构建占据了该调用——针对同一进程的每隔一次工具调用都由内存中的第 1 层缓存（亚毫秒级）提供服务，直到磁盘上的某些内容发生更改。冷构建之后，`get_index_status` 将报告一个与你为第一次调用观察到的挂钟时间相匹配的 `lastBuildMs` 值。 ### 5.b 健全性检查 在 Claude Code 为你的项目启动 MCP 服务器后，要求它调用以下两个诊断工具： 1. **`ping`** — 应返回字面字符串 `"pong"`。如果失败，说明服务器未运行或 stdio 传输配置错误。 2. **`get_index_status`** — 应返回一个 `state` 字段为 `green` 的 JSON 对象。第一次调用可能会阻塞在冷构建上；后续调用将立即返回。 在健康项目上的典型首次运行如下所示： ``` > ping "pong" > get_index_status { "state": "green", "projectCount": 3, "componentsIndexed": 160, "lastBuildMs": 11420, "loadErrors": [], "parseErrors": [] } ``` 如果 `state` 返回为 `yellow`，则 BlazeDex 成功加载了解决方案，但某些文件存在编译错误——受影响的行将返回 `resolved: false` 及其原因，但不相关的行仍然完全正确。 如果 `state` 返回为 `red`，则整个解决方案加载失败（缺少 SDK、未还原的包、未设置环境变量）。其他工具在 red 状态下将返回空结果而不会抛出异常——请先调用 `get_index_status` 找出原因。 ### 5.c 状态语义详情 - **Green** — 干净的构建；每一行都有 `resolved: true`；`loadErrors` 和 `parseErrors` 为空。这是健康项目的稳定状态。 - **Yellow** — 尽力而为的构建；某些 `.razor` 或 `.cs` 文件有错误，触及这些文件的行将返回 `resolved: false` 并在 `reason` 字段中附带人类可读的原因，所有其他行完全正确。Yellow **不是**失败——它是 BlazeDex 的“我已经尽力提供了所能提供的信息”的状态。规范 §10 称此为 *yellow > red* 原则：部分答案胜过抛出异常。 - **Red** — 灾难性故障。解决方案根本没有加载`loadErrors` 列出了诊断信息。工具调用返回空数组而不抛出异常，因此在你修复根本原因时，Claude Code 可以继续操作你的其余工具集。 ### 5.d 你应该期望的延迟 - **首次调用（冷构建）：** 在约 3 个项目、约 500 个 razor 文件的解决方案上需要 10–20 秒。Roslyn 成本占主导地位；除非从第 2 层 SQLite 缓存进行热加载，否则 BlazeDex 无能为力。 - **温暖的第 2 层加载：** 从进程启动到第一行数据的挂钟时间需 18–22 毫秒。可在进程重启后存活。与第 1 层使用相同的指纹检查——热加载绝不会在没有重新验证的情况下被信任。 - **温暖的第 1 层调用：** 亚毫秒级。对于一个 500 文件的解决方案，指纹遍历大约需要 ~50 毫秒，但是当监听器在过去 `BLAZEDEX_VERIFIED_CLEAN_WINDOW_MS`（默认 250 毫秒）内报告了干净状态时，监听器快速路径会跳过此步骤。 - **漂移触发的重建：** 10–16 秒，与冷构建相同。部分构建被推迟——参见已知限制。 ## 6. 工具目录 BlazeDex v0.1.0 暴露了分组为六个功能桶的 **20 个工具**。 每个工具都将其主体封装在 MCP 边界处的 `try/catch` 中；异常会成为响应中的结构化错误行，并且永远不会传播到客户端。 ### 6.a 发现 (5 个工具) - **`list_razor_components(glob?, limit, offset)`** — 枚举已索引解决方案中的每一个 `.razor` 组件，带有可选的 glob 过滤器和分页功能。返回源路径、代码隐藏路径（如果存在）以及组件的完全限定名。 - **`list_pages(glob?)`** — 列出每一个可路由的组件，派生自 `@page` 指令和分部类上的 `[Route(…)]` 属性。每一行包含路由模板以及该指令的源码位置。 - **`find_component(name)`** — 通过短名称或完全限定名定位组件。返回规范行，包括所有存在的代码隐藏伙伴（`.razor`、`.razor.cs`、`.razor.css`）。 - **`find_components_injecting(serviceTypeName)`** — 查找其 `[Inject]` 链（包括跨越项目边界的继承基类）引用给定服务类型的每一个组件。适用于更改 DI 注册时的影响范围分析。 - **`find_route_definitions(routeTemplateGlob?)`** — 枚举解决方案中的每一个路由模板，可选择通过模板字符串上的 glob 进行过滤。每一行包含路由以及拥有它的组件。 ### 6.b 使用 (5 个工具) - **`find_component_usages(componentName, limit, offset)`** — 返回实例化给定组件的每一个标记位置。例如，`find_component_usages("WidgetExample")` 返回每一个消费页面的 `.razor:line:column`，且带有 `resolved: true`。解析通过 Razor 生成器的 `#line` 指令经由 `Location.GetMappedLineSpan()` 进行——绝非手动解析。 - **`find_handler_bindings(methodQualifiedName)`** — 查找通过 `EventCallback.Factory.Create(this, HandlerName)` 连接代码隐藏处理程序的每一个标记位置。例如，`find_handler_bindings("WidgetExampleBase.HandleValueChanged")` 返回绑定位置的 `.razor:line:column`。 - **`find_parameter_passers(componentName, parameterName)`** — 查找向给定组件的特定 `[Parameter]` 传递值的每一个标记位置。通过 Razor 生成器的 `AddComponentParameter(seq, nameof(Type.PropName), valueExpr)` 模式进行解析。 - **`find_binding_targets(componentName, parameterName)`** — 查找针对特定组件参数使用 `@bind-{Parameter}` 语法糖的每一个标记位置。返回绑定目标表达式及其 `.razor:line:column` 位置。 - **`find_bind_inventory(componentName?)`** — `@bind-…` 用法的解决方案级清单，可选择过滤为单个组件。适用于双向绑定审计和迁移计划。 ### 6.c API (3 个工具) - **`get_component_api(componentQualifiedName)`** — 返回组件的完整表面区域：参数（带有 `[EditorRequired]`、`[SupplyParameterFromQuery]`、捕获不匹配值标志）、级联参数、渲染片段、注入、方法、字段、事件、类级别属性和泛型约束。通过 `INamedTypeSymbol.BaseType` 遍历跨项目边界的继承链，因此基类成员会自动折叠包含在内。 - **`get_component_tree(componentName, depth?)`** — 渲染以给定组件为根的组件实例化树，递归遍历 `OpenComponent` 调用直到可选的深度限制。每个节点都带有 `.razor:line:column` 源锚点。 - **`get_cascading_chain(componentName)`** — 从消费者向其提供者追溯 `[CascadingParameter]` 流。在 v0.1 中仅限于静态级联模型——有关此功能尚未涵盖的内容，请参见已知限制。 ### 6.d 质量 (4 个工具) - **`find_unused_components(includeTestProjects?)`** — 列出解决方案中 `find_component_usages` 结果为零的每一个组件。可选择将测试项目纳入分析。这是死代码清理的第一步。 - **`find_route_conflicts()`** — 返回解析存在歧义的路由模板（两个或多个组件声明了相同的 `@page` 字面量，或模板的约束存在重叠）。每个冲突行列出了每一个违规组件。 - **`find_render_mode_conflicts()`** — 返回在 Blazor United 中其渲染模式属性与其父级渲染模式冲突的组件（例如，一个实例化在 `RenderModeWebAssembly` 父组件内的 `RenderModeServer` 组件）。每行带有两个锚点。 - **`find_dead_routes()`** — 返回通过 `@page` 指令可达但从未从任何 `` 或编程式 `NavigationManager.NavigateTo` 调用链接到的路由定义。适用于查找孤立的 admin 页面和过时的端点。 ### 6.e 编辑 (1 个工具) - **`add_parameter(componentQualifiedName, parameterName, parameterType, defaultValueExpression?, isEditorRequired?)`** — v0.1.0 中**唯一**的编辑工具。通过 Roslyn 的 `SymbolEditor` 将 `[Parameter] public {Type} {Name} { get; set; }` 声明添加到命名组件的代码隐藏分部类中。在写入之前验证参数不存在，在修改后的文件上运行 `dotnet format`，并在响应中显示差异。所有其他编辑操作推迟到规范的 Phase 3（参见已知限制）。 ### 6.f 诊断 (2 个工具) - **`ping()`** — 返回字面字符串 `"pong"`。在启动 MCP 服务器后将其作为第一次调用，以确认 stdio 传输工作正常。 - **`get_index_status()`** — 返回索引的当前状态：`state`（`green`/`yellow`/`red`）、`projectCount`、`componentsIndexed`、`lastBuiltAtUtc`、`lastBuildMs`、`loadErrors`、`parseErrors`、`tier2Loaded`、`watcherHealth`。这是出现问题时首先要调用的工具。 ## 7. 故障排除 ### 7.a 首次调用后 `state: red` 整个解决方案加载失败。常见原因： - **未安装 .NET 10 SDK。** BlazeDex 目标是 `net10.0`，并且运行 MCP 服务器的机器上需要 .NET 10 SDK。使用 `dotnet --list-sdks` 检查——你应该看到至少一个 `10.0.x` 条目。如果你只有较旧的 SDK，请从 https://dot.net 安装 .NET 10 并重启你的 MCP 宿主。 - **NuGet 包未还原。** 在启动 MCP 服务器之前，至少对你的目标解决方案运行一次 `dotnet restore`。如果上游项目未还原，Roslyn `MSBuildWorkspace` 无法解析 `ProjectReference` 闭包。 - **未设置环境变量。** 确认在启动 Claude Code 的环境中设置了 `BLAZEDEX_SOLUTION`（或 `BLAZEDEX_PROJECT`）。如果你的 shell 环境不可靠，请通过 `.mcp.json` 的 `env` 块传递它们。 - **路径错误或包含错误的斜杠。** 在 Windows 上的 JSON 字符串字面量中使用双反斜杠：`"C:\\path\\to\\YourApp.sln"`，而不是 `"C:\path\to\YourApp.sln"`。正斜杠也可以：`"C:/path/to/YourApp.sln"`。 - **解决方案文件引用了丢失或已移动的项目。** 在文本编辑器中打开 `.sln` 并确认每个 `Project("…") = "…", "…"` 行都指向一个相对于解决方案文件存在的路径。 如果从 `loadErrors` 中看不出明显原因，请从命令行针对同一解决方案运行 `dotnet build`。那里出现的任何错误也会在 BlazeDex 中重现。 ### 7.b 带有 `resolved: false` 行的 `state: yellow` 某些文件有编译错误。BlazeDex 提供它能解析的内容；受影响的行会返回 `resolved: false` 和一个 `reason` 字符串。这就是规范的 *yellow > red* 原则——yellow 是正确的行为，而不是 bug。在你的编辑器中修复潜在的编译错误，下一次工具调用将重建并清除 yellow 状态。 如果你想确切查看哪些文件失败，请查看 `get_index_status.parseErrors`——它列出了每个受影响的文件以及 Roslyn 抛出的诊断消息。 ### 7.c 首次调用缓慢（约 10–20 秒） 这是预期的 Roslyn 冷构建。针对全新进程的第一次工具调用会加载解决方案中的每个项目，物化 Razor 生成器的语法树并遍历它们。 随后的调用将命中内存中的第 1 层缓存并在不到一毫秒内完成。在热重启时，第 2 层 SQLite 缓存将在 18–22 毫秒内加载。 如果你的冷构建超过 30 秒（规范上限），请附上 `get_index_status` 输出提交 issue，以便我们为你的项目形状调整索引器。 ### 7.d 监听器被禁用或不健康 查看 `get_index_status.watcherHealth`。如果它报告 `disabled`，说明你设置了 `BLAZEDEX_WATCHER=0`——通过取消设置该变量来重新启用它。 如果它报告 `unhealthy`，说明监听器触发了其 10 秒 / 3 次失败的重创建预算（通常是因为项目位于网络共享或 WSL 桥接上，这两者都会静默丢弃 `FileSystemWatcher` 事件）。 正确性不受影响，因为每次调用的 stat 指纹始终作为权威检查运行；你只是失去了延迟提示。要强制禁用监听器并完全依赖 stat 指纹，请设置 `BLAZEDEX_WATCHER=0` 并重启 MCP 宿主。 ### 7.d 重建 MCP 时的锁定错误 如果当 Claude Code 仍然保持 MCP 进程打开时你执行了 `dotnet build` 构建 BlazeDex 本身，你将会在 `BlazeDex.Mcp.dll` 及相关文件上看到文件锁定错误。在重建之前退出 Claude Code（或 MCP 宿主），或者在一个不同的输出目录中构建。 `C:\tools\blazedex-mcp\` 下的发布输出由正在运行的进程加载，无法原地覆盖。CI 发布管道之所以使用 `dotnet build -c Release` 并 `dotnet publish` 到单独的 `artifacts/publish/` 文件夹，正是出于这个原因。 ### 7.f 验证健康的安装 如果你想要一个不依赖于 Claude Code 的自包含健全性检查，请在 BlazeDex 代码仓库内运行 `dotnet test --no-build -c Release` 以执行单元测试套件，然后启动服务器并从你选择的 MCP 客户端调用 `ping`，接着是 `get_index_status`。绿色的 `state` 加上非零的 `componentsIndexed` 即可确认安装是端到端健康的。 ## 8. 已知限制 v0.1.0 是第一个可发布的版本。以下差距被有意推迟到后续阶段——它们被记录在 `PLAN.md` 和 Phase 2/3 规范中。 - **编辑操作仅限于 `add_parameter`。** 规范 Phase 3（重命名、提取组件、更改参数类型、代码隐藏分部提升、路由重构）被推迟。v0.1 刻意只发布一个安全的编辑操作，以便在没有庞大维护表面积的情况下端到端地测试布线（Roslyn `SymbolEditor`、格式化传递、响应差异、范围锁）。 - **漂移处理触发完整重建。** 当每次调用的 stat 指纹检测到任何更改时，BlazeDex 会重建整个解决方案（在测试语料库上需 10–16 秒，远在 <30 秒预算内）。通过 `ProjectDependencyGraph` 反向依赖闭包进行的部分重建已接入内存模型，但尚未连接到重建路径——`MSBuildWorkspace` 不支持就地项目重载，因此一旦符号解析需要传递的 `ProjectReference` 闭包，每个受影响项目的新建工作区方法就会级联成近乎整个解决方案的重载。行数据已经是独立于 Roslyn 的（在索引构建时通过 `Location.GetMappedLineSpan()` 预映射），因此未来的步骤可以在不更改架构的情况下将漂移处理切换为真正的部分重建。 - **CascadingValue 追踪仅限于 `get_cascading_chain`。** 支持静态的 `[CascadingParameter]` ↔ `` 提供者/消费者链。动态级联值（编程式提供者、条件级联作用域、值更改重渲染流）推迟到规范 Phase 2。 - **`RenderFragment` 解析是部分的。** Phase 2 表面将 `RenderFragment` 和 `RenderFragment` 拆分为 `get_component_api` 上的专用 `fragments` 桶，但完整的模板内容解析（哪些标记实际填充了片段，带有完整的 `.razor:line:column` 溯源）被推迟。 - **每个进程一个解决方案。** 一个 BlazeDex MCP 进程处理一个解决方案。要同时索引两个解决方案，请在你的 `.mcp.json` 中注册两个具有不同 `BLAZEDEX_SOLUTION` 值和不同命令调用的 MCP 服务器。 - **非 Windows 宿主未经过独立验证。** macOS 和 Linux 理论上可以通过 `MSBuildLocator` 在启动时解析的便携版 MSBuild 运行时工作，但 v0.1.0 仅附带经过端到端验证的 Windows。 - **无流式响应。** 所有工具响应作为单个 JSON-RPC 消息返回。非常大的结果集通过工具支持 `limit` / `offset` 参数进行分页。 ## 9. 许可证 BlazeDex 是在 [**Elastic License 2.0**](LICENSE) 下的**源码可用**项目。 简而言之：你可以自由使用、修改和分发 BlazeDex，**除了**： 1. 你不得将 BlazeDex 作为托管或托管服务提供给第三方，前提是该服务让用户能够访问 BlazeDex 的实质性功能集。 2. 你不得规避任何许可证密钥功能。 3. 你不得更改、删除或模糊处理任何版权或许可声明。 完整条款请参见 [`LICENSE`](LICENSE)。通过向此代码库做出贡献，你同意按照相同的条款许可你的贡献。提交流程要求请参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 10. 架构 关于设计原理和完整的工具表面规范，请参见 `blazor-razor-mcp.md`——这是驱动 v0.1 构建的规范文档。 关于执行计划、推迟的工作以及沿途做出的设计决策，请参见 `PLAN.md`。这两个文件都位于代码库的根目录并已签入。 高层架构如下： - **stdio 传输。** 所有日志都路由到 **stderr**，因为 stdout 是为 JSON-RPC 协议帧保留的。服务器代码中禁止使用 `Console.WriteLine`。 - **`MSBuildLocator.RegisterDefaults()`** 作为 `Program.cs` 的**第一行**运行，在任何 MSBuild 程序集加载之前。这是不可协商的——其他任何情况都会触发 MSBL001。 - **Roslyn `MSBuildWorkspace`** 打开配置的 `.sln`（或回退的 `.csproj`），并且 `GetCompilationAsync` 在内存中物化 Razor 源生成器的 `*.razor.g.cs` 语法树——不会向磁盘写入任何文件。 - **`ProjectIndexer`** 为每个项目遍历一次语法树，为每个工具收集行数据，并将它们存储在每个项目的 `ProjectSnapshot` 记录中。 - **`IndexService`** 维护内存中的第 1 层缓存，运行每次调用的 stat 指纹检查，并在发生漂移时从头开始重建。该指纹涵盖了每个加载的项目目录下所有 `.razor`、`.razor.cs`、`.razor.css`、`.cs`、`.csproj`、`_Imports.razor`、`Directory.Build.props` 和 `global.json` 的 `last-write-time` + `size`。 - **第 2 层 SQLite 缓存**（`Microsoft.Data.Sqlite`）在关闭时序列化行表，并在启动时在 18–22 毫秒内热加载它们。第 1 层和第 2 层使用相同的指纹格式；热加载在提供服务之前运行指纹检查，因此第 2 层绝不会静默地提供过时的行。 - **被动的 `FileSystemWatcher`** 仅作为快速路径提示。stat 指纹始终作为权威检查运行——监听器故障（网络共享、WSL 桥接、保存爆发、符号链接、挂起/恢复）不会导致过时的结果，只会导致较慢的路径。 - **工具边界 `try/catch`** 封装了每个 `[McpServerTool]` 方法主体。异常成为结构化错误行；没有任何东西会逃逸到 JSON-RPC 客户端。 在测试语料库上 10–16 秒的冷构建预算轻松满足了规范 §10 小于 30 秒的上限。锚定用例——`find_handler_bindings("WidgetExampleBase.HandleValueChanged")` 通过 Razor `#line` 指令解析回正确的 `.razor:line:column`——在每个关卡（冷 Roslyn 构建、第 2 层热加载和监听器禁用路径）都得到了验证。

标签：AI编程助手, API内省, Blazor, Claude Code, macOS, MCP Server, Model Context Protocol, .NET 10, Razor, Roslyn, SOC Prime, Syscall, Web开发, 事件处理绑定, 代码发现, 代码智能, 代码索引, 代码追踪, 大语言模型工具, 安全编辑, 开发工具, 开发者体验, 死代码检测, 源生成器, 组件图, 编译器API, 质量检查, 路由解析, 错误基检测, 静态代码分析