WebアプリをAIから操作できるようにした話（第1回）— MCPサーバー化の動機とアーキテクチャ

Claude Code
    │
    │  JSON-RPC 2.0 over HTTP
    ↓
MCPサーバー（あなたのアプリ）
    │
    │  通常のAPI呼び出し
    ↓
データベース・外部サービス

1. POST /api/mcp  ← initialize（ハンドシェイク）
2. POST /api/mcp  ← notifications/initialized（通知）
3. POST /api/mcp  ← tools/list（利用可能ツール一覧）
4. POST /api/mcp  ← tools/call（ツール実行）

Claude Code（開発者のPC）
    │
    │  HTTPS + Bearer Token
    ↓
CloudFront
    │
    ↓
API Gateway + Lambda
    │
    ├── POST /api/mcp  ←── MCPサーバー本体（今回実装）
    │       │
    │       ├── initialize, tools/list
    │       └── tools/call → 各ツールハンドラー
    │
    ├── GET  /api/mcp  ←── SSEハンドシェイク用
    │
    └── 既存のWebアプリAPI
            │
            └── DynamoDB（タスク・プロジェクトデータ）

src/
├── app/api/
│   ├── mcp/
│   │   └── route.ts          # MCPエンドポイント（POST/GET/OPTIONS）
│   └── mcp-tokens/
│       ├── route.ts           # トークン一覧・発行
│       └── [id]/route.ts      # トークン失効
├── lib/mcp/
│   ├── auth.ts                # Bearer Token認証
│   ├── handler.ts             # JSON-RPC 2.0 ハンドラー
│   ├── server.ts              # 全ツールの集約
│   ├── types.ts               # 型定義
│   └── tools/
│       ├── project.ts         # プロジェクト操作ツール
│       ├── task.ts            # タスク操作ツール
│       ├── item.ts            # アイテム操作ツール
│       ├── comment.ts         # コメント操作ツール
│       ├── tag.ts             # タグ操作ツール
│       ├── milestone.ts       # マイルストーン操作ツール
│       ├── baseline.ts        # ベースライン操作ツール
│       ├── work-report.ts     # 業務報告操作ツール
│       ├── dependency.ts      # 依存関係操作ツール
│       └── misc.ts            # チーム・ユーザー・アクティビティ
└── components/settings/
    └── McpTokenSettings.tsx   # トークン管理UI

Next.js 15（App Router）+ TypeScript + AWS Lambda 構成の既存Webアプリに
MCPサーバー機能を追加してください。

【要件】
- エンドポイント: POST /api/mcp（メインのJSON-RPC処理）
- エンドポイント: GET /api/mcp（SSEハンドシェイク用、空ストリームを返すだけでOK）
- プロトコル: MCP Streamable HTTP（protocolVersion: "2024-11-05"）
- 認証: リクエストヘッダーの Authorization: Bearer <token> を検証

【MCPエンドポイントの動作】
- initialize → protocolVersion・capabilities・serverInfo を返す
- tools/list → 登録済みツール一覧を返す
- tools/call → ツール名とargumentsを受け取り対応するハンドラーを呼ぶ
- Notification（id フィールドなし）→ 202 No Content を返す
- バッチリクエスト（配列）→ 各要素を処理して配列で返す

Lambdaはステートレスなので、セッション状態は持たない。
型はすべて明示し、any/unknown は使わないこと。