From cea66bb1a1694940164c086c66ad40d86309d843 Mon Sep 17 00:00:00 2001 From: smile <134200591+smileygames@users.noreply.github.com> Date: Sun, 15 Mar 2026 22:19:45 +0900 Subject: [PATCH] docs(requirements): cover Node.js MCP server addition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #20 で追加された Node.js MCP サーバー（mcp-server/）を要求仕様書に反映。 Architecture、F4、N2、Dependencies、Infrastructure、Files の各セクションを更新。 Refs #22 Co-Authored-By: Claude Opus 4.6 --- docs/0-requirements.md | 42 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/docs/0-requirements.md b/docs/0-requirements.md index 97ca0bd..aeb4135 100644 --- a/docs/0-requirements.md +++ b/docs/0-requirements.md @@ -24,17 +24,25 @@ GitHub ──POST──> Cloudflare Tunnel ──> FastAPI :8080 ──persist | ^ | | MCP Server (stdio) ──read/write direct trigger queue + Python or Node.js | ^ | | | AI Agent (Codex / Claude) optional trigger command ``` -二つのプロセスモードを持つ単一エントリポイント: -- `python main.py webhook` — HTTP 受信サーバー -- `python main.py mcp` — MCP ツールサーバー +システムは二つのコンポーネントで構成される: -Webhook モードは、イベント永続化に加えて optional な direct trigger queue を持つ。 -trigger command が設定されている場合、保存済みイベントごとに直列実行される。 +1. **Webhook 受信サーバー（Python）** — `python main.py webhook` + - HTTP 受信、イベント永続化、optional な direct trigger queue を担当 + - trigger command が設定されている場合、保存済みイベントごとに直列実行される + +2. **MCP ツールサーバー** — 二つの実装が存在する: + - **Python 実装:** `python main.py mcp` + - **Node.js 実装:** `mcp-server/` ディレクトリ（`npx github-webhook-mcp` または MCPB 経由） + +両 MCP 実装は同一の events.json を読み書きし、同一の5ツールを提供する。 +Python 実装は webhook 受信サーバーと同一エントリポイントで起動する。 +Node.js 実装は独立パッケージとして配布される（MCPB: Claude Desktop 向け、npx: Codex 向け）。 ## Functional Requirements @@ -99,6 +107,8 @@ trigger command が設定されている場合、保存済みイベントごと ### F4. MCP ツール +Python 実装と Node.js 実装の両方が、以下の同一ツールセットを提供する。 + | ID | ツール名 | 引数 | 戻り値 | 要件 | |----|---------|------|--------|------| | F4.1 | `get_pending_status` | なし | pending_count, latest_received_at, types | 未処理イベントの軽量スナップショットを返す | @@ -191,8 +201,10 @@ trigger command が設定されている場合、保存済みイベントごと | N2.4 | trigger command | `--trigger-command` / `WEBHOOK_TRIGGER_COMMAND` | なし | | N2.5 | trigger working directory | `--trigger-cwd` / `WEBHOOK_TRIGGER_CWD` | なし | | N2.6 | success 時に pending を維持するか | `--keep-pending-on-trigger-success` | false | +| N2.7 | events.json パス（Node.js MCP） | `EVENTS_JSON_PATH` | `mcp-server/../events.json` | 優先順位: CLI 引数 > 環境変数 > デフォルト +Node.js MCP サーバーは環境変数のみで構成する（CLI 引数なし）。 ### N3. 制約 @@ -205,6 +217,8 @@ trigger command が設定されている場合、保存済みイベントごと ## Dependencies +### Python（webhook 受信 + MCP サーバー） + | パッケージ | バージョン | 用途 | |-----------|-----------|------| | fastapi | >=0.110.0 | HTTP サーバーフレームワーク | @@ -212,6 +226,16 @@ trigger command が設定されている場合、保存済みイベントごと | mcp | >=1.0.0 | Model Context Protocol SDK | | python-dotenv | >=1.0.0 | 環境変数ロード | +### Node.js（MCP サーバー） + +| パッケージ | バージョン | 用途 | +|-----------|-----------|------| +| @modelcontextprotocol/sdk | ^1.0.0 | MCP SDK | +| iconv-lite | ^0.6.3 | レガシーエンコーディング対応 | +| zod | ^3.22.0 | スキーマバリデーション | + +Node.js >= 18.0.0 が必要。 + ## Infrastructure | コンポーネント | 用途 | @@ -219,6 +243,8 @@ trigger command が設定されている場合、保存済みイベントごと | Cloudflare Tunnel | GitHub からのインバウンド HTTPS を localhost に転送 | | GitHub Webhook | イベント送信元 | | optional trigger command | 保存済みイベントごとの direct reaction | +| MCPB | Claude Desktop 向け Node.js MCP サーバー配布 | +| npx | Codex 向け Node.js MCP サーバー配布 | ## Files @@ -226,5 +252,9 @@ trigger command が設定されている場合、保存済みイベントごと |-----|------| | `events.json` | 永続化された webhook イベント本体 | | `trigger-events/.json` | trigger command に渡す保存済みイベント JSON | -| `main.py` | webhook receiver / MCP server / direct trigger queue | +| `main.py` | webhook receiver / Python MCP server / direct trigger queue | | `codex_reaction.py` | Codex direct execution / resume / notify-only fallback helper | +| `mcp-server/server/index.js` | Node.js MCP サーバー エントリポイント | +| `mcp-server/server/event-store.js` | Node.js イベントストア（events.json 読み書き） | +| `mcp-server/package.json` | Node.js パッケージ定義（npx 配布用） | +| `mcp-server/manifest.json` | MCPB マニフェスト（Claude Desktop 配布用） |