内容
<!-- mcp-name: io.github.Byggarepop/dotnet-mcp-orchestrator -->
# McpOrchestrator — .NET 原生 MCP 编排器
[](https://www.nuget.org/packages/McpOrchestrator)
[](https://www.nuget.org/packages/McpOrchestrator)
[](LICENSE)
**每个您连接的 MCP 服务器在代理执行任何操作之前都会消耗上下文。 它的工具清单在每次对话中都位于提示中。 连接足够多的服务器，您将花费数万个代币仅仅用于描述代理尚未使用的工具。**
McpOrchestrator 在您的代理和所有其他服务器之间放置一个服务器。 它按需加载下游工具清单，而不是预先加载，这样代理始终保持上下文扁平，无论您添加多少服务器。 它是一个**纯中继** — 编排器从不解释代理的输入。
## 测量影响
在真实的工作场所 MCP 设置中运行，使用 Copilot CLI 的 `/usage` 命令测量：
| | 上下文中的代币 |
| --- | --- |
| MCP 直接连接（预先加载清单） | **17,900** |
| 相同的 MCP 通过 McpOrchestrator | **1,400** |
| **减少** | **~13 倍** |
节省的代币数量随着服务器数量的增加而增加：您连接的 MCP 越多，避免的前期清单成本就越高。 使用下面的 `profile` 命令测量您自己的设置 — 无需安装，不会更改任何内容。
## 工作原理
一个代理连接到这个单一服务器；它持有与许多下游 MCP 服务器（JIRA，代码生成，文件系统服务器等）的连接，并将代理的调用中继到正确的服务器 — 因此您使用 **一个代理 + 一个 MCP** 而不是为每个工具集切换代理。 下游工具通过三个元工具按需发现：
`list_capabilities` → `discover_tools("Tokensaver")` → `route("Tokensaver", "outline_c_sharp_file", { … })`
## 适用场景
这里的价值是 **尽可能小的表面**：一个纯粹的 stdio 中继，作为一个单一的 .NET 工具（或 AOT 二进制文件，无运行时）安装，没有任何需要读取的内容，只有路由路径。渐进式发现并不是独一无二的 — 最接近的 .NET 替代品 [mcp-aggregator](https://github.com/MarimerLLC/mcp-aggregator) 做了更多的事情（MCP 旁边的 REST API，运行时服务器注册，凭证管理），因此如果您想要一个网关，请选择它。 如果您想要一个尽可能精简的中继，没有额外的运行或推理内容，请选择此选项。 它故意省略了网关（如 Kong 或 Envoy）提供的企业层 — 认证，多租户，速率限制。
👉 **完整文档：** [`McpOrchestrator/README.md`](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md) — 它是如何工作的，设置，添加新的 MCP，配置参考，测试和故障排除。
## 这是适合您的工具吗？用一条命令检查 — 无需安装
在更改任何内容之前，看看编排器实际上可以为您节省多少代币。 `cd` 进入一个已经包含 MCP 配置的文件夹，并运行 `profile` 命令，**无需路径** — 它会自动检测配置，连接到每个 stdio 服务器一次，然后打印代币节省 — **不会安装任何内容，也不会更改任何文件** （需要 .NET SDK）：
```bash
cd ~/my-project # 一个包含 .mcp.json / .vscode/mcp.json / Cursor 配置的文件夹
dotnet tool execute McpOrchestrator profile
```
它会选取它找到的第一个配置（`orchestrator.config.json`，`.mcp.json`，`.vscode/mcp.json`，`.cursor/mcp.json`，`mcp.json`）。 也可以选择显式指向一个配置 — 在配置位于其他位置或您想确保读取哪个配置时很有用：
```bash
dotnet tool execute McpOrchestrator profile --host-config <您的 .mcp.json / Cursor / Claude Desktop 配置>
```
远程（`http`/`sse`）服务器无法中继，将被跳过；其他所有内容都将在内存中进行测量。 如果数字看起来不错，请按照下面的方法设置 — 如果不，请完成，无需清理。 （完整详细信息和本地构建变体：[性能分析指南](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#profiling-token-economics-profile).）
## 快速入门
从现有的 MCP 设置到通过编排器运行的三个步骤。
### 1. 安装
.NET 工具（需要 **.NET SDK** — `dotnet tool` 与 SDK 捆绑在一起，而不是运行时）将 `mcp-orchestrator` 命令放在您的 PATH 上：
```bash
dotnet tool install --global McpOrchestrator
```
> 没有 .NET SDK？ 从 [GitHub Releases](https://github.com/Byggarepop/dotnet-mcp-orchestrator/releases) 下载独立的 Native-AOT 二进制文件，解压它，并将二进制文件的绝对路径用作命令（将其传递给下面的 `init` 命令 `--command <path>`）。 它不需要任何 .NET。
### 2. 初始化
将 `init` 命令指向现有的 MCP 主机配置 — `.mcp.json`（Claude Code，Visual Studio），`.vscode/mcp.json`（VS Code），或 Cursor / Claude Desktop 配置：
```bash
mcp-orchestrator init path/to/.mcp.json
```
它将每个 stdio 服务器提升到生成的 `orchestrator.config.json`（每个功能一个），备份原始文件到 `.bak`，然后重写它以启动 **仅** 编排器 — 通过 `MCP_ORCHESTRATOR_CONFIG` 指向新目录。 远程（http/sse）服务器无法通过 stdio 中继，因此它们保持不变。 （添加 `--dry-run` 以预览两个文件。）
### 3. 添加摘要文本
打开生成的 `orchestrator.config.json` 文件，并将每个功能的 `TODO` `summary` 替换为代理应该使用它的单行描述 — 该行是代理读取以路由的内容。 然后重启您的 MCP 主机。
就这样。 代理现在看到三个元工具，流程为 `list_capabilities` → `discover_tools("…")` → `route("…", "<tool>", { … })`.
> 从头开始，没有 MCP 配置？ 请参阅[手动设置](#手动设置)以获取 `init` 命令生成的两个文件。 日志会镜像到 `~/.mcpOrchestrator/orchestrator.log`.
## 手动设置
`init` 命令自动化了此过程；如果您没有主机配置或想要完全控制，请手动执行。 **两个配置文件** 涉及：
- **主机配置** — 代理现有的 MCP 文件：`.mcp.json`（Claude Code 和 Visual Studio）或 `.vscode/mcp.json`（VS Code）。 您在此处添加编排器作为服务器。
- **编排器配置** — 您创建的新文件（例如 `orchestrator.config.json`），由 `MCP_ORCHESTRATOR_CONFIG` 环境变量指向。 它列出了下游 MCP 服务器。
### 1. 将编排器添加到主机配置（`.mcp.json` / `.vscode/mcp.json`）
代理只会看到 **这个服务器**:
```jsonc
{
"servers": {
"orchestrator": {
"type": "stdio",
// 工具放在您的 PATH 上的命令 — `mcp-orchestrator`，而不是包
// id `McpOrchestrator`. （或 AOT 二进制文件的绝对路径。）
"command": "mcp-orchestrator",
"args": [],
"env": {
// 指向您在步骤 2 中创建的编排器配置的绝对路径：
"MCP_ORCHESTRATOR_CONFIG": "<ABSOLUTE-PATH-TO>/orchestrator.config.json"
}
}
}
}
```
### 2. 在编排器配置中列出下游服务器（`orchestrator.config.json`）
这是您指向 `MCP_ORCHESTRATOR_CONFIG` 的文件。 每个条目都是代理可以路由到的一个功能；`command`/`args`/`env` 是如何启动下游 MCP 的。 使用普通的绝对路径 — 您不需要任何特殊语法。 可选地，如果您需要，可以替换 `${...}` 占位符：`${CONFIG_DIR}`（此配置所在的文件夹）和任何 `${ENV_VAR}`（进程环境变量，例如 API 密钥）：
```jsonc
{
"capabilities": [
{
"name": "files",
"summary": "在本地机器上读写文件。",
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "<ABSOLUTE-PATH-TO>/projects"],
"connectTimeoutSeconds": 30
},
{
"name": "Tokensaver",
"summary": "在使用 .NET 时减少代币消耗（大纲/最小化/跟踪 DI）。",
"enabled": true,
"transport": "stdio",
"command": "dotnet",
"args": ["tool", "execute", "TokenSaver.Mcp", "--yes"],
"env": {
"TOKENSAVER_API_URL": "https://tokensavermcp.com",
"TOKENSAVER_UPDATE_INTERVAL_MINUTES": "0"
}
}
]
}
```
重启 MCP 主机以使其生效。
代理现在看到三个元工具，流程为 `list_capabilities` → `discover_tools("Tokensaver")` → `route("Tokensaver", "outline_c_sharp_file", { … })`.
> **注意。** `summary` 是代理路由的内容。 `instructions` 是向代理显示的可选使用提示 — 除非某个功能需要它，否则请省略它。 `env`/`workingDirectory` 每个功能都是可选的。 配置文件支持 `//` 注释。 还有一个 `${SOLUTION_DIR}` 占位符，但您几乎不需要它 — 它解析为此存储库的解决方案根目录，仅存在于存储库内的示例配置可以找到相邻的演示服务器。 对于您自己的设置，请使用绝对路径，`${CONFIG_DIR}` 或 `${ENV_VAR}` 代替。 日志会镜像到 `~/.mcpOrchestrator/orchestrator.log`. 有关每个字段，包装和故障排除的详细信息，请参阅 [完整文档](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md)。
> **测试本地构建？** `pack-local.ps1` 将项目打包为固定 `9.9.9-dev` 版本的 `nupkg/local-feed`；然后 `init --dev-feed nupkg/local-feed` 将主机连接到从该源运行编排器的位置，以便它始终运行您最新的本地代码。 重新运行 `pack-local.ps1` 并重启主机以应用更改。
## 项目
| 项目 | 角色 |
| --- | --- |
| `McpOrchestrator` | 编排器：MCP 服务器到代理，MCP 客户端到下游服务器。 约 1.4 MB 工具。 |
| `McpOrchestrator.DemoMcp` | 示例下游 MCP（ `--persona jira` / `codegen` / `diag`）。 |
| `McpOrchestrator.SmokeTest` | 控制台 MCP 客户端，驱动编排器端到端。 |
| `McpOrchestrator.Tests` | xUnit 套件：单元测试 + 集成测试 + 端到端测试。 |
## 三个工具
`list_capabilities` → `discover_tools` → **`route`** （您选择工具并填写参数）。 编排器是一个 **快递员，而不是解释器**：它转发代理发送的确切内容 — 代理进行思考。 有关详细信息，请参阅 [完整文档](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md)。
