Stateless MCP Server Builder for PHP & Static Hosts

1. 目的と基本原理

エックスサーバー等の一般的なレンタルサーバーにおいて、Node.jsやPythonの常時起動プロセス（デーモン）を用いずに、PHPと静的ファイル（JSON）の組み合わせだけで完全な MCP (Model Context Protocol) サーバーを構築・運用するための実装規範である。

2. アーキテクチャ構成

1. SSGビルド時: scripts/prerender.mjs 等を用いて、MCPで提供するリソースデータやツール定義を dist/assets/data/*.json などの静的ファイルとして全自動出力する。
2. MCP Endpoint (public/api/mcp.php):
3. JSON-RPC 2.0 仕様 (initialize, tools/list, tools/call, resources/list, resources/read) を実装。
4. POST リクエストを受け取り、JSON-RPCリクエストを解析して静的JSONから検索・返却する。
5. CORS & Xserver 対策:
6. Access-Control-Allow-Origin: * をヘッダーで返す。
7. Access-Control-Allow-Headers: Content-Type, Authorization, MCP-Session-Id, Mcp-Version を許可する。
8. public/api/.htaccess で Require all granted を設定し、WAF等による 403 Forbidden を回避する。

3. 実装上の必須ルール (Mandatory Rules)

3.1. リクエストボディの確実な取得

PHP環境では、$_POST 変数は application/json の場合に自動でパースされない。必ず php://input を読み込むこと。

❌ 悪い例（POSTデータを正しく取得できない）

$request = $_POST; // application/jsonの場合は空になる

✅ 良い例（ストリームから取得してパース）

$rawInput = file_get_contents('php://input');
$request = json_decode($rawInput, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    // パースエラー時の対応
}

3.2. JSON-RPC 2.0 仕様の厳守

• リクエストには必ず jsonrpc: "2.0"、method、id (通知以外) が含まれる。
• レスポンスには必ず jsonrpc: "2.0"、id、および result または error のいずれかが含まれる。

3.3. HTTPステータスコードの扱い

JSON-RPCの仕様に従い、リクエストのパース自体が成功し、プロトコル上のエラー（例: メソッドが見つからない）を返す場合も HTTP ステータスは 200 OK にする。HTTP 4xx/5xx は致命的なサーバーエラーやルーティングエラーの場合にのみ使用する。

4. セキュリティとCORS（禁止事項）

• 禁止事項: 開発環境以外で無制限の CORS を許可したままにすること。
• ただし、Claude Desktop 等のローカルクライアントからアクセスする場合は * が必要になるケースがあるため、要件に応じて Access-Control-Allow-Origin を適切に絞る。

5. 出力チェックリスト

• [ ] エンドポイントのPHPスクリプトが php://input からJSONを読み込んでいるか。
• [ ] initialize メソッドに対して正しいケイパビリティ（capabilities）を返しているか。
• [ ] ツールやリソースのリストが正しくフォーマットされているか。
• [ ] エラー時のレスポンスが JSON-RPC 2.0 準拠の error オブジェクトになっているか。