metheus-governance-mcp-cli 0.2.52 → 0.2.54

package/README.md

@@ -20,23 +20,54 @@ Compatibility note: legacy command alias `metheus-governance-mcp` is still suppo
 npm install -g metheus-governance-mcp-cli@latest
 ```
 
-Install creates a local Telegram settings template here:
+Install creates local provider settings templates here:
 
 - `~/.metheus/telegram.env`
+- `~/.metheus/slack.env`
+- `~/.metheus/kakaotalk.env`
+- `~/.metheus/bot-runner.json`
 
-This file is for the local Telegram bot secret only.
+These files are for local provider bot secrets only.
 
 - Store locally:
   - `TELEGRAM_BOT_TOKEN`
-- Server-side Metheus stores project Telegram destination metadata separately:
-  - `chat_id`
+  - `SLACK_BOT_TOKEN`
+  - `KAKAOTALK_BOT_TOKEN`
+- Server-side Metheus stores project chat destination metadata separately:
+  - provider
+  - `chat_id` / channel / room identifier
   - label / active state
-- Do not put project `chat_id` in the local Telegram env file.
+- Do not put project chat destination identifiers in local env files.
 
-Example template:
+Example templates:
 
 ```env
+# ~/.metheus/telegram.env
 TELEGRAM_BOT_TOKEN=
+
+# ~/.metheus/slack.env
+SLACK_BOT_TOKEN=
+
+# ~/.metheus/kakaotalk.env
+KAKAOTALK_BOT_TOKEN=
+```
+
+Runner template:
+
+```json
+{
+  "version": 1,
+  "routes": [
+    {
+      "name": "telegram-monitor",
+      "enabled": false,
+      "project_id": "<project_uuid>",
+      "provider": "telegram",
+      "role": "monitor",
+      "command": "metheus-governance-mcp-cli local-bot-bridge --client codex --no-update"
+    }
+  ]
+}
 ```
 
 ## One command bootstrap (recommended)
@@ -69,11 +100,33 @@ Recommended for Codex/Claude/Gemini/Antigravity/Cursor multi-workspace sessions:
 metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctxpack_key>" --base-url https://metheus.gesiaplatform.com --workspace-dir auto
 ```
 
-`setup` also ensures the local Telegram template exists:
+`setup` also ensures local provider templates exist:
 
 - `~/.metheus/telegram.env`
+- `~/.metheus/slack.env`
+- `~/.metheus/kakaotalk.env`
+- `~/.metheus/bot-runner.json`
+
+Fill only provider bot tokens locally. Project chat destination identifiers should be managed on the Metheus server as project chat destinations, not as local env values and not inside legacy Chat Hooks/webhooks.
+
+`~/.metheus/bot-runner.json` is the local automation profile for:
+- which project to watch
+- which provider/role bot profile to use
+- which local AI command to run on new archived chat messages
 
-Fill only the bot token locally. Project Telegram `chat_id` destinations should be managed on the Metheus server as project Telegram destinations, not as local env values and not inside Chat Hooks.
+Built-in helper command:
+
+```bash
+metheus-governance-mcp-cli local-bot-bridge --client codex --no-update
+```
+
+Supported `--client` values:
+- `codex`
+- `claude`
+- `gemini`
+- `sample`
+
+Use `sample` first for smoke tests before switching to a real AI client.
 
 Gemini CLI note:
 - `gemini mcp` commands require Gemini auth to be configured first (`GEMINI_API_KEY` or `~/.gemini/settings.json` auth).
@@ -105,7 +158,8 @@ metheus-governance-mcp-cli doctor --project-id <project_uuid> --base-url https:/
 
 Checks:
 - auth token status (+ auto refresh attempt)
-- local Telegram env token presence
+- local provider env template presence
+- local provider token presence for active project destinations
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
 - `project.summary` access
@@ -113,10 +167,60 @@ Checks:
 - smoke calls: `workitem.list`, `evidence.list`, `decision.list`
 
 Direct bot posting:
-- `me.send-bot-message` uses the local `TELEGRAM_BOT_TOKEN` from `~/.metheus/telegram.env`
+- `me.send-bot-message` uses local provider tokens from `~/.metheus/<provider>.env`
 - it does not use a server-stored bot token
-- the destination `chat_id` is resolved from the current project's saved Chat Destinations on the Metheus server
-- if multiple active Telegram destinations exist for the project, pass `destination_id` or `destination_label`
+- the destination identifier is resolved from the current project's saved Chat Destinations on the Metheus server
+- if multiple active destinations exist for the same provider, pass `destination_id` or `destination_label`
+- direct local delivery is implemented today for:
+  - Telegram
+  - Slack
+- KakaoTalk profiles and destinations can be stored now, but direct local delivery is not implemented yet
+
+## Local bot runner
+
+The local runner closes the loop:
+
+1. provider bot receives a room message
+2. Metheus archives the message into Governance discussion comments
+3. local runner reads new archived comments
+4. local AI command generates a reply
+5. CLI sends the reply back through `me.send-bot-message`
+6. the sent reply is mirrored back into the archive
+
+Commands:
+
+```bash
+metheus-governance-mcp-cli runner once
+metheus-governance-mcp-cli runner start
+```
+
+Common flags:
+
+```bash
+metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --command "node C:\\path\\to\\my-runner.js"
+metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --command "python C:\\path\\to\\reply.py" --poll-interval-ms 5000
+```
+
+Recommended production path:
+- keep provider bot token in `~/.metheus/<provider>.env`
+- keep project room identifier in server-side Chat Destinations
+- keep automation route config in `~/.metheus/bot-runner.json`
+
+Runner command contract:
+- stdin: JSON payload containing project, destination, trigger message, and recent context comments
+- stdout:
+  - plain text reply, or
+  - JSON object like `{"reply":"...","reply_to_message_id":123}`, or
+  - JSON skip result like `{"skip":true,"reason":"not actionable"}`
+
+Notes:
+- `runner once` processes the most recent pending archived inbound message
+- `runner start` keeps polling and stores per-route cursor state in `~/.metheus/bot-runner-state.json`
+- first start primes the cursor to the latest inbound message and does not reply to old backlog
+- `local-bot-bridge` reads stdin JSON from the runner and can call Codex/Claude/Gemini for you
+- today this automation path is implemented for Telegram end-to-end
+- Slack can use direct local send, but automatic inbound runner flow is not completed yet
+- KakaoTalk config can be stored now, but direct send/runner flow is not implemented yet
 
 ## Use in MCP