---

name: mcp-server-builder description: MCPサーバーの実装と mcp.json 登録を一気通貫で行う。mcp/server.ts 実装、.claude/mcp.json 追加、接続確認（tools/list + tools/call の実呼び出し）までが必要なときに使う。

mcp-server-builder

MCPサーバー実装だけで終わらせず、mcp.json 登録と動作検証まで完了させるためのスキル。

使う場面

• 「MCPサーバーを構築して登録して」
• 「mcp.json に追加して動作確認して」
• 「ツール呼び出しまで検証して」

基本方針

• 実装、登録、検証を必ずセットで実施する。
• console.log ではなく console.error を使う（stdio干渉回避）。
• 全ツールで success: true/false の統一レスポンスを返す。
• SQLは ? プレースホルダを使い、文字列連結で値を埋め込まない。

最短ワークフロー

1. 仕様確認
   • ツール一覧、入出力スキーマ、DB種別、必要環境変数を確定。
2. 実装
   • mcp/server.ts
   • mcp/schemas/index.ts
   • mcp/utils/db.ts
   • package.json に mcp:start を追加。
3. 登録
   • プロジェクトの .claude/mcp.json にサーバーを追加。
4. 検証
   • 起動確認（設定したコマンドをそのまま実行）
   • MCPクライアントから tools/list と主要 tools/call を実行。
5. 後始末
   • 一時スクリプト削除
   • 検証用のデータを残す場合は明示する。

推奨ディレクトリ構成

{project}/
├── mcp/
│   ├── server.ts
│   ├── schemas/
│   │   └── index.ts
│   └── utils/
│       └── db.ts
├── .claude/
│   └── mcp.json
└── package.json

登録テンプレート（Claude Code / Codex向け）

.claude/mcp.json の基本形: references/config-mcp-json.json

この形式を推奨する理由

• MCPプロセスは .env.local を自動読込しないため、source が必要。
• env にシークレットを直接書かずに済む（コミット事故を避ける）。
• cwd を固定し、相対パス起動失敗を防ぐ。

実装テンプレート（要点）

references/template-server.ts を参照。

検証手順（必須）

1) 起動確認

mcp.json に書いたコマンドをそのまま実行してログ確認。

zsh -lc 'set -a; [ -f .env.local ] && source .env.local; set +a; npx tsx mcp/server.ts'

期待ログ:

• Schema initialized
• MCP Server running on stdio

2) プロトコル確認（tools/list + tools/call）

• @modelcontextprotocol/sdk の Client + StdioClientTransport で接続。
• tools/list で期待ツールが出るか確認。
• 主要ツールを最低1回ずつ tools/call。
• エラー時はレスポンス本文（success:false / error）を確認。

実運用TIPS（今回の反映）

• 一時検証スクリプトは プロジェクト配下 に置く。
  • /tmp に置くと Node のモジュール解決が壊れる場合がある。
• mcp.json の形式差異に注意。
  • .claude/mcp.json は通常 mcpServers。
  • エディタ設定ファイル側は servers の場合がある。既存形式に合わせる。
• npx tsx mcp/server.ts 単体成功だけでは不十分。
  • 実際に MCP Client で tools/call まで通して初めて「登録後に使える」状態。
• 秘密情報は mcp.json に直書きしない。
  • source .env.local 方式を優先。

完了チェックリスト

• mcp/server.ts が起動する
• 全ツールの Zod スキーマがある
• 全ツールが統一レスポンス（成功/失敗）を返す
• .claude/mcp.json に登録済み
• mcp.json のコマンドで起動確認済み
• tools/list + 主要 tools/call の実行確認済み
• 一時検証ファイルを削除済み

⚠️ よくある落とし穴

• MCPはアプリ本体と別プロセス: アプリ側の環境初期化（.env 自動読込等）に依存しない。source .env.local を起動コマンドに含めないと環境変数が空になる
• console.log でstdio干渉: MCPはstdioでJSON-RPCを通信するため、console.log がプロトコルを破壊する。デバッグ出力は必ず console.error を使う
• /tmp に検証スクリプトを置くとモジュール解決が壊れる: node_modules の解決パスがプロジェクト外になる。一時スクリプトはプロジェクト配下に置く
• npx tsx mcp/server.ts 単体起動だけでの検証不足: プロセスが起動しても、MCPクライアントから tools/call を実際に呼ぶまで「使える状態」とは言えない。スキーマ不一致やランタイムエラーは呼び出して初めて発覚する
• mcpServers と servers のキー名混在: .claude/mcp.json は通常 mcpServers、エディタ設定側は servers の場合がある。既存ファイルの形式を確認してから追記する
• 既存の未コミット変更を巻き込む: MCP関連ファイルだけをコミットすべきところで、不要なファイルまでステージングしないよう注意