setup-mcp

配置 MCP

帮用户在 cosh 中配置 MCP 服务器。

用户经常从 Claude Desktop、VS Code、GitHub README 等地方复制 MCP 配置粘贴过来，但这些格式和 cosh 不兼容——多了 type 字段、顶层 key 不对、甚至 JSON 本身就有语法错误。不要试图把用户粘贴的内容直接塞给验证脚本赌运气，而是从用户的输入中理解他们要配什么，然后你自己按 cosh 的格式写出正确的配置。验证脚本只用来做最后的合并写入和校验。

cosh 的配置格式

cosh 不用 type 或 transport 字段——它看配置里有哪些字段来判断传输方式。这是最重要的一点，因为几乎所有外部来源的配置都会带一个 "type": "stdio" 之类的字段，而 cosh 不认这个。

三种传输方式，由字段决定：

本地进程（stdio）较少出现

{
  "mcpServers": {
    "mcp-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"],
      "env": { "DEBUG": "true" }
    }
  }
}

远程 HTTP——用户提到 streamableHttp 、streamable等字段就是 HTTP Streamable：

{
  "mcpServers": {
    "mcp-name": {
      "httpUrl": "https://mcp.example.com/v1",
      "headers": { "Authorization": "Bearer $MY_API_TOKEN" }
    }
  }
}

远程 SSE（旧版）—— 用户提供的 url 尾部是 /sse 字段就是 SSE：

{
  "mcpServers": {
    "mcp-name": {
      "url": "http://localhost:8080/sse"
    }
  }
}

其他可选字段（三种传输通用）：timeout、trust、includeTools、excludeTools。stdio 还可以用 cwd。

怎么做

1. 弄清用户要什么

用户的输入五花八门。可能是一段 JSON、一句"帮我配下 filesystem 的 MCP"、一个 npm 包名、甚至一张截图。不管输入是什么形式，你需要搞清楚三件事：

1. 用什么连接？ 如果用户提到了 npx/uvx/node/python/docker 这些命令，那就是 stdio。如果给了一个 URL，那是远程服务（HTTP 优先，除非用户明确说 SSE）。
2. 怎么认证？ 有些服务需要 API key 或 token。如果需要，密钥用 $VAR_NAME 的形式引用环境变量，别把真实密钥写进配置文件。
3. 叫什么名字？ 服务器需要一个标识名。通常可以从包名或 URL 推断出来，比如 @modelcontextprotocol/server-filesystem 就叫 filesystem。

示例 1 — 用户说"帮我配置 filesystem MCP"： → 你知道这是 npx -y @modelcontextprotocol/server-filesystem，问用户想暴露哪个目录，然后构建配置。

示例 2 — 用户粘贴了一段 Claude Desktop 的配置：

{"mcpServers": {"github": {"type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": {"GITHUB_TOKEN": "ghp_xxxx"}}}}

→ 从中提取有用信息：command 是 npx，args 是 ["-y", "@modelcontextprotocol/server-github"]，需要 GITHUB_TOKEN。忽略 type 字段。注意到 token 是明文的——改成 $GITHUB_TOKEN，提醒用户设置环境变量。

示例 3 — 用户给了一个 URL https://mcp.linear.app/sse 和一个 API key： → 用户给的是 URL，先确认是 HTTP 还是 SSE。路径里有 /sse 说明是 SSE，和用户确认后用 url 字段。

如果信息不够（比如不知道要连哪个服务，或者不确定认证方式），直接问用户。不要猜。

2. 写出配置 JSON

你自己构建，不要依赖脚本做格式转换。模板就这么简单：

stdio → {"mcpServers": {"<名称>": {"command": "...", "args": [...]}}} HTTP → {"mcpServers": {"<名称>": {"httpUrl": "..."}}} SSE → {"mcpServers": {"<名称>": {"url": "..."}}}

需要认证就加 headers（远程）或 env（本地）。

不要加 type、transport、disabled、alwaysAllow、scope 这些字段——cosh 不认，加了只会出问题。

3. 写入配置文件

用脚本合并写入，这样不会覆盖用户已有的其他配置：

python3 __SKILL_DIR__/scripts/validate_mcp.py '<json>' --merge <config_path>

配置文件位置：

• 默认写项目级：.copilot-shell/settings.json（当前工作目录下）
• 用户说"全局"或"所有项目"时写用户级：~/.copilot-shell/settings.json

脚本会自动处理目录创建、已有配置保留和新条目合并。如果脚本报错，看错误信息自己修正 JSON 后重试，不要把错误丢给用户。

4. 确认结果

写入后跑一下检查：

python3 __SKILL_DIR__/scripts/validate_mcp.py --check <config_path>

没问题就告诉用户配置完成，提醒他们：

• 用 /mcp 看服务器是否正常加载
• 如果配置里用了 $VAR_NAME，确保对应的环境变量已设置

处理各种来源的配置

用户粘贴的 JSON 几乎不可能直接用。常见情况：

• Claude Desktop 的配置带 "type": "stdio" → 提取 command/args/env，丢掉 type
• VS Code 的配置顶层是 "servers" 而不是 "mcpServers" → 把内容搬到 mcpServers 下
• GitHub README 可能带 "transport": "sse" → 提取 url/command，丢掉 transport
• 裸对象（没有 mcpServers 包裹）→ 加上名称和包裹
• 语法有错的 JSON（尾逗号、缺引号）→ 尝试理解意图，和用户确认关键信息后自己重写

核心原则：从用户输入中提取意图和关键参数，然后自己重建正确配置。