MCPサーバー開発(TypeScript)

目的

公式TypeScript SDKを使用してMCPサーバーをビルドするための繰り返し可能で文書化されたワークフローを提供します。これにより、エージェントと開発者はアドホックな検出なしにツール、リソース、プロンプトを追加できます。このワークフローに従い、要件から動作確認可能なサーバー(StdioまたはStreamable HTTP)を構築します。このスキルはMCPスペック2025-11-25に準拠しており、ツール、リソース、プロンプト、およびサーバーユーティリティ(ロギング、完了、ページネーション)に対応しています。

ワークフロー チェックリスト

• ステップ1:要件の発見
  • references/mcp-specification.mdを読んでプリミティブ(ツール、リソース、プロンプト)とトランスポートについて学ぶ。
  • サーバーが公開するプリミティブを決定する(例:ツールのみ、またはツール+リソース)。
  • トランスポートを選択:Stdio(ローカル、プロセスベース)またはStreamable HTTP(リモート、Webベース)。
• ステップ2:プロジェクト初期化
  • Node/pnpmプロジェクトを初期化し、@modelcontextprotocol/sdkとzodをインストール。
  • TypeScriptをESM用に設定(例:"module": "Node16"、"target": "ES2022")。オプションでassets/boilerplate/package.jsonとassets/boilerplate/tsconfig.jsonを使用。
• ステップ3:実装パターン
  • references/typescript-sdk-cheatsheet.mdを使用してMcpServer、トランスポート、registerTool(Zod inputSchema付き)、registerResourceについて学ぶ。
  • ツールアノテーション(title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint)を検討し、クライアントがツールを提示でき、ユーザーが承認できるようにする。チートシートの「ツールアノテーション」とMCP Tool annotationsを参照。
  • データを削除または永続的に変更するツールの場合、destructiveHint: trueを設定。クライアントは実行前に確認プロンプトを表示すべきであり、エージェント指示では破壊的なツールを呼び出す前にユーザーに確認するよう要求すること。
  • Stdioの場合:ロギングにはconsole.error(またはstderr)のみを使用し、console.log(stdoutはJSON-RPCを破損させる)は絶対に使用しない。
  • オプションでassets/templates/server-stdio.tsまたはassets/templates/server-http.tsからコピー。
• ステップ4:テスト
  • MCP Inspectorでテスト:例えばnpx @modelcontextprotocol/inspectorを実行し、サーバーを起動(例:node build/index.js)。
  • またはClaude Desktopでテスト:claude_desktop_config.json(macOS:~/Library/Application Support/Claude/claude_desktop_config.json)にサーバーを追加し、commandとargsを指定して、Claude Desktopを再起動。

詳細な手順

1. 要件の発見

MCPスペック概要を読んで以下を理解します:

• プリミティブ:ツール(LLMから呼び出し可能)、リソース(読み取り専用コンテキスト)、プロンプト(再利用可能なテンプレート)。
• トランスポート:Stdio(ローカル、クライアント1つ/プロセス)対Streamable HTTP(リモート、多数のクライアント)。
• ライフサイクル:初期化、機能ネゴシエーション、その後ツール一覧表示/呼び出しまたはリソース読み取り。

サーバーが必要とするプリミティブを決定し、ローカルで実行(Stdio)するかホストされた環境(Streamable HTTP)で実行するかを決めます。

2. プロジェクト初期化

• パッケージを作成します(例:pnpm initまたはnpm init -y)。
• インストール:pnpm add @modelcontextprotocol/sdk zod(またはnpm install @modelcontextprotocol/sdk zod)。SDKはツールのinputSchemaにZodが必要です。
• ESMを使用する場合はpackage.jsonに"type": "module"を設定。
• "module": "Node16"、"moduleResolution": "Node16"、"target": "ES2022"、"outDir": "./build"(またはそれに類する設定)を含むtsconfigを使用。

3. 実装パターン

TypeScript SDKチートシートを使用して以下を行います:

• McpServerを作成しトランスポート(StdioServerTransportまたはStreamableHTTPServerTransport)に接続。
• server.registerTool(name, { description, inputSchema }, handler)でツールを登録。inputSchemaにはZodを使用(例:{ id: z.string() })。{ content: [{ type: "text", text: "..." }] }を返します。クライアントがツールを提示または承認するのに役立つ場合は、ツールアノテーション(title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint)を追加します。破壊的な操作(例:削除)の場合は、destructiveHint: trueを設定。クライアントはユーザー確認プロンプトを表示すべきであり、エージェント指示ではそのようなツールを呼び出す前にユーザーに確認するよう要求すること。
• 必要に応じてリソースを登録(URIテンプレートと読み取りハンドラー)。
• ロギング:Stdioトランスポート使用時は、stdoutに書き込まず、console.errorまたはstderrに出力するロガーを使用。

4. テスト

• MCP Inspector:npx @modelcontextprotocol/inspectorを実行し、サーバーを起動(例えばClaude Desktopで使用するコマンド)。Inspector UIを使用してツールを一覧表示し、呼び出します。
• Claude Desktop:設定ファイルを編集(ローカルMCPサーバーに接続を参照)。mcpServersの配下にcommandとargsを含むエントリを追加(例:nodeと["/path/to/build/index.js"])。Claude Desktopを完全に再起動(アプリを終了してから再度開く)。サーバーがコネクタに表示されることを確認。

成功の基準

• サーバーはツール(および/またはリソース/プロンプト)を正しく一覧表示および実行できる。
• Stdioの場合:console.logの使用がなく、ログはstderrに出力される。
• ツールのinputSchemaはZodを使用し、SDK期待値と一致している。
• ツール名はスペック2025-11-25に準拠(1〜128文字、許可された文字)。エラーはツール実行結果(isError: true)またはプロトコルエラーとして適切に使用。
• ツールアノテーション(title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint)は、クライアントがツールを提示または承認するのに役立つ場合に使用される。
• 公式リンク(TypeScript SDK、MCPスペック2025-11-25)がバージョンとAPIの詳細に使用される。

参考リソース

• スペックインデックス(2025-11-25): references/spec-2025-11-25-index.md – 2025-11-25スペックのすべてのセクションのインデックス(基本、クライアント、サーバー、サーバーユーティリティ)
• references/mcp-specification.md – MCPの概念とスペックリンク
• references/typescript-sdk-cheatsheet.md – SDKスニペットとロギングルール
• MCP Build server (TypeScript)
• MCP TypeScript SDK
• MCP Specification 2025-11-25 · Changelog
• MCP Tools — Tool annotations (title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint)