From e795dbc7540df2bf82d00cf21b1f475186bd4c9f Mon Sep 17 00:00:00 2001 From: liplus-lin-lay <259586417+liplus-lin-lay@users.noreply.github.com> Date: Sun, 15 Mar 2026 16:01:18 +0900 Subject: [PATCH] docs(readme): trim duplicated behavior details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README を quick start と運用入口に寄せ、詳細な trigger semantics や metadata の重複説明を requirements spec へ委譲しました。\nsetup 導線は残しつつ、source of truth を docs/0-requirements.md に明示しています。\n\nRefs #17 --- README.md | 112 +++++++++--------------------------------------------- 1 file changed, 18 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index d8b1dd8..e142785 100644 --- a/README.md +++ b/README.md @@ -3,28 +3,14 @@ GitHub webhook receiver as an MCP server. Receives GitHub webhook events and enables Lin and Lay to autonomously handle PR reviews and issue management. -It can either expose events to MCP for polling or trigger Codex immediately when a webhook arrives. +It supports two operating styles: -## Architecture +- MCP polling: store webhook events and let an AI poll lightweight summaries. +- Direct trigger: run a command immediately for each stored event. -``` -GitHub → Cloudflare Tunnel → webhook server (FastAPI :8080) - ↓ events.json - ┌──────────────┴──────────────┐ - ↓ ↓ - MCP server (stdio) direct trigger queue - ↓ ↓ - Codex / Claude codex exec (one-by-one) -``` - -Recommended polling flow: - -1. Poll `get_pending_status` every 60 seconds. -2. If `pending_count > 0`, call `list_pending_events`. -3. Only call `get_event` for the specific event IDs that need full payloads. -4. Call `mark_processed` after handling them. +Detailed behavior, event metadata, trigger semantics, and file responsibilities live in [docs/0-requirements.md](docs/0-requirements.md). -## Setup +## Quick Start ### 1. Install dependencies @@ -32,35 +18,16 @@ Recommended polling flow: pip install -r requirements.txt ``` -### 2. Start webhook receiver +### 2. Start webhook receiver for MCP polling ```bash WEBHOOK_SECRET=your_secret python main.py webhook --port 8080 --event-profile notifications ``` -### 2b. Start webhook receiver with direct Codex reactions - -`main.py webhook` accepts `--trigger-command`, which runs once per stored event. -When a service manager already splits arguments for you, put `--trigger-command` last and pass the command tokens after it without wrapping the whole trigger in quotes. -The command receives the full event JSON on stdin and also gets these environment variables: - -- `GITHUB_WEBHOOK_EVENT_ID` -- `GITHUB_WEBHOOK_EVENT_TYPE` -- `GITHUB_WEBHOOK_EVENT_ACTION` -- `GITHUB_WEBHOOK_EVENT_REPO` -- `GITHUB_WEBHOOK_EVENT_SENDER` -- `GITHUB_WEBHOOK_EVENT_NUMBER` -- `GITHUB_WEBHOOK_EVENT_TITLE` -- `GITHUB_WEBHOOK_EVENT_URL` -- `GITHUB_WEBHOOK_EVENT_PATH` -- `GITHUB_WEBHOOK_RECEIVED_AT` - -The webhook server serializes trigger execution, so only one direct reaction runs at a time. -Successful runs are marked processed automatically. Failed runs stay pending. -If the trigger command intentionally defers handling, it can exit with code `86`. -That is recorded as `trigger_status=skipped` and the event stays pending for foreground polling. +### 3. Optional: start webhook receiver with direct Codex reactions -Use the bundled Codex wrapper if you want the webhook to launch `codex exec` immediately: +Use the bundled Codex wrapper if you want the webhook to launch `codex exec` immediately. +Put `--trigger-command` last when a service manager splits the remaining tokens for you. ```bash python main.py webhook \ @@ -69,28 +36,7 @@ python main.py webhook \ --trigger-command "python codex_reaction.py --workspace /path/to/workspace --output-dir /path/to/github-webhook-mcp/codex-runs" ``` -Service-manager style is also supported: - -```text -python main.py webhook --port 8080 --event-profile notifications --trigger-command python codex_reaction.py --workspace /path/to/workspace --output-dir /path/to/github-webhook-mcp/codex-runs -``` - -On Windows PowerShell the same idea looks like this: - -```powershell -py -3 .\main.py webhook ` - --port 8080 ` - --event-profile notifications ` - --trigger-command "py -3 C:\path\to\github-webhook-mcp\codex_reaction.py --workspace C:\path\to\workspace --output-dir C:\path\to\github-webhook-mcp\codex-runs" -``` - -`codex_reaction.py` builds a short prompt, points Codex at the saved event JSON file, and runs: - -```text -codex -a never -s workspace-write exec -C ... -``` - -If you want the result to appear in an existing Codex app thread instead of a markdown file, switch the wrapper to resume mode: +If you want Codex to resume an existing app thread instead of writing markdown output: ```text python codex_reaction.py --workspace /path/to/workspace --resume-session @@ -99,7 +45,7 @@ python codex_reaction.py --workspace /path/to/workspace --resume-session .json`: saved payload passed to direct trigger commands +- For the recommended polling flow, MCP tool contracts, event profiles, and trigger metadata, see [docs/0-requirements.md](docs/0-requirements.md). +- For environment variable examples, see [.env.example](.env.example). +- For direct trigger usage, `codex_reaction.py` is the bundled helper. ## Related +- [docs/0-requirements.md](docs/0-requirements.md) — source-of-truth requirements and behavior contracts - [Liplus-Project/liplus-language](https://github.com/Liplus-Project/liplus-language) — Li+ language specification - liplus-language #610