内容
# 观测性MCP服务器
一个 **MCP（模型上下文协议）服务器**，允许AI代理（Claude Code / Cursor）通过一个统一的、带有仪表盘的工具表面查询你的观测性堆栈 — **VictoriaMetrics**、**VictoriaLogs**、**Prometheus** 和 **Alertmanager** — 可用的数据源完全由配置驱动，每个数据源可以直接访问 **或通过`vmauth`代理**（带有可选的基本身份验证/持有者身份验证和自定义CA）。
它是 [`kubernetes-mcp`](https://github.com/truepace-io-oss/kubernetes-mcp-server) 的观测性兄弟姐妹：相同的代理身份验证模型（静态持有者令牌 + Authentik/Keycloak OIDC），相同的 Prometheus 自我指标 + Grafana 仪表盘，相同的 Helm 图表 / CI / GitOps 部署约定。
## 数据源兼容性
| 后端 | 状态 | 备注 |
|---|---|---|
| VictoriaMetrics（单节点 & 集群 `vmselect`） | ✅ 支持 | Prometheus `/api/v1/*` 查询 API；直接或通过 `vmauth`。集群模式使用 `pathPrefix: /select/0/prometheus`。 |
| Prometheus | ✅ 支持 | Prometheus 兼容的 `/api/v1/*`。 |
| VictoriaLogs（单节点 & 集群 `vlselect`） | ✅ 支持 | LogsQL via `/select/logsql/*`；直接或通过 `vmauth`。 |
| Alertmanager（包括 `vmalertmanager`） | ✅ 支持 | v2 API；读取 + 静默创建/删除（写入是只读保护的）。 |
| Loki | 🔜 计划中 | LogQL — 候选 `loki` 数据源类型。 |
| Thanos / Cortex / Mimir | 🔜 计划中 | Prometheus-API 兼容；可能像今天的 `prometheus` 一样工作。 |
| Jaeger / Tempo（跟踪） | 🔜 已考虑 | 单独的工具组。 |
参见 [`docs/datasources.md`](docs/datasources.md) 了解如何添加和配置数据源，以及如何添加 **新的数据源类型**。
## 拓扑
```mermaid
flowchart LR
agent["AI 代理<br/>(Claude Code / Cursor)"] -->|可流式 HTTP + OIDC/持有者令牌| mcp["观测性MCP"]
subgraph mcp_internal["观测性MCP"]
reg["数据源注册表"]
end
mcp --> reg
reg -->|/api/v1| vm["VictoriaMetrics / Prometheus"]
reg -->|/select/logsql| vl["VictoriaLogs"]
reg -->|/api/v2| am["Alertmanager"]
reg -.->|基本/持有者身份验证| vmauth["vmauth 代理"]
vmauth --> vm
vmauth --> vl
```
## 请求流程
```mermaid
sequenceDiagram
participant A as AI 代理
participant M as 观测性MCP（/mcp）
participant D as 数据源（VM/日志/AM）
A->>M: 1. 身份验证（静态持有者令牌或 OIDC JWT）— 可选
A->>M: 2. 调用工具（例如 metrics_query{datasource,query}）
M->>M: 从注册表解析数据源，检查类型 + 只读保护
M->>D: 3. HTTP 请求（可选数据源身份验证 / vmauth）
D-->>M: JSON / NDJSON
M-->>A: 紧凑的、适合 LLM 的文本结果
```
两个独立的保护措施：**代理 → MCP** 身份验证（谁可以调用 MCP）和 **MCP → 数据源** 身份验证（MCP 如何访问后端）。它们分别配置。
## 工具
| 组 | 工具 |
|---|---|
| 常用 | `datasources_list` |
| 指标（`victoriametrics`/`prometheus`） | `metrics_query`、`metrics_query_range`、`metrics_series`、`metrics_labels`、`metrics_label_values`、`metrics_metadata`、`rules_list`、`alerts_active`、`targets_list` |
| 日志（`victorialogs`） | `logs_query`、`logs_hits`、`logs_stats`、`logs_field_names`、`logs_field_values`、`logs_streams` |
| Alertmanager | `alertmanager_alerts`、`alertmanager_alert_groups`、`alertmanager_silences_list`、`alertmanager_silence_get`、`alertmanager_status`、`alertmanager_receivers`、**（写入）** `alertmanager_silence_create`、`alertmanager_silence_delete` |
每个工具都带有可选的 `datasource` 参数（默认为已配置的默认数据源）。当实例（`readOnly: true`）或目标数据源（`readOnly: true`）为只读时，写入工具会被阻止。
## 快速开始
```bash
cat > /tmp/omcp.yaml <<'EOF'
defaultDatasource: vm
datasources:
- name: vm
type: victoriametrics
url: http://localhost:8428 # 单节点 VM；为集群添加 pathPrefix
- name: logs
type: victorialogs
url: http://localhost:9428
EOF
go run . --config /tmp/omcp.yaml
# MCP 在 :9090/mcp 上，自我指标在 :9091/metrics 上
```
参见 [`examples/config.yaml`](examples/config.yaml) 获取完整示例（所有类型、vmauth、身份验证）。
## 配置代理
```bash
claude mcp add --transport http observability https://observability-mcp.tools.averion.zone/mcp
```
对于通过 Authentik 的 OIDC，您必须提供 `client_id` 和身份验证服务器元数据 URL — 参见
[`examples/mcp.claude.json`](examples/mcp.claude.json)、[`examples/mcp.cursor.json`](examples/mcp.cursor.json)
和 [`docs/auth.md`](docs/auth.md)。
## 部署（Helm + ESO）
```bash
helm install obs deploy/helm/observability-mcp -n observability-mcp --create-namespace \
--set 'datasources[0].name=vm' \
--set 'datasources[0].type=victoriametrics' \
--set 'datasources[0].url=http://vmselect-...:8481' \
--set 'datasources[0].pathPrefix=/select/0/prometheus' \
--set config.defaultDatasource=vm
```
通过 `environments` GitOps 仓库（Authentik OIDC、ESO/Bitwarden、ingress）的生产部署在 [`docs/environments-integration.md`](docs/environments-integration.md) 中有文档。
## 安全模型
- **代理身份验证**（可选、可插拔）：静态持有者令牌和/或 OIDC（Authentik/Keycloak）。启用时始终在 TLS 后面运行。
- **数据源身份验证**（可选，按数据源）：基本或持有者，加上自定义 CA / `insecureSkipTLSVerify` — 这是 `vmauth` 代理所需的内容。
- **只读保护**：全局 `readOnly` 切换和按数据源的 `readOnly` 阻止 Alertmanager 写入工具（在后端的自身身份验证基础上进行防御性保护）。
- 代理身份验证 ≠ 数据源身份验证：对调用者进行身份验证以访问 MCP 不会改变 MCP 可以对后端执行的操作。
## 指标
Prometheus 自我指标在单独的、无身份验证的端口上提供（默认为 `:9091`）：每个工具的使用情况/延迟/结果、代理身份验证结果、出站数据源请求（带有状态代码）+ 延迟和数据源可达性。图表和 Grafana 仪表盘随 Helm 图表一起提供。参见 [`docs/metrics.md`](docs/metrics.md)。
## 测试
```bash
make test # 单元测试（httptest 模拟；不需要真正的后端）
make test-e2e # 完整的 MCP 服务器通过 HTTP 与伪造的 VM/日志/AM 后端
make lint # go vet + gofmt
```
## 开发
Go 1.25+，[MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)，和标准库 HTTP。包：`internal/config`、`internal/datasources`、`internal/promapi`、`internal/logsql`、`internal/alertmanager`、`internal/mcpserver`、`internal/auth`、`internal/metrics`。参见 [`docs/architecture.md`](docs/architecture.md)。
