metheus-governance-mcp-cli 0.2.62 → 0.2.64

package/README.md

@@ -10,6 +10,7 @@ Compatibility note: legacy command alias `metheus-governance-mcp` is still suppo
   - checks Codex/Claude/Gemini/Antigravity/Cursor MCP registration
   - registers only missing clients
 - `setup`: register `metheus-governance-mcp` into Codex/Claude/Gemini/Antigravity/Cursor (if installed)
+- `bot`: local chat bot env setup/list/show/add/edit/remove/global/verify
 - `doctor`: run end-to-end health checks (auth/registration/gateway/project/ctxpack/tools)
 - `proxy`: stdio MCP bridge to Metheus HTTPS gateway
 - `auth`: save/check/clear local Metheus token used by proxy
@@ -27,10 +28,10 @@ Install creates local provider settings templates here:
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
 
-These files are for local provider bot secrets only.
+These files are for local provider bot secrets, local transport options, and optional per-bot local AI binding.
 
 - Store locally:
-  - `TELEGRAM_BOT_TOKEN`
+  - `TELEGRAM_BOT_TOKEN` or named Telegram bot mappings such as `TELEGRAM_BOT_MAIN_TOKEN`
   - `SLACK_BOT_TOKEN`
   - `KAKAOTALK_BOT_TOKEN`
 - Server-side Metheus stores project chat destination metadata separately:
@@ -38,13 +39,30 @@ These files are for local provider bot secrets only.
   - `chat_id` / channel / room identifier
   - label / active state
 - Do not put project chat destination identifiers in local env files.
+- Telegram env can also carry per-bot local AI binding fields.
 
 Example templates:
 
 ```env
 # ~/.metheus/telegram.env
+TELEGRAM_API_BASE_URL=
+TELEGRAM_AUTO_CLEAR_WEBHOOK=true
+TELEGRAM_ALLOWED_UPDATES=message,edited_message
+TELEGRAM_DEFAULT_BOT_KEY=main
+
+# Legacy fallback
 TELEGRAM_BOT_TOKEN=
 
+# Preferred named bot mapping
+TELEGRAM_BOT_MAIN_SERVER_BOT_ID=
+TELEGRAM_BOT_MAIN_USERNAME=<bot_username>
+TELEGRAM_BOT_MAIN_TOKEN=
+TELEGRAM_BOT_MAIN_ROLE_PROFILE=monitor
+TELEGRAM_BOT_MAIN_AI_CLIENT=codex
+TELEGRAM_BOT_MAIN_AI_MODEL=
+TELEGRAM_BOT_MAIN_AI_PERMISSION_MODE=read_only
+TELEGRAM_BOT_MAIN_AI_REASONING_EFFORT=low
+
 # ~/.metheus/slack.env
 SLACK_BOT_TOKEN=
 
@@ -72,6 +90,17 @@ Runner template:
       "reasoning_effort": "low"
     }
   },
+  "bot_bindings": {
+    "primary_monitor_bot": {
+      "bot_id": "<server_bot_uuid>",
+      "bot_name": "<bot_name>",
+      "role_profile": "monitor",
+      "client": "codex",
+      "model": "",
+      "permission_mode": "read_only",
+      "reasoning_effort": "low"
+    }
+  },
   "routes": [
     {
       "name": "telegram-monitor",
@@ -79,7 +108,7 @@ Runner template:
       "project_id": "<project_uuid>",
       "provider": "telegram",
       "role": "monitor",
-      "role_profile": "monitor",
+      "bot_id": "<server_bot_uuid>",
       "trigger_policy": {
         "mentions_only": true,
         "direct_messages": true,
@@ -134,13 +163,14 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 - `~/.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.
+Fill provider bot secrets and provider-local transport options 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 `project_id -> workspace_dir` mapping to apply locally
 - which role profile maps to which local CLI/model/permission/reasoning policy
+- which server bot maps to which local LLM execution profile via `telegram.env` or fallback `bot_bindings`
 
 Built-in helper command for legacy fallback/testing:
 
@@ -169,6 +199,65 @@ Guardrail note:
 - By default, CLI blocks reading/writing ctxpack sync metadata when workspace root resolves to the home directory.
 - Override only when intentional: `METHEUS_ALLOW_HOME_WORKSPACE=1`.
 
+## Bot
+
+Interactive entry:
+
+```bash
+metheus-governance-mcp-cli bot setup
+```
+
+Direct commands:
+
+```bash
+metheus-governance-mcp-cli bot list
+metheus-governance-mcp-cli bot show --provider telegram --bot-key main
+metheus-governance-mcp-cli bot add --provider telegram
+metheus-governance-mcp-cli bot edit --provider telegram
+metheus-governance-mcp-cli bot remove --provider telegram
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-key main
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-key main
+metheus-governance-mcp-cli bot global --provider telegram
+metheus-governance-mcp-cli bot verify --provider telegram --bot-key main
+```
+
+Behavior:
+
+- `bot setup` asks for `Telegram / Slack / KakaoTalk` first, then prompts with numbered actions.
+- Telegram supports named local bot entries with:
+  - `SERVER_BOT_ID`
+  - `USERNAME`
+  - `TOKEN`
+  - `ROLE_PROFILE`
+  - `AI_CLIENT`
+  - `AI_MODEL`
+  - `AI_PERMISSION_MODE`
+  - `AI_REASONING_EFFORT`
+- Slack and KakaoTalk currently use a single local token entry per provider in this command flow.
+- `bot verify` checks the configured local token and prints the current AI binding summary.
+- `bot show` prints one local bot entry in detail.
+- `bot global` edits Telegram-wide local settings such as API base URL, allowed updates, and default bot key.
+- `bot set-default` updates `TELEGRAM_DEFAULT_BOT_KEY`.
+- `bot migrate` moves legacy `TELEGRAM_BOT_TOKEN` into a named Telegram bot entry.
+
+Non-interactive examples:
+
+```bash
+metheus-governance-mcp-cli bot global --provider telegram --non-interactive true --api-base-url http://127.0.0.1:8999/telegram --auto-clear-webhook false --allowed-updates message,edited_message,channel_post
+metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --bot-key main --bot-id <server_bot_uuid> --token <telegram_bot_token> --role-profile monitor --client codex --permission-mode read_only --reasoning-effort low --default true
+metheus-governance-mcp-cli bot edit --provider telegram --bot-key main --non-interactive true --client claude --model claude-3.7-sonnet --permission-mode workspace_write --reasoning-effort medium
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-key main --non-interactive true
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-key main --bot-id <server_bot_uuid> --bot-name <telegram_username> --role-profile monitor --client codex --permission-mode read_only --reasoning-effort low --non-interactive true
+metheus-governance-mcp-cli bot remove --provider telegram --bot-key main --non-interactive true
+metheus-governance-mcp-cli bot verify --provider telegram --bot-key main --json true
+```
+
+Current support status:
+
+- Telegram: full local bot entry management, token verification, bot-to-AI binding, inbound runner support
+- Slack: single local token entry, verification supported, inbound runner not supported
+- KakaoTalk: single local token entry, local config only, remote verification not implemented
+
 ## Project ID behavior (verified)
 
 - `setup --project-id <A>` sets default proxy scope to project `A`.
@@ -193,6 +282,9 @@ Checks:
 - role profile -> local CLI availability
 - route dry-run / trigger-policy safety warnings
 - local provider token presence for active project destinations
+- enabled runner route -> local bot env binding resolution
+- enabled runner route -> server bot UUID cross-check
+- legacy `TELEGRAM_BOT_TOKEN` fallback still in use
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
 - `project.summary` access
@@ -266,6 +358,9 @@ Recommended production path:
 - keep `project_mappings.<project_id>.workspace_dir` aligned to that teammate's actual local project folder
 - let `ctxpack pull` or project connection refresh the mapping automatically
 - keep per-role execution policy under `role_profiles`
+- keep per-bot LLM binding primarily in `~/.metheus/telegram.env`
+- use `bot_bindings` in `bot-runner.json` only as local fallback/override
+- runner resolution order is: explicit `route.role_profile` -> provider env bot binding -> `bot_bindings` -> server bot role -> `route.role`
 
 Why `workspace_dir` matters:
 - the server cannot know each project member's local folder path
@@ -329,7 +424,7 @@ Notes:
 - `local-bot-bridge` reads stdin JSON from the runner and can call Codex/Claude/Gemini for you
 - `route.command` fallback is disabled by default; enable it only temporarily with `METHEUS_ALLOW_LEGACY_RUNNER_COMMAND=1`
 - today this automation path is implemented for Telegram end-to-end
-- set `METHEUS_TELEGRAM_API_BASE_URL=http://127.0.0.1:<port>` only for local mock or regression testing; normal usage should keep the default Telegram API base
+- prefer `TELEGRAM_API_BASE_URL=` inside `~/.metheus/telegram.env` for per-bot local Telegram API overrides; `METHEUS_TELEGRAM_API_BASE_URL` remains a process-level fallback mainly for mock/regression testing
 - 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
 - `doctor` now reports provider support for both enabled runner routes and active project chat destinations