MCP Server

🚀 MCP Server

プラガブルなツールを備えた統一されたMCP（Model Context Protocol）サーバーです。各ツールは独立したエンドポイントを持ち、クライアントは特定のツールを選択的に追加できます。

日本語ドキュメント

✨ 主な機能

• パスルーティングによる統一エンドポイント：各ツールは独自のMCPエンドポイント（/mcp/{toolName}）を持ちます。
• 疎結合なツール：ツールはsrc/tools/ディレクトリから独立して読み込まれます。
• 障害分離：個々のツールの障害は他のツールに影響を与えません（タイムアウト保護 + エラーハンドリング）。
• StreamableHTTPトランスポート：最新のMCPトランスポートプロトコルです。
• ベアラートークン認証：安全なAPIアクセスが可能です。
• Dockerサポート：コンテナ化されたデプロイメントに対応しています。

📦 インストール

ローカル開発

# 依存関係のインストール
npm install

# .envファイルの作成
echo "AUTHORIZATION_KEY=your-secret-key" > .env

# 開発サーバーの起動
npm run dev

Dockerデプロイメント

# docker-composeでビルドして実行
docker-compose up -d --build

# または手動でビルド
docker build -t mcp-server .
docker run -e AUTHORIZATION_KEY=your-secret-key -p 3000:3000 mcp-server

📚 ドキュメント

プロジェクト構造

mcp_server/
├── src/
│   ├── index.ts                    # エントリーポイント
│   ├── core/
│   │   ├── tool-registry.ts        # ツールレジストリ
│   │   ├── tool-loader.ts          # 動的ツールローダー
│   │   └── tool-executor.ts        # 分離された実行器（タイムアウト + エラーハンドリング）
│   ├── server/
│   │   ├── app.ts                  # Express + StreamableHTTP
│   │   └── mcp-server.ts           # MCPサーバーインスタンス
│   ├── middleware/
│   │   └── auth.ts                 # ベアラートークン認証
│   ├── tools/                      # 疎結合なツールディレクトリ
│   │   ├── calculator/index.ts     # 計算機ツール（加算/減算/乗算/除算）
│   │   ├── echo/index.ts           # エコーツール（エコー/反転/情報）
│   │   └── time/index.ts           # 時間ツール（現在時刻の取得/時刻の変換/時刻のフォーマット）
│   ├── types/mcp.ts                # 型定義
│   └── utils/logger.ts             # ターミナルロガー
├── Dockerfile                      # マルチステージビルド
├── docker-compose.yml
├── package.json
└── tsconfig.json

APIエンドポイント

利用可能なツール

計算機 (/mcp/calculator)

様々な演算子と関数をサポートする数式評価器です。

サポートされる演算子:

• 算術演算子: +, -, *, /
• 切り捨て除算: //
• 剰余: %
• べき乗: ** または ^

サポートされる定数: pi, e

サポートされる関数: sin, cos, tan, sqrt, abs, log, log10, exp, floor, ceil, round, pow, min, max

例:

2 + 3 * 4        → 14
(2 + 3) * 4      → 20
2^10             → 1024
sqrt(16)         → 4
2 * pi           → 6.283...
sin(0)           → 0
pow(2, 8)        → 256
17 // 5          → 3
17 % 5           → 2

エコー (/mcp/echo)

テストとデバッグ用のエコーツールです。

時間 (/mcp/time)

タイムゾーン変換とフォーマット用の時間ツールです。

クライアント設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）を編集します。

{
  "mcpServers": {
    "calculator": {
      "url": "http://localhost:3000/mcp/calculator",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    },
    "time": {
      "url": "http://localhost:3000/mcp/time",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

Cursor / VS Code

プロジェクトルートに.cursor/mcp.jsonを作成します。

{
  "mcpServers": {
    "calculator": {
      "url": "http://localhost:3000/mcp/calculator",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

プログラムによる使用（Node.js）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({
  name: "my-client",
  version: "1.0.0",
});

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp/calculator"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer your-secret-key",
      },
    },
  }
);

await client.connect(transport);

// 利用可能なツールをリストする
const tools = await client.listTools();
console.log(tools);

// ツールを呼び出す
const result = await client.callTool({
  name: "add",
  arguments: { a: 10, b: 5 },
});
console.log(result);

新しいツールの追加

1. src/tools/の下に新しいディレクトリを作成します。

src/tools/my-tool/
└── index.ts

2. MCPToolインターフェイスを実装します。

import { z } from "zod";
import { MCPTool, MCPMethodDefinition } from "../../types/mcp.js";

const myTool: MCPTool = {
  name: "my-tool",
  description: "Description of my tool",
  version: "1.0.0",

  getMethods(): MCPMethodDefinition[] {
    return [
      {
        name: "my-method",
        description: "Description of my method",
        inputSchema: {
          param1: z.string().describe("Parameter description"),
        },
        handler: async (params) => {
          const { param1 } = params as { param1: string };
          return { result: param1 };
        },
      },
    ];
  },

  async initialize() {
    // 初期化ロジック
  },

  async healthCheck() {
    return true;
  },
};

export default myTool;

3. ツールはサーバー起動時に自動的に読み込まれます。

スクリプト

npm run dev        # ホットリロード付きで開発サーバーを起動する
npm run build      # 本番用にビルドする
npm start          # 本番サーバーを起動する
npm test           # テストを実行する
npm run lint       # コードスタイルをチェックする
npm run lint:fix   # コードスタイルの問題を自動修正する

📄 ライセンス

MIT