comms-mcp

# comms-mcp — full LLM reference (v0.9.1)

Unified fleet comms gateway. One portmanteau tool `comms_ops` with operations
send / read_recent / list_threads / status / auth / help / history / search /
react / edit / delete, plus `comms_shutdown`,
resource `comms://status`, prompt `comms_send_briefing`, skill `skill://comms`.
Web console has one page per service (/telegram, /whatsapp, /slack, /teams,
/signal) backed by GET|POST /api/v1/channel/{channel}/{threads,history,send}.

## Install

git clone https://github.com/sandraschi/comms-mcp; cd comms-mcp; copy .env.example .env
Per-channel setup (2-5 min each): docs/ONBOARDING.md
just serve  (or uv run python -m comms_mcp; MCP_PORT=11205 -> HTTP daemon)

## Tools

comms_ops(operation="send", channel="telegram|whatsapp|slack|teams|signal", chat_id="<id>", text="<body>")
  - allowlist-gated per channel; returns {success, message, outbox_id, message_id|ts}
comms_ops(operation="read_recent", channel="telegram")
  - polls getUpdates, sanitizes inbound, returns recent messages
comms_ops(operation="list_threads", channel="...")  -> allowlist for the channel
comms_ops(operation="status", channel="...")        -> identity + configured + allowlist + stats
comms_ops(operation="auth", channel="teams")        -> Graph device-code start/poll
comms_ops(operation="help", channel="...")          -> per-channel setup steps
comms_shutdown(confirm=True)                        -> orderly daemon exit (500 ms)
comms_show_status()                                 -> Prefab status card (bot, allowlist, outbox stats)

## Config (env, prefix COMMS_)

TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_IDS, TELEGRAM_API_BASE,
WHATSAPP_SIDECAR_URL, WHATSAPP_ALLOW_NUMBERS,
SLACK_APP_TOKEN, SLACK_BOT_TOKEN, SLACK_CHANNEL_IDS,
GRAPH_CLIENT_ID, TEAMS_RECIPIENTS, TEAMS_TOKEN_FILE, TEAMS_GRAPH_BASE,
DB_PATH, RETENTION_DAYS (7), INBOUND_SECRET, DAEMON_URL,
MCP_PORT / PORT, MCP_HOST

## Architecture

FastMCP server; adapters/<channel>.py (allowlist + send + inbound); outbox/sqlite.py
(outbox pending/sent/failed + inbound with TTL); sanitize.py (inbound
injection neutralization); FastAPI REST + MCP streamable-HTTP at /mcp (daemon
mode). Stdio instances probe the daemon and proxy when reachable.
Dual transport per SOTA_REQUIREMENTS 2.3.

## REST (HTTP daemon mode, MCP_PORT=11205)

- GET /health — status + stats
- GET /api/capabilities — server/channels/tools/endpoints
- GET /api/skills — skill listing (skill-first agents)
- GET /api/v1/outbox?status=&limit= — delivery log
- GET /api/v1/inbound?chat_id=&limit= — recent inbound
- GET /api/v1/status — bot + allowlist + stats
- GET /api/v1/channels — per-channel setup state (no secrets)
- GET /api/v1/allowlists — per-channel send allowlists (no secrets)
- GET /api/v1/channel/{channel}/threads — thread picker (live list or allowlist)
- GET /api/v1/channel/{channel}/history?chat_id=&limit= — live (slack/teams) or local store
- POST /api/v1/channel/{channel}/send — {chat_id, text, thread_ts?, parse_mode?}, allowlist-gated
- POST /api/v1/send — {chat_id, text}, allowlist-gated
- POST /api/v1/inbound/wa — wa-sidecar webhook (X-Comms-Secret when set)
- POST /api/shutdown — orderly exit (NSSM-safe bounce)
- /mcp — MCP streamable HTTP (both /mcp and /mcp/ answer)

## Ports

11205 backend (FastAPI + FastMCP /mcp), 11204 console (Vite dev; served from
backend root via web_sota/dist in daemon mode), 11208 wa-sidecar.

## Troubleshooting

- status shows configured:false -> token missing/empty
- send blocked: chat not in allowlist -> add to the channel allowlist env
- 404 from Telegram -> token wrong or pasted with "bot" prefix
- wa 503: sidecar not connected -> re-scan QR (:11208/qr)
- Full table: docs/TROUBLESHOOTING.md