# rocketchat-mcp-server

A **FastMCP (Python)** server for Rocket.Chat — 28 tools with AI governance,
observability, and monitoring built in. A ground-up rewrite of the Go server
`rocketchat-mcp-go`, applying the systematic MCP-server approach in
[ADR 0001](docs/adr/0001-systematic-approach-to-mcp-servers.md).

## Highlights

- **28 tools** across channels, messages, threads, DMs, files, users, and analytics.
- **Token economy**: message grouping (consecutive same-user merge), compact mode,
  parallel thread expansion, server-side channel digests.
- **Governance**: `READ_ONLY` mode (write tools hidden), per-tool `readOnlyHint`/
  `destructiveHint` annotations, optional human-in-the-loop approval for
  consequential writes, structured audit events, and a bearer-token gateway.
- **Observability**: structlog JSON logs with secret redaction, per-tool logging
  middleware, `/metrics` (Prometheus), optional OpenTelemetry tracing, and
  `/healthz` + `/readyz`.
- **Security**: SSRF host guard + 25 MB cap on downloads, filename escaping on
  uploads, URL scheme validation, bounded pagination. See
  [the security review](docs/security/SNICKERS-REVIEW-2026-07-13.md).

## Quick start

```bash
uv sync --extra dev --extra metrics

export ROCKETCHAT_URL="https://chat.example.com"
export ROCKETCHAT_AUTH_TOKEN="<personal access token>"
export ROCKETCHAT_USER_ID="<user id>"

# HTTP (Streamable) transport on :8000, endpoint /mcp
uv run rocketchat-mcp --mode http

# stdio transport (local MCP clients)
uv run rocketchat-mcp --mode stdio
```

## Configuration

Go-compatible env vars are preserved: `ROCKETCHAT_URL`, `ROCKETCHAT_AUTH_TOKEN`,
`ROCKETCHAT_USER_ID`, `READ_ONLY`, `MCP_PORT`. New settings use the `RCMCP_`
prefix — notably `RCMCP_APPROVE_WRITES`, `RCMCP_GATEWAY_TOKENS`
(`token:principal,...`), `RCMCP_READ_ONLY`, `RCMCP_ENABLE_METRICS`,
`RCMCP_LOG_JSON`. See [`config.py`](src/rocketchat_mcp/config.py).

> **Security note:** the HTTP transport should sit behind the bearer-token
> gateway (`RCMCP_GATEWAY_TOKENS`) and TLS termination (Traefik/nginx). The
> server holds a single Rocket.Chat identity — every authorised caller shares
> its permission ceiling.

## Development

```bash
uv run ruff check .
uv run mypy src
uv run pytest -m "not live"   # default: respx-mocked, no live server needed
```

### Live integration tests

`tests/test_live.py` exercises the server against a **real** Rocket.Chat. They
are excluded from the default suite and CI, and only touch a dedicated test
channel (default `mcp-test`), cleaning up every message they create. The
configured account must be a member of that channel.

```bash
RCMCP_LIVE=1 RCMCP_TEST_CHANNEL=mcp-test \
ROCKETCHAT_URL=... ROCKETCHAT_AUTH_TOKEN=... ROCKETCHAT_USER_ID=... \
uv run pytest -m live
```

Pin/react tests skip automatically when the account lacks those permissions.

## Deployment

- **Docker / Podman:** `Dockerfile` builds a non-root OCI image. A systemd
  quadlet unit is in [`deploy/quadlet/`](deploy/quadlet/).
- **Release:** tag `v*` triggers the multi-arch nexus push workflow.

## Architecture Decision Records

This server is built to a documented, systematic standard. The design rationale
lives in ADRs under [`docs/adr/`](docs/adr/):

- [ADR 0001 — A systematic approach to building MCP servers](docs/adr/0001-systematic-approach-to-mcp-servers.md)
  — the house standard for architecture, AI governance, observability, and
  engineering practice that this repository implements.
- [ADR 0002 — Per-principal upstream identity (multi-tenant)](docs/adr/0002-per-principal-upstream-identity.md)
  — opt-in per-caller Rocket.Chat credentials so actions are attributable.

New consequential decisions are recorded as additional numbered ADRs.

## Documentation

- [System design](docs/design/SYSTEM-DESIGN.md) — FastMCP adoption design, tool
  parity, delivery phases.
- [Bot identity](docs/BOT-IDENTITY.md) — message alias vs a dedicated bot
  account, and how to set one up.
- [Cutover runbook](docs/CUTOVER.md) — migrating from the Go server and retiring it.
- [Architecture Decision Records](docs/adr/) — see above.
- [Security review](docs/security/SNICKERS-REVIEW-2026-07-13.md) — Snickers /
  Snyk agent-security findings and their dispositions.

## Provenance

A ground-up FastMCP (Python) rewrite of the Go server `rocketchat-mcp-go`,
applying lessons from `openproject-gt-mcp-server` (layered architecture,
observability, human-in-the-loop) and `redmine-mcp-server` (tag-based tool
visibility, `{error, hint, code}` envelope, secret scrubbing). Tracked under
OpenProject **AI and Automation / EPIC #9810**.