mcp-server-setup

MCP 服务设置

这是严格的指南。 请严格遵守以下规则。

我们 devcontainer 设置中的 MCP 服务配置。post_create.sh 会将单个源文件分发给所有 Agent。

---

单一事实来源

MCP 服务只在 ~/.devcontainer-state/ai/mcp/servers.json 中定义（已加入 gitignore，包含凭据）。仓库中有一个已提交的模板：servers.json.template。

容器启动时，post_create.sh 会将此文件分发到：

Agent	目标位置	方式
Kiro CLI	~/.kiro/settings/mcp.json	复制
Claude Code	~/.claude/settings.json	将 mcpServers 合并到现有设置中
Amazon Q / Codex	${WORKSPACE_ROOT}/.amazonq/mcp.json	复制

VS Code / Copilot 是例外——.vscode/mcp.json 使用不同的格式（servers 键、${ENV_VAR} 引用），并已提交到仓库。请单独维护此文件。

---

源文件格式

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Kiro、Claude 和 Amazon Q 共用此格式。

---

VS Code 格式

顶层键不同，使用环境变量引用，而不是原始值：

{
  "servers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "ENV_VAR": "${ENV_VAR}"
      }
    }
  }
}

---

已知服务及其环境变量

请使用此处列出的确切环境变量名称。名称不匹配是最常见的设置失败原因。

Trello（mcp-server-trello）

TRELLO_API_KEY    — from https://trello.com/app-key
TRELLO_TOKEN      — NOT "TRELLO_API_TOKEN"
TRELLO_BOARD_ID   — optional, found in board URL

GitHub（@modelcontextprotocol/server-github）

GITHUB_PERSONAL_ACCESS_TOKEN  — or GITHUB_TOKEN

---

添加新的 MCP 服务

1. 在容器中手动测试服务

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | ENV_VAR=value timeout 5 npx -y <package-name> 2>/dev/null

预期结果：包含 result.serverInfo 的 JSON 响应。如果出现缺少环境变量的错误，说明变量名称有误——请检查服务的源代码或 README。

2. 添加到源文件

在主机上编辑 ~/.devcontainer-state/ai/mcp/servers.json。添加服务条目，并使用测试中确认的确切环境变量名称。

3. 重建容器或重新运行 post_create.sh

容器启动时会分发配置。请重建容器，或手动运行 post_create.sh。

4. 单独更新 VS Code 配置

如果使用 Copilot，请在项目仓库的 .vscode/mcp.json 中添加该服务，采用 servers 格式并使用 ${ENV_VAR} 引用。

---

Devcontainer 注意事项

• 全局 npm 软件包会在重建后保留，因为它们位于 ~/.cache/npm-global（缓存挂载点）中。
• 凭据保存在 devcontainer-state 中（已加入 gitignore）。它们绝不会出现在项目仓库中——.amazonq/ 已加入 gitignore，VS Code 使用环境变量引用。
• 编辑一次，适用于所有 Agent——只需修改一次 servers.json 并重建，Kiro、Claude 和 Amazon Q 都会获得更新。

---

故障排除

症状	原因	解决方法
找不到服务	未安装软件包	npm install -g <package>
出现“missing env var”错误	环境变量名称错误	检查“已知服务”部分；手动测试
服务已启动，但 Agent 无法连接	配置位于错误的文件中或格式错误	检查 mcpServers 与 servers 键
重建后配置丢失	主机上没有 servers.json	检查 ~/.devcontainer-state/ai/mcp/servers.json 是否存在
Agent 看不到配置更改	会话过期	重启 Agent 会话
容器启动时出现 MCP 警告	尚未创建 servers.json	运行 cp servers.json.template servers.json，然后填写凭据

---

渐进式改进

如果开发者纠正了此技能本应避免的行为，请建议对此技能进行具体修订，以防止今后再次出现同样的纠正。