内容
# 语义 .NET MCP
**基于 Roslyn 的 AST 代码智能，通过 MCP 提供服务。**
您的 AI 代理读取 C# 代码的方式就像初级开发人员阅读小说一样：从左到右，从上到下，希望上下文能尽快出现。语义 .NET MCP 解决了这个问题。它将您的 .NET 解决方案加载到 Roslyn 的语义编译器中，构建完整的符号索引，并通过 [模型上下文协议](https://modelcontextprotocol.io/) 将整个代码库暴露为可查询的图。七种工具，四种资源，一个提示，礼貌地告诉您的代理停止使用 `read_file`。
结果：您的代理获得类型解析、调用图、继承链和跨项目引用。不是 grep，不是字符串匹配。实际的编译器级代码理解。
构建于 .NET 10 / C# 14。输出默认为 [TOON](docs/toon-format.md)（Token Optimized Object Notation），它减少了约 60% 的 JSON 标记。
## Roslyn 优势（这不公平，我们不道歉）
让我们准确地说明一下大多数代理项目都忽略的事情。
大多数语言工具生成抽象语法树（AST）：结构解析。节点和标记。括号表达式和标识符列表。有用，但不像电话簿在你需要了解一个城市时的用处。AST 告诉你**写了什么**，但不告诉你它的**含义**。
Roslyn 不止于语法。Roslyn 生成完整的**语义模型**：一个包含每个已解析类型绑定、每个重载解析、每个泛型类型参数推断、每个隐式转换、每个符号在每个项目边界上的可访问性的 `Compilation` 对象。当你问 Roslyn “`var x = GetOrder()` 解析为什么？”时，它不会猜测。它告诉你是 `Task<Order?>` 因为 `GetOrder()` 返回 `Task<Order?>` 因为接口契约在三个项目之外规定了它。它遍历整个依赖图。它解析 `<inheritdoc/>` 链。它知道在六种类型实现 `IDisposable` 时你指的是哪个 `Dispose()`。
这不是 AST。这是一个**编译器即服务**。而其他主流语言生态系统都没有类似的东西，它如此易用、快速、正确。
Python 有 `ast.parse()`。它给你一个语法树。没有类型信息。没有跨模块解析。没有重载消歧。想要类型？单独运行 mypy，解析其输出，希望版本匹配。
TypeScript 有 TS 编译器 API。值得肯定：它是最近的竞争对手。但它为每个项目重新实现模块解析，从头开始，卡在 monorepo 边界上，而 `ts.Program` 对象是可变的，不适合并发访问。祝你好运，在不破坏状态的情况下提供并发查询。
Java 有 Eclipse JDT 和 javac 树。两者都需要运行的 JVM，都没有公开干净的 `Compilation` 快照，增量重编译是一个研究项目，而不是一个发布的特性。
Rust 有 `rust-analyzer`。优秀的工程，真正令人印象深刻的增量计算。但 `rust-analyzer` 是一个 IDE 服务器，而不是一个库。你不嵌入它；你通过 LSP 与它通信。而 LSP 是为编辑器设计的，而不是代理。协议没有“给我工作区中所有调用此函数的调用者，返回一个结构化响应”的概念。
Roslyn 从一开始就设计为一个可嵌入的编译器平台。并发的不可变快照。每个文件的延迟语义模型计算。增量重新解析。完整的跨项目符号解析。所有这些都作为 NuGet 包提供，您可以 `dotnet add` 并从自己的进程调用。
**语义 .NET MCP 通过 MCP 将整个语义模型暴露给编码代理。** 不是带有启发式类型猜测的语法树。实际编译器的代码理解。每个已解析类型。每个绑定。每个跨项目引用。每个泛型实例。
这就是为什么 C# 和 .NET 是代理开发的最佳选择。不是因为语法偏好或运行时基准测试。因为编译器本身就是一个可查询的、可嵌入的、并发安全的语义数据库。没有其他生态系统免费提供此功能。优势是结构性的，它随着代码库的大小而增加：您的解决方案越大、越复杂，代理“读取文本文件”和“查询语义模型”之间的差距就越大。
## 问题，陈述简单
AI 编码代理将源代码作为纯文本消耗。它们看到字符。Roslyn 看到符号、作用域、绑定和关系。两种视图之间的差距是 bug、幻觉和浪费的上下文窗口的根源。
考虑当代理需要理解 `OrderService.CreateOrder` 时会发生什么：
| 方法 | 标记 | 代理学习的内容 |
| --- | --- | --- |
| 在 `OrderService.cs` 上 `read_file` | ~800 | 原始文本。没有调用者。没有接口契约。希望代理推断出其余部分。 |
| 在 4 个相关文件上 `read_file` | ~3,000+ | 更多文本。仍然没有解析的类型，没有调用图，没有继承链。 |
| `ast_details symbol=OrderService.CreateOrder` | ~140 | 完整的签名，解析的类型，文档注释，位置，语义上下文。完成。 |
这不是一个舍入误差。这是 20 倍的标记成本降低，但信息更丰富。架构是权衡取舍。这个成本对你来说是零。
## 关于“Vibe Coding”（一个简短的、必要的令人不愉快的话题）
有一种时尚的运动，人们输入提示，接受 LLM 生成的代码，然后在没有阅读的情况下将其交付。他们称之为“vibe coding”。他们带着自豪的态度谈论它。他们有播客。
让我直接地说：vibe coding 不是工程。它甚至不是编程。它是将你的判断外包给统计模型，然后对结果表现出自信。它相当于在不阅读你不懂的语言的合同的情况下签署合同，因为感觉还不错。
那些进行 vibe coding 的人交付他们无法解释的 `O(n³)` 循环。他们引入他们无法识别的安全漏洞。他们创造他们无法服务的技術债务，因为他们不了解资产。当他们的 vibe-coded 应用程序在凌晨 3 点出现故障时，他们会打开一个新的聊天会话，并在故障的基础上进行 vibe-code 修复。
语义 .NET MCP 存在的理由恰恰相反。它存在是因为代理应该比文本扫描允许的更好地理解代码，而不是更差。整个架构都是围绕给予代理与高级工程师在多年使用代码库中获得的相同的语义理解而构建的：类型关系、调用图、继承链、可访问性边界、已解析的泛型。当代理拥有这种理解时，它会编写更好的代码。它会发现自己的错误。它知道在进行更改之前什么会破坏下游。
Vibe 编码者希望代理快速行动。我们希望代理行动正确。没有理解的速度只是大规模生成 bug。
如果您正在使用 Semantic .NET MCP 构建，您正在为使用编译器级语义上下文推理代码的代理构建。您正在为审查、测试和理解交付内容的工程团队构建。您正在为认为“在我机器上运行”是一个对话的开始，而不是结束的人构建。
如果您正在寻找帮助您更快地接受 LLM 输出而无需阅读它的工具，您是在错误的存储库中。我们祝你好运。你会需要的。
## 需求
- [.NET 10 SDK](https://dotnet.microsoft.com/download) 或更高版本
- 工作目录（自动发现）或显式指定的 .NET 解决方案（`.sln` 或 `.slnx`）
- 一台具有足够 RAM 的机器，以便 Roslyn 完成其工作（推荐 16GB 以上，适用于超过 500 个文件的解决方案）
## 入门指南
### 安装
**选项 1：安装为全局工具（推荐）**
```bash
# 克隆、构建、打包和安装
git clone https://github.com/dotnet-semantic-mcp/dotnet-semantic-mcp.git
cd dotnet-semantic-mcp
dotnet build -c Release
dotnet pack src/DotnetSemanticMcp -c Release -o ./nupkg
dotnet tool install --global --add-source ./nupkg DotnetSemanticMcp
# 验证安装
dotnet-semantic-mcp --version
```
**选项 2：通过 dotnet run 运行**
```bash
dotnet build
dotnet test # 265 个测试。全部通过。
```
### CLI 用法
```bash
# 从包含 .NET 解决方案的任意目录
cd /path/to/your/solution
# 全局工具（安装后）
dotnet-semantic-mcp status
dotnet-semantic-mcp search "CreateOrder"
dotnet-semantic-mcp map --map-type solution
dotnet-semantic-mcp details --target OrderService.CreateOrder
# 或通过 dotnet run
dotnet run --project /path/to/dotnet-semantic-mcp/src/DotnetSemanticMcp -- search "CreateOrder"
```
查看 [完整的 CLI 参考](docs/usage/cli.md) 以获取所有命令。
### MCP 服务器模式
在您的 AI 客户端中配置（[完整设置指南](docs/usage/mcp-setup.md)）：
**使用全局工具：**
```json
{
"mcpServers": {
"ast": {
"command": "dotnet-semantic-mcp",
"cwd": "/path/to/your/repo"
}
}
}
```
**使用 dotnet run：**
```json
{
"mcpServers": {
"ast": {
"command": "dotnet",
"args": ["run", "--no-build", "--project", "/path/to/dotnet-semantic-mcp/src/DotnetSemanticMcp"],
"cwd": "/path/to/your/repo"
}
}
}
```
> `cwd` 设置工作目录 — 服务器从那里递归发现 `.sln`/`.slnx` 文件。VS Code 扩展可以使用 `"cwd": "${workspaceFolder}"`。
> 解决方案文件在工作目录中**递归**自动发现（跳过 `bin`、`obj`、`node_modules`、`.git` 等）。所有找到的 `.sln`/`.slnx` 文件都被加载 — 不需要 `--solution` 标志。要覆盖：传递 `--solution path.sln` 或设置 `DotnetSemanticMcp:SolutionPath`。
> 📖 查看 [入门指南](docs/getting-started.md) 以获取完整的演练。
## MCP 表面积
### 工具（v1.0 — 核心分析）
| 工具 | 它做什么 |
| --- | --- |
| [`ast_search`](docs/specs/tools-and-resources.md#31-ast_search--find-symbols-by-namepattern) | 按名称、模式或通配符查找符号。索引支持，100 毫秒以下。 |
| [`ast_map`](docs/specs/tools-and-resources.md#32-ast_map--structural-visualization) | 结构映射：解决方案、项目、命名空间、类型、方法、文件。 |
| [`ast_details`](docs/specs/tools-and-resources.md#33-ast_details--deep-inspection) | 符号的完整 AST：成员、文档注释、解析类型、流分析。 |
| [`ast_chunk`](docs/specs/tools-and-resources.md#34-ast_chunk--source-retrieval-by-location) | 按文件 + 行范围检索源代码。用于精确语法的逃生阀。 |
| [`ast_references`](docs/specs/tools-and-resources.md#35-ast_references--reference--call-graph-queries) | 调用图：`callers_of`、`callees_of`、`references_to`。跨项目。 |
| [`ast_hierarchy`](docs/specs/tools-and-resources.md#36-ast_hierarchy--type-hierarchy-queries) | 类型层次结构：`implementations_of`、`base_types_of`、`overrides_of`、`extensions_for`。 |
| [`ast_diagnostics`](docs/specs/tools-and-resources.md#37-ast_diagnostics--code-health) | Roslyn 编译器诊断。警告、错误、代码分析。 |
### 工具（v2.0 — 扩展分析）
| 工具 | 它做什么 |
| --- | --- |
| [`ast_dependencies`](docs/specs/tools-and-resources.md#38-ast_dependencies--project-dependency-analysis) | 项目依赖图、NuGet 引用、循环检测、构建顺序。 |
| [`ast_attributes`](docs/specs/tools-and-resources.md#39-ast_attributes--attributedecorator-queries) | 查询属性/装饰器：查找用法、获取符号上的属性、按类别分组。 |
| [`ast_diff`](docs/specs/tools-and-resources.md#310-ast_diff--semantic-code-comparison) | 语义代码比较，带有破坏性变更检测。由 DiffPlex 驱动。 |
| [`ast_diff_unified`](docs/specs/tools-and-resources.md#311-ast_diff_unified--generate-unified-diff) | 生成统一的 diff 输出（类似 git 格式）。 |
### 资源（v1.0）
| URI | 描述 |
| --- | --- |
| `ast:///solution/map` | 解决方案拓扑：项目、依赖项、框架 |
| `ast:///project/{name}/map` | 项目级类型映射 |
| `ast:///file/{path}` | 文件级声明摘要 |
| `ast:///workspace/status` | 加载进度、就绪状态、按项目状态 |
### 提示（v1.0）
| 提示 | 目的 |
| --- | --- |
| `use_ast_for_code_reading` | 训练代理使用 AST 工具代替 `read_file` |
> 📖 完整的工具合约、参数和示例：[工具和资源规范](docs/specs/tools-and-resources.md)
> 📖 推荐的工作流：[工作流模式](docs/usage/workflow-patterns.md)
## 架构
两种操作模式，底层使用相同的引擎：
| 模式 | 传输 | 生命周期 |
| --- | --- | --- |
| **MCP 服务器** | stdio | 持久的。文件监视器。通过快照隔离的并发查询。 |
| **CLI** | stdout | 一次性的。加载、编译、查询、打印、退出。 |
```
Program.cs ─── 模式检测
├── MCP 模式 ──→ 工具/ + 资源/ + 提示/
└── CLI 模式 ──→ Cli/CliRunner.cs
↓
查询/QueryEngine.cs
↓
工作区/WorkspaceManager.cs ──→ Roslyn MSBuildWorkspace
↓
投影/ ──→ TOON（默认）或 JSON
```
Roslyn `Compilation` 对象是不可变的。查询在同一个快照上并发运行。文件更改会生成新的 `Compilation` 并原子地交换。没有锁。没有撕裂读取。
> 📖 完整的架构深入解析：[架构](docs/architecture.md)
> 📖 并发模型、快照策略、依赖注入：[运行时行为规范](docs/specs/runtime-behavior.md)
## 路线图
**v1.0** ✅ **已发布**：七种工具，四种资源，一个提示，265 个测试。只读分析。CLI 模式。全局 dotnet 工具打包。基础。
**v2.0** ✅ **已发布**：四种新工具，全部只读：
- `ast_dependencies` — 项目依赖图、循环检测、NuGet 版本分析
- `ast_diff` — 语义代码比较与 DiffPlex 集成（理解破坏性与美观变化）
- `ast_diff_unified` — 生成统一的 diff 输出，类似 git 格式
- `ast_attributes` — 查询装饰器/注解，用于依赖注入、API、序列化理解
**v3.0 — 扩展分析** 📋 **计划中**：仍然只读，外部源访问：
- `ast_complexity` — 圈复杂度/认知复杂度指标、热点分析
- `ast_sourcelink` — 通过 SourceLink 解析 NuGet 包的源代码
- `ast_decompile` — 关闭源代码依赖的 IL 反编译（ILSpy）
**v4.0 — 代码修改** 🔮：只读约束解除，谨慎：
- Git 集成 FIRST（自动提交、撤销、分支）作为安全网
- `ast_rename` — 解决方案范围内的重命名（Roslyn 的成熟 API）
- `ast_add_member` — 向类添加方法/属性
- 稍后：`ast_overwrite_member`、`ast_delete_member`（需要成熟的 Git 集成）
> 📖 v2/v3 工具的详细规范：[v2-v3 工具规范](docs/specs/v2-v3-tools.md)
## 文档
### 指南
| 文档 | 它涵盖的内容 |
| --- | --- |
| [入门指南](docs/getting-started.md) | 先决条件、安装、MCP 和 CLI 快速入门 |
| [MCP 设置](docs/usage/mcp-setup.md) | 客户端配置，适用于 Claude Desktop、VS Code 和其他 MCP 客户端 |
| [CLI 参考](docs/usage/cli.md) | 所有 8 个子命令、选项、管道、脚本 |
| [工作流模式](docs/usage/workflow-patterns.md) | 渐进式披露、调查流程、现实世界场景 |
| [配置](docs/configuration.md) | 所有设置、环境变量、每种模式的行为 |
| [TOON 格式](docs/toon-format.md) | 语法规则、转换管道、JSON 比较、示例 |
| [架构](docs/architecture.md) | 层、组件、数据流、并发、依赖注入、项目结构 |
| [故障排除](docs/troubleshooting.md) | 常见问题、错误代码、诊断步骤、解决方案 |
### 规范
| 文档 | 它涵盖的内容 |
| --- | --- |
| [概念规范](docs/specs/conceptual.md) | 问题、愿景、架构概述、范围、设计决策日志 |
| [工具和资源](docs/specs/tools-and-resources.md) | 完整的工具合约：输入、输出、验证、分页、注释 |
| [v2-v3 工具规范](docs/specs/v2-v3-tools.md) | 即将推出的零风险工具的详细规范：依赖项、差异、属性、复杂性、源链接、反编译 |
| [数据模型](docs/specs/data-models.md) | 错误模型、源位置、输出模式、JSON→TOON 映射 |
| [运行时行为](docs/specs/runtime-behavior.md) | 并发、启动生命周期、增量更新、内存、安全 |
| [实现](docs/specs/implementation.md) | TOON 语法、配置参考、CLI 规范、类图、依赖注入注册 |
| [测试](docs/specs/testing.md) | 测试策略、夹具设计、示例解决方案、覆盖率目标 |
## 许可证
查看 [LICENSE](LICENSE)。
