name: mcp-server-builder
mcp/server.ts 実装、.claude/mcp.json 追加、接続確認(tools/list + tools/call の実呼び出し)までが必要なときに使う。MCPサーバー実装だけで終わらせず、mcp.json 登録と動作検証まで完了させるためのスキル。
console.log ではなく console.error を使う(stdio干渉回避)。success: true/false の統一レスポンスを返す。? プレースホルダを使い、文字列連結で値を埋め込まない。mcp/server.tsmcp/schemas/index.tsmcp/utils/db.tspackage.json に mcp:start を追加。.claude/mcp.json にサーバーを追加。tools/list と主要 tools/call を実行。{project}/
├── mcp/
│ ├── server.ts
│ ├── schemas/
│ │ └── index.ts
│ └── utils/
│ └── db.ts
├── .claude/
│ └── mcp.json
└── package.json
.claude/mcp.json の基本形: references/config-mcp-json.json
.env.local を自動読込しないため、source が必要。env にシークレットを直接書かずに済む(コミット事故を避ける)。cwd を固定し、相対パス起動失敗を防ぐ。references/template-server.ts を参照。
mcp.json に書いたコマンドをそのまま実行してログ確認。
zsh -lc 'set -a; [ -f .env.local ] && source .env.local; set +a; npx tsx mcp/server.ts'
期待ログ:
Schema initializedMCP Server running on stdio@modelcontextprotocol/sdk の Client + StdioClientTransport で接続。tools/list で期待ツールが出るか確認。tools/call。success:false / error)を確認。/tmp に置くと Node のモジュール解決が壊れる場合がある。mcp.json の形式差異に注意。
.claude/mcp.json は通常 mcpServers。servers の場合がある。既存形式に合わせる。npx tsx mcp/server.ts 単体成功だけでは不十分。
tools/call まで通して初めて「登録後に使える」状態。mcp.json に直書きしない。
source .env.local 方式を優先。mcp/server.ts が起動する.claude/mcp.json に登録済みmcp.json のコマンドで起動確認済みtools/list + 主要 tools/call の実行確認済み.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 の場合がある。既存ファイルの形式を確認してから追記する