内容
# CentralOps MCP 服务器
模型上下文协议（MCP）服务器，暴露了CentralOps HTTP API的精选子集，作为类型化的工具，内部开发者可以通过Claude Code驱动漂移分类、映射编辑、回填作业和隔离重新处理，而无需编写原始HTTP调用。
服务器在容器内作为stdio MCP传输运行 — Claude Code在每个会话中启动`docker run --rm -i ...`，无需在CentralOps组合栈中添加额外的服务，也无需暴露端口。
## 状态
稳定且可用于内部。 通过在`/settings/tokens`处颁发的**个人访问令牌（PAT）**或**服务账户令牌**进行身份验证 — 与外部集成使用的相同凭证模型。 在Fase 2（`feat(pat): …`下的提交历史记录）中移除了Cookie /会话身份验证。
## 工具
25种工具，按代理可见或执行的操作分组。
### 供应商端可见性（读取）
供应商的连接、健康状况和行为。
| 工具 | 目的 |
| --- | --- |
| `list_integrations` | 已连接的供应商、状态、last_error、功能。 |
| `get_integration` | 一个集成的完整配置（除非允许，否则机密将被掩盖）。 |
| `get_integration_health` | 即时健康检查（Wazuh的管理器+索引器，Sophos的OAuth...）。 |
| `get_integration_overview` | 聚合仪表盘：计数器、最近活动、每个流的摘要。 |
| `list_integration_alerts` | 已收集并规范化的集成警报。 |
| `list_supported_platforms` | 后端可以连接的平台。 |
### 采集管道（读取）
正在采集的内容及来源。
| 工具 | 目的 |
| --- | --- |
| `list_collector_vendors` | 采集器知道如何采集的（平台、流）对。 |
| `list_collection_state` | 每个流的光标、last_success_at、last_error、consecutive_failures。 |
| `get_collector_summary` | 用户可见的所有集成的全局视图。 |
### 原始有效载荷和漂移（读取 — *“供应商发送的内容是什么？”集合*）
| 工具 | 目的 |
| --- | --- |
| `get_mapping_samples` | 来自样本库的原始事件，适用于（供应商、事件类型）— 采集器接收的实际JSON。 |
| `get_quarantine_event` | 一个隔离的事件及其完整的`raw_payload` — 当特定形状破坏映射时很有用。 |
| `list_quarantine` | 隔离的事件，可按供应商/集成/错误类型过滤。 |
| `list_drift_fields` | 漂移采样器观察到的未知原始字段，但没有映射使用。 |
| `discover_mapping_fields` | 为此映射的供应商/事件类型发现的字段 — JMESPath自动完成源。 |
### 映射目录和历史（读取）
| 工具 | 目的 |
| --- | --- |
| `list_mappings` | 映射定义目录。 |
| `get_mapping` | 单个映射的定义+版本历史记录。 |
| `diff_mapping_versions` | 两个映射版本之间的结构化差异。 |
| `list_mapping_audit` | 谁在何时更改了什么。 |
### 回填（读取）
| 工具 | 目的 |
| --- | --- |
| `list_backfill_jobs` | 集成作业。 |
| `get_backfill_job` | 一个作业快照。 |
### 变异 — 安全
| 工具 | 目的 |
| --- | --- |
| `dry_run_mapping` | 验证规则是否与样本库冲突。调用时附带`ack_token`。 |
| `request_backfill` | 排队一个回填窗口（最多90天）。返回`job_id`。 |
| `reprocess_quarantine` | 重新处理最多50个隔离事件。后台是幂等的。 |
### 破坏性 — 需要权限
| 工具 | 目的 |
| --- | --- |
| `commit_mapping` | 推广新映射版本。需要与`dry_run_mapping`相同的`definition_id`和规则的`ack_token`。 |
### 帮助
| 工具 | 目的 |
| --- | --- |
| `wait_for_backfill_job` | 服务器端轮询，直到终端状态。避免LLM轮询循环。 |
`commit_mapping`是唯一具有破坏性的工具。它需要`dry_run_mapping`为相同的`definition_id`和规则颁发的`ack_token`；该令牌在5分钟内过期且仅可使用一次。 CentralOps后台重新验证并重新运行提交时的预运行，因此这是防御深度，而不是安全边界。
## 身份验证
MCP服务器在每个请求上发送`Authorization: Bearer <token>`。在CentralOps中生成令牌：
1. 以应该“拥有”MCP流量的用户身份登录CentralOps。
2. 进入**设置 → API令牌**（`/settings/tokens`）。
3. 点击**Criar token**，给予其一个名称（例如`claude-code-mcp`），选择一个过期时间（或选择“永不过期”以实现稳定的开发工作流），并**复制`copsk_…`值** — 该值仅显示一次。
4. 可选：选择范围。如果没有范围，令牌将继承用户的完整权限集。对于只需要读取漂移/映射的MCP，限制为例如`mappings.read`、`quarantine.read`、`integrations.read`、`audit.read`。
5. 在shell中导出令牌或将其粘贴到下面的MCP配置中。
令牌可以从同一页面单独撤销 — 丢失笔记本电脑或合同终止不再意味着轮换共享的cookie。
每个请求都发送`X-Client: centralops-mcp/<version>`标头，以便后端审计日志可以将MCP流量与UI流量区分开来。
当令牌被拒绝时，工具返回401，并提示在`/settings/tokens`处重新生成。当令牌**有效**但缺乏工具所需的范围时，响应为403，并附有权限提示。
## 配置
| 环境变量 | 默认值 | 是否必需 | 备注 |
| --- | --- | --- | --- |
| `CENTRALOPS_BASE_URL` | `http://localhost:3000/api` | 推荐 | URL以`/api`结尾。 |
| `CENTRALOPS_API_TOKEN` | — | **是** | 以`copsk_`开头的PAT或服务账户令牌。在`<base_url>/settings/tokens`处生成。 |
| `CENTRALOPS_TIMEOUT_S` | `30` | 否 | 每个请求的超时时间。 |
| `CENTRALOPS_VERIFY_TLS` | `1` | 否 | 仅在自签名开发环境中设置为`0`。 |
| `CENTRALOPS_LOG_LEVEL` | `WARNING` | 否 | `DEBUG`跟踪stderr上的请求。 |
## 构建
```bash
docker build -t centralops-mcp:dev mcp/
```
## 从Claude Code使用
将以下内容添加到`.mcp.json`（项目）或Claude Code用户设置中：
```json
{
"mcpServers": {
"centralops": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CENTRALOPS_BASE_URL",
"-e", "CENTRALOPS_API_TOKEN",
"centralops-mcp:dev"
],
"env": {
"CENTRALOPS_BASE_URL": "https://centralops.local/api",
"CENTRALOPS_API_TOKEN": "copsk_..."
}
}
}
}
```
然后重启Claude Code并运行`/mcp`以确认工具已列出。
> 令牌是敏感的 — 不要在`.mcp.json`中提交具有真实值的令牌。优先从shell读取，例如`CENTRALOPS_API_TOKEN=$(pbpaste)`，或存储在秘密管理器（1Password，macOS Keychain等）中。
## 本地开发
```bash
cd mcp
python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install pytest pytest-asyncio
.venv/bin/pytest
```
## 烟雾测试镜像
MCP握手需要`initialize` → `notifications/initialized` → `tools/list`。尾随的`sleep`保持stdin打开足够长的时间，以便服务器在EOF关闭管道之前发出第二个响应：
```bash
{
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
sleep 2
} | docker run --rm -i \
-e CENTRALOPS_BASE_URL="http://localhost:3000/api" \
-e CENTRALOPS_API_TOKEN="copsk_..." \
centralops-mcp:dev
```
您应该看到两个JSON-RPC响应；第二个包含所有11种工具及其架构。
