first-mcp-server

プロジェクト概要

• 2つの数値を加算し、結果をテキストとして返す単一ツール add を公開する最小限の MCP（Model Context Protocol）サーバー。

• 入力検証のために @modelcontextprotocol パッケージと zod を使用しています。

主要ファイル

• index.js — add ツールを登録し、サーバーを起動するメインのサーバⅰファイル。

要件

• Node.js 16+（LTS 推奨）

• npm または yarn

インストール

1. リポジトリをク蟜ーンして、プロジェクトディレクトリに移動します：

   git clone && cd /Users/sagar/Documents/Learning/MCP-Server

2. 依存関係をインストールします（npm の例）：

   npm install

このプロジェクトで使用している依存関係（コードからの例）：

• @modelcontextprotocol/server

• @modelcontextprotocol/server/stdio（STDIOトランスポート）

• @modelcontextprotocol/express（expressヘルパー）

• @modelcontextprotocol/node（Node HTTP トランスポート）

• zod（検証）

実行

• デフォルの HTTP トランスポート（このプロジェクトの現在の起動方法）：

  node index.js

  サーバーはポート3001で待ち受け、MCP エンドポイントを /mcp にマウントします（from index.js を参照）。

• STDIO トランスポート（ローカ11 CLI との統合に便利）：

  index.js 内の runServerOnSTDIOTransport() コールをコメントアウト解除して、次を実行します：

  node index.js

利用例

1. HTTP の例（curl）

• リクエスト・ペイロード（JSON）：

  { "tool": "add", "input": { "num1": 10, "num2": 20 } }

• curl 呼び出しの例（必要応じて hostname/port を調整してください）：

  curl -X POST http://localhost:3001/mcp
  -H "Content-Type: application/json"
  -d '{"tool":"add","input":{"num1":10,"num2":20}}'

• 期待されるレスポンス（サーバーのツールはテキストブロックの content 配列を返します）：

  { "content": [ { "type": "text", "text": "30" } ] }

注記: index.jss は NodeStreamableHTTPServerTransport を使用して HTTP トランスポートを配線し、transport.handleRequest(req, res, req.body) を呼び出します（[src] の "index.js）を参照）。トランスポートが期待するエンベロープは @modelcontextprotocol/node トランスポートの実装に依存します。上記の例は、このプロジェクトで使用されているシンプルな形式（toolとinput`）に従っています。

2. STDIO の例（ローカールCLI との統合）

• このプロジェクトには、StdioServerTransport を介して STDIO 上でサーバーを実行するヘルパーが含まれています。STDIO モードで起動した場合、サーバーは stdin の JSON リクエストを受けけ、stdout にレスポンスを返します。トールは index.js に登録されており、zod で入力を検証し、合計をテキストとして返します。

ツールの詳細（コードに基づく）

• ツール名: "add"

• 説明: "2つの数値を加算する"

• 入力スキーマ（zod）:

  • num1: number

  • num2: number

実装スニペット（コード内の [index.js] から取得）

server.registerTool(
  "add",
  {
    title: "add",
    description: "Add two numbers",
    inputSchema: z.object({ num1: z.number(), num2: z.number() }),
  },
  async (ctx) => ({
    content: [{ type: "text", text: `${ctx.num1 + ctx.num2}` }],
  }),
);

注記:

• バリデーション: zod が入力を既サにしています。呼び出し側は必ず数値を送り、検証エラーを適切に処理してください。

• エラー処理: transport.handleRequest とツールハンドラを try/catch で包み、一貫したエラー・ペイロードと HTTP ステータスコード（クライアント・エラーは 4xx、サーバー・エラーは 5xx）を返すようにしてください。

• ロギングとモニタリング: 構造化ロギング、リクエスト ID、基本メトリクスを追加して、使用状況とエラーを監視してください。

• セキュリティ: 公開する場合は、/ mcp エンドポイントを認証とレート制限で保護し、リバースプロキシ間で運してください。

• テス: ツールハンドラのユニットテスと、トランスポートの統合テス（HTTP と STDIO）を追加してください。

貢献

• 機能リクエストや修正には、Issue を開くか PR を作成してください。