mcp-server-setup

MCP サーバーのセットアップ

これは厳格なガイドラインです。 これらのルールに正確に従ってください。

devcontainer セットアップにおける MCP サーバーの設定です。単一のソースファイルが post_create.sh によってすべてのエージェントに配布されます。

---

唯一の信頼できる情報源

MCP サーバーは ~/.devcontainer-state/ai/mcp/servers.json で一度だけ定義します（gitignore 対象で、認証情報が含まれます）。コミット済みのテンプレートは servers.json.template にあります。

コンテナの起動時に、post_create.sh がこのファイルを次の場所に配布します。

エージェント	配布先	方法
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 は環境変数参照を使用します。
• 一度の編集ですべてのエージェントに反映 — servers.json を一度変更して再ビルドすれば、Kiro／Claude／Amazon Q のすべてに更新が適用されます。

---

トラブルシューティング

症状	原因	対処方法
サーバーが見つからない	パッケージがインストールされていない	npm install -g <package>
「missing env var」エラー	環境変数名が間違っている	既知のサーバーのセクションを確認し、手動でテストする
サーバーは起動するが、エージェントが接続できない	設定ファイルまたは形式が間違っている	mcpServers キーと servers キーのどちらかを確認する
再ビルド後に設定が見つからない	ホストに servers.json がない	~/.devcontainer-state/ai/mcp/servers.json が存在することを確認する
エージェントに設定変更が反映されない	セッションが古い	エージェントのセッションを再起動する
コンテナ起動時に MCP の警告が出る	servers.json がまだ作成されていない	cp servers.json.template servers.json を実行し、認証情報を入力する

---

継続的な改善

このスキルで防げるはずの動作を開発者が修正した場合、同じ修正が今後必要にならないよう、このスキルへの具体的な変更を提案してください。