name: mcp-server-orchestrator description: 为AI代理工作流配置、部署和调试Model Context Protocol (MCP) 服务器。用于设置MCP服务器、调试连接问题、管理多服务器配置、集成Claude Desktop/Code/Cowork或设计自定义工具服务器。在MCP配置、工具服务器开发、Claude集成问题或代理基础设施设置时触发。 license: MIT

MCP 服务器编排器

管理用于AI驱动的开发工作流的MCP服务器基础设施。

MCP 架构概述

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   MCP 客户端    │────▶│   MCP 服务器     │────▶│   外部API       │
│ (Claude 等)     │◀────│  (工具提供者)    │◀────│  (服务)         │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                       │
         └───── JSON-RPC ────────┘

关键概念：

服务器：通过MCP协议提供工具、资源和提示
客户端：消费服务器能力（Claude Desktop、Claude Code等）
传输：通信层（stdio、SSE、WebSocket）

配置位置

客户端	配置文件	平台
Claude Desktop	`claude_desktop_config.json`	macOS：`~/Library/Application Support/Claude/`
		Windows：`%APPDATA%\Claude\`
Claude Code	`settings.json` 或 MCP 配置	项目级别或用户设置
Cline	`cline_mcp_settings.json`	VS Code 扩展设置

服务器配置架构

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "value"
      },
      "disabled": false
    }
  }
}

常见服务器类型

Python 服务器 (uvx)：

{
  "my-python-server": {
    "command": "uvx",
    "args": ["--from", "package-name", "server-command"]
  }
}

Node 服务器 (npx)：

{
  "my-node-server": {
    "command": "npx",
    "args": ["-y", "@scope/package-name"]
  }
}

本地开发服务器：

{
  "dev-server": {
    "command": "python",
    "args": ["-m", "my_server"],
    "env": {
      "DEBUG": "true"
    }
  }
}

故障排除工作流

连接问题

验证服务器独立启动：

# 测试 Python 服务器
python -m my_server

# 测试 Node 服务器
npx -y @scope/package-name

检查日志：
- Claude Desktop：~/Library/Logs/Claude/mcp*.log
- 查找 JSON-RPC 错误、连接超时

验证 JSON 配置：

python -c "import json; json.load(open('config.json'))"

常见修复：
- 使用绝对路径执行命令
- 确保依赖安装在正确环境
- 检查 API 密钥/环境变量是否设置
- 配置更改后重启客户端

认证问题

OAuth 流程： 确保重定向 URI 正确配置
API 密钥： 验证环境变量可被服务器进程访问
令牌刷新： 检查令牌存储位置和权限

构建自定义服务器

Python 服务器 (FastMCP)

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """AI的工具描述。"""
    return f"结果：{param}"

@mcp.resource("resource://my-data")
def get_data() -> str:
    """以资源形式提供数据。"""
    return "资源内容"

if __name__ == "__main__":
    mcp.run()

Node 服务器 (MCP SDK)

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-server", version: "1.0.0" }, {
  capabilities: { tools: {} }
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "my_tool",
    description: "工具描述",
    inputSchema: { type: "object", properties: { param: { type: "string" } } }
  }]
}));

const transport = new StdioServerTransport();
await server.connect(transport);

多服务器编排

模块化架构

按领域组织服务器：

{
  "mcpServers": {
    "filesystem": { "command": "...", "args": ["--allowed-dirs", "/projects"] },
    "database": { "command": "...", "env": { "DB_URL": "..." } },
    "api-integrations": { "command": "...", "env": { "API_KEYS": "..." } },
    "custom-tools": { "command": "python", "args": ["-m", "my_tools"] }
  }
}

服务器选择策略

将服务器视为合成器中的模块——根据工作流需求连接它们：

开发工作流： 文件系统 + git + 代码分析服务器
研究工作流： 网络搜索 + 文档 + 笔记服务器
数据工作流： 数据库 + 可视化 + 导出服务器

性能优化

延迟加载： 仅启用当前任务所需的服务器
缓存： 为昂贵操作实现响应缓存
超时调优： 为慢速外部API调整超时
连接池： 在数据库服务器中重用连接

参考

references/server-templates.md - 常见服务器类型的模板
references/debugging-guide.md - 详细的故障排除程序