星战科技xingzhan.cloud
返回市场
网格化MCP服务器

网格化MCP服务器

作者：app-sre2 星标更新：2025-08-27
安装使用来源：spider==github.com

项目介绍

Proms MCP Server

一个精简的MCP（模型上下文协议）服务器，提供LLM代理透明访问多个Prometheus实例进行指标分析和SRE操作。

概述

该服务器使用现代FastMCP库实现MCP协议，允许LLM代理通过统一接口查询多个Prometheus实例。它支持发现、查询和分析Prometheus指标，并内置了安全验证和全面的可观测性。

特性

  • 多Prometheus支持：通过单一接口查询多个Prometheus实例
  • Bearer Token认证：使用OpenShift Bearer令牌进行安全认证
  • 安全性增强：基本的PromQL查询验证以确保安全
  • 全面工具集：8个MCP工具覆盖发现、查询和分析，使用现代@tool装饰器
  • 可观测性：结构化日志用于调试和监控
  • 生产就绪：设计用于OpenShift/Kubernetes部署
  • 精简架构：无状态，最小依赖项（5个核心依赖项），快速失败设计

MCP工具

发现工具

  • list_datasources：列出所有可用的Prometheus数据源
  • list_metrics：从数据源获取所有可用的指标名称
  • get_metric_metadata：获取特定指标的元数据

查询工具

  • query_instant：执行即时PromQL查询
  • query_range：执行范围PromQL查询

分析工具

  • get_metric_labels：获取特定指标的所有标签名称
  • get_label_values：获取特定标签的所有值
  • find_metrics_by_pattern：查找匹配正则表达式模式的指标

快速开始

前提条件

  • Python 3.11+
  • uv 用于依赖管理
  • Docker/Podman 用于容器开发

本地开发

# 克隆并设置
git clone <repository-url>
cd proms-mcp
make install

# 1. 登录到目标集群并获取您的令牌
oc login https://api.your-cluster.example.com:6443
export OPENSHIFT_TOKEN=$(oc whoami -t)

# 2. 使用您的令牌创建数据源配置
# 这假设您的OpenShift令牌可用于在Prometheus上进行身份验证
cat > local_config/datasources.yaml << EOF
datasources:
  - name: "my-prometheus"
    type: "prometheus"
    url: "https://prometheus.your-cluster.example.com"
    jsonData:
      httpHeaderName1: "Authorization"
    secureJsonData:
      httpHeaderValue1: "Bearer ${OPENSHIFT_TOKEN}"
EOF

# 3. 启动带有认证的服务器
make run-auth OPENSHIFT_API_URL=$(oc whoami --show-server)
# 或者不带认证运行服务器 - 与Prometheus的连接仍然会进行认证
make run

# 4. 配置您的MCP客户端（例如，使用Cursor和启用认证的proms-mcp）
cat > .cursor/mcp.json << EOF
{
  "mcpServers": {
    "proms-mcp-local-auth": {
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer ${OPENSHIFT_TOKEN}"
      }
    }
  }
}
EOF

容器开发

# 构建容器
podman build -t proms-mcp .

# 创建数据源配置（参见配置部分）
# 使用配置运行
podman run -p 8000:8000 \
  -v ./datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml:ro \
  proms-mcp

MCP客户端设置

Cursor集成

服务器支持两种认证模式：

开发（无认证）：

{
  "mcpServers": {
    "proms-mcp-dev": {
              "url": "http://localhost:8000/mcp/",
      "description": "开发服务器 - 无认证"
    }
  }
}

生产（Bearer Token认证）：

{
  "mcpServers": {
    "proms-mcp": {
      "url": "https://proms-mcp.apps.cluster.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-openshift-token-here"
      },
      "description": "具有OpenShift Bearer令牌认证的生产服务器"
    }
  }
}

⚠️ 安全提示：永远不要将.cursor/mcp.json中包含真实令牌的内容提交到Git。它已经在.gitignore中。

查看.cursor/mcp-examples.json以获取完整的配置示例，包括：

  • 开发和生产设置
  • 服务账户令牌配置
  • 多环境配置
  • SSL验证场景

其他MCP客户端

服务器通过HTTP暴露MCP：

  • 端点：POST http://localhost:8000/mcp/（或您部署的URL）
  • 协议：HTTP上的JSON-RPC 2.0
  • Content-Type：application/json
  • Accept：application/json, text/event-stream
  • 认证：当AUTH_MODE=active时，在Authorization头中使用Bearer令牌

📝 路径行为：服务器使用/mcp/（带尾部斜杠）以避免可能导致某些MCP客户端认证问题的HTTP 307重定向。始终在客户端配置中使用尾部斜杠。

配置

环境变量

  • PORT：MCP服务器端口（默认：8000）
  • HEALTH_METRICS_PORT：健康和指标服务器端口（默认：8080）
  • LOG_LEVEL：日志级别（默认：INFO）
  • GRAFANA_DATASOURCES_PATH：数据源配置文件路径（默认：/etc/grafana/provisioning/datasources/datasources.yaml）
  • QUERY_TIMEOUT：查询超时时间（秒，默认：30）

认证配置

服务器支持两种认证模式：

  • AUTH_MODE：认证模式（none或active，默认：active）
  • OPENSHIFT_API_URL：OpenShift API服务器URL（Bearer令牌认证所需）
  • OPENSHIFT_CA_CERT_PATH：CA证书文件路径（可选，仅需自定义证书时）

无认证模式（仅限开发）

# 显式禁用认证以供开发
AUTH_MODE=none uv run python -m proms_mcp

Bearer Token认证模式（默认）

# 使用Bearer令牌认证运行
AUTH_MODE=active \
OPENSHIFT_API_URL=https://api.cluster.example.com:6443 \
uv run python -m proms_m

认证实现： 服务器使用Kubernetes TokenReview API进行自我验证以认证OpenShift Bearer令牌。每个用户的令牌自行验证 - 不需要特殊的RBAC权限。认证由与FastMCP认证系统集成的自定义TokenReviewVerifier处理。

数据源配置

创建Grafana数据源配置YAML文件。只有type: "prometheus"的数据源会被处理。

示例datasources.yaml：

apiVersion: 1
prune: true
datasources:
  - name: "prod-prometheus"
    type: "prometheus"
    url: "https://prometheus-prod.example.com"
    access: "proxy"
    editable: false
    jsonData:
      httpHeaderName1: "Authorization"
    secureJsonData:
      httpHeaderValue1: "Bearer prod-token"
  - name: "demo-prometheus"
    type: "prometheus"
    url: "https://demo.robustperception.io:9090"
    access: "proxy"
    editable: false

安全

PromQL查询验证

服务器实现了基本的安全检查：

  • 查询长度：限制为10,000字符
  • 空查询：防止空或仅包含空白字符的查询
  • 输入清理：通过httpx进行基本参数编码

API端点

  • POST /mcp/：MCP JSON-RPC 2.0端点（端口8000）
  • GET /health：健康检查（端口8080）
  • GET /metrics：Prometheus指标（端口8080）

部署

OpenShift部署

使用提供的OpenShift模板进行部署：

# 开发部署（无认证）
oc process -f openshift/deploy.yaml \
  -p IMAGE=quay.io/app-sre/proms-mcp \
  -p IMAGE_TAG=latest \
  -p AUTH_MODE=none \
  | oc apply -f -

# 生产部署（Bearer令牌认证）
oc process -f openshift/deploy.yaml \
  -p IMAGE=quay.io/app-sre/proms-mcp \
  -p IMAGE_TAG=v1.0.0 \
  -p AUTH_MODE=active \
  -p OPENSHIFT_API_URL=https://api.cluster.example.com:6443 \
  | oc apply -f -

# 不需要额外的RBAC设置 - 服务器使用自我验证

模板参数：

  • AUTH_MODE：none（开发）或active（生产，默认）
  • OPENSHIFT_API_URL：OpenShift API服务器URL（默认：https://kubernetes.default.svc，针对集群内部）
  • OPENSHIFT_CA_CERT_PATH：CA证书路径（默认：集群内部服务账户CA）
  • NAMESPACE：目标命名空间（必需）
  • HOSTNAME：路由主机名（必需）

MCP客户端配置

开发模式（无认证）

{
  "mcpServers": {
    "proms-mcp-dev": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

生产模式（Bearer Token）

{
  "mcpServers": {
    "proms-mcp": {
      "url": "https://proms-mcp.apps.cluster.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OPENSHIFT_TOKEN}"
      }
    }
  }
}

获取您的OpenShift令牌：

export OPENSHIFT_TOKEN=$(oc whoami -t)

RBAC需求

对于生产（Bearer令牌认证）部署：

  1. ServiceAccount：proms-mcp-server（由模板创建） - 仅用于pod身份
  2. 无需特殊RBAC权限：服务器使用自我验证，每个用户的令牌自行验证
  3. 用户令牌：用户需要有效的OpenShift令牌（oc whoami -t）

模板为pod身份创建ServiceAccount。由于认证使用自我验证，因此不需要ClusterRoleBindings或特殊权限。

开发

代码质量

make format          # 格式化代码并修复导入
make lint            # 检查代码并进行类型检查
make test            # 运行测试并生成覆盖率报告

项目结构

proms-mcp/
  proms_mcp/             # 主要包
    auth.py                # 基于TokenReview的身份验证，与FastMCP集成
    server.py              # 包含8个MCP工具的FastMCP服务器
    client.py              # Prometheus API封装
    config.py              # 支持认证的配置解析器
    monitoring.py          # 健康/指标端点
    logging.py             # 结构化日志配置
  tests/                   # 测试套件（镜像包结构）
  openshift/deploy.yaml    # 带有RBAC支持的OpenShift模板
  local_config/            # 本地开发配置

故障排除

常见问题

  1. 未加载数据源：
    • 检查GRAFANA_DATASOURCES_PATH是否指向您的数据源文件
    • 验证YAML语法是否有效（也支持JSON格式）
    • 确保文件包含一个datasources数组，其中包含type: "prometheus"条目
    • 使用make run，它会自动将路径设置为local_config/datasources.yaml
  2. 认证失败：验证secureJsonData中的Bearer令牌
  3. 查询超时：调整QUERY_TIMEOUT环境变量
  4. 查询验证错误：检查查询长度并确保非空查询
  5. 客户端连接问题：
    • 400 Bad Request：重启服务器 - 客户端将自动重新连接
    • 406 Not Acceptable：客户端必须接受application/json, text/event-stream

调试模式

LOG_LEVEL=DEBUG make run

健康检查

curl http://localhost:8080/health
curl http://localhost:8080/metrics | grep mcp_

文档

  • SPECS.md - 技术规范和架构
  • LLM.md - AI助手开发指南
  • TESTING.md - 带Bearer令牌示例的本地测试指南

贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 带有测试的更改
  4. 运行质量检查：make format lint test
  5. 提交拉取请求

许可

Apache License 2.0