内容
# rocketchat-mcp-server
**FastMCP（Python）** 服务器，用于 Rocket.Chat — 28 种工具，具备 AI 治理、 可观察性和监控功能。基于 Go 服务器 `rocketchat-mcp-go` 重写，采用 [ADR 0001](docs/adr/0001-systematic-approach-to-mcp-servers.md) 中定义的系统化 MCP 服务器方法。
## 亮点
- **28 种工具**，涵盖渠道、消息、线程、直接消息、文件、用户和数据分析。
- **代币经济**：消息分组（连续相同用户合并）、紧凑模式、 并行线程扩展、服务器端渠道摘要。
- **治理**：`READ_ONLY` 模式（隐藏写入工具）、每个工具的 `readOnlyHint` / `destructiveHint` 注解、可选的人工审批流程、结构化审计事件和 bearer-token 网关。
- **可观察性**：structlog JSON 日志（带有秘密删除）、每个工具的日志中间件、`/metrics`（Prometheus）、可选的 OpenTelemetry 跟踪和 `/healthz` + `/readyz`。
- **安全性**：SSRF 主机防护 + 下载大小上限（25 MB）、上传文件名转义、URL 方案验证、有限分页。参见 [安全审查](docs/security/SNICKERS-REVIEW-2026-07-13.md)。
## 快速开始
```bash
uv sync --extra dev --extra metrics
export ROCKETCHAT_URL="https://chat.example.com"
export ROCKETCHAT_AUTH_TOKEN="<个人访问令牌>"
export ROCKETCHAT_USER_ID="<用户 ID>"
# HTTP（可流式传输）传输，监听 :8000，端点 /mcp
uv run rocketchat-mcp --mode http
# 标准输入/输出传输（本地 MCP 客户端）
uv run rocketchat-mcp --mode stdio
```
## 配置
兼容 Go 的环境变量得以保留：`ROCKETCHAT_URL`、`ROCKETCHAT_AUTH_TOKEN`、`ROCKETCHAT_USER_ID`、`READ_ONLY`、`MCP_PORT`。新设置使用 `RCMCP_` 前缀 — 特别是 `RCMCP_APPROVE_WRITES`、`RCMCP_GATEWAY_TOKENS`（`token:principal,...`）、`RCMCP_READ_ONLY`、`RCMCP_ENABLE_METRICS`、`RCMCP_LOG_JSON`。参见 [`config.py`](src/rocketchat_mcp/config.py)。
> **安全注意：** HTTP 传输应位于 bearer-token 网关（`RCMCP_GATEWAY_TOKENS`）和 TLS 终止（Traefik/nginx）之后。服务器持有单个 Rocket.Chat 身份 — 所有授权调用者共享其权限上限。
## 开发
```bash
uv run ruff check .
uv run mypy src
uv run pytest -m "not live" # 默认：respx 模拟，无需真实服务器
```
### 真实集成测试
`tests/test_live.py` 在 **真实** 的 Rocket.Chat 实例上测试服务器。这些测试被排除在默认测试套件和 CI 之外，仅涉及专用测试渠道（默认为 `mcp-test`），并清理创建的每个消息。配置的账户必须是该渠道的成员。
```bash
RCMCP_LIVE=1 RCMCP_TEST_CHANNEL=mcp-test \
ROCKETCHAT_URL=... ROCKETCHAT_AUTH_TOKEN=... ROCKETCHAT_USER_ID=... \
uv run pytest -m live
```
当账户缺乏这些权限时，Pin/react 测试将自动跳过。
## 部署
- **Docker / Podman：** `Dockerfile` 构建一个非 root OCI 镜像。在 [`deploy/quadlet/`](deploy/quadlet/) 中有一个 systemd quadlet 单元。
- **发布：** 标签 `v*` 触发多架构 nexus 推送工作流。
## 架构决策记录
该服务器按照文档化的、系统化标准构建。设计原理在 [`docs/adr/`](docs/adr/) 下的 ADRs 中：
- [ADR 0001 — 构建 MCP 服务器的系统化方法](docs/adr/0001-systematic-approach-to-mcp-servers.md)
— 本仓库实施的架构、AI 治理、可观察性和工程实践的标准。
- [ADR 0002 — 按主体划分的上游身份（多租户）](docs/adr/0002-per-principal-upstream-identity.md)
— 按调用者划分的可选 Rocket.Chat 凭证，以便操作可归因。
新的重要决策作为额外的编号 ADR 记录。
## 文档
- [系统设计](docs/design/SYSTEM-DESIGN.md) — FastMCP 采用设计、工具一致性、交付阶段。
- [机器人身份](docs/BOT-IDENTITY.md) — 消息别名与专用机器人账户，以及如何设置。
- [切换运行手册](docs/CUTOVER.md) — 从 Go 服务器迁移并将其停用。
- [架构决策记录](docs/adr/) — 见上。
- [安全审查](docs/security/SNICKERS-REVIEW-2026-07-13.md) — Snickers / Snyk 代理安全发现及其处置。
## 来源
`rocketchat-mcp-go` Go 服务器的从头开始的 FastMCP（Python）重写，应用了 `openproject-gt-mcp-server`（分层架构、 可观察性、人工介入）和 `redmine-mcp-server`（基于标签的工具可见性、 `{error, hint, code}` 信封、秘密清理）的经验教训。在 OpenProject **AI 和自动化 / EPIC #9810** 下跟踪。
