MCP Prometheus Server

MCP Prometheus 服务

概述

这是一个可用于生产环境的 Haskell Model Context Protocol（MCP）服务实现，可让 Claude Desktop 访问 Prometheus 指标和查询。项目遵循 Haskell 最佳实践，包括妥善处理异常、严格求值模式和全面的错误恢复。

“The Adeon Special”——v1.0.1 融合了先进的 Haskell 技术，可避免常见陷阱并确保线程安全、稳定运行。

功能特性

• 🚀 Claude Desktop 集成 - 无缝支持 MCP 协议
• 📊 完整的 Prometheus API - 查询、发现和探索指标
• 🔍 5 个强大工具 - 从即时查询到指标发现
• 🛡️ 可用于生产环境 - 全面的错误处理和日志记录
• 🧵 线程安全 - 严格求值可防止惰性 I/O 挂起
• 🔧 Haskell 最佳实践 - 妥善处理异常，不使用 SomeException 反模式
• 🧪 测试覆盖 - 包含单元测试和集成测试

快速开始

选项 1：使用预构建二进制文件（推荐）

1. 克隆仓库：

git clone https://github.com/drewstreib/mcp-prom-haskell.git
cd mcp-prom-haskell/mcp-prometheus-server

2. 使用预构建二进制文件：

./testbin/mcp-prometheus-server --prometheus-url http://your-prometheus-server:9090

选项 2：从源代码构建

make build
# Binary will be in testbin/mcp-prometheus-server

选项 3：Docker（开发）

# Start test Prometheus instance
docker-compose up -d prometheus

# Build and run
docker build -t mcp-prometheus-server .
docker run -it --rm \
  --network mcp-prometheus-server_mcp-network \
  -e PROMETHEUS_URL=http://prometheus:9090 \
  mcp-prometheus-server

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "prometheus": {
      "command": "/path/to/mcp-prom-haskell/mcp-prometheus-server/testbin/mcp-prometheus-server",
      "args": [
        "--prometheus-url",
        "http://your-prometheus-server:9090"
      ]
    }
  }
}

将 /path/to/ 替换为仓库的实际路径。

可用工具

1. prometheus_query

在特定时间点执行即时 PromQL 查询。

示例：“当前 CPU 使用率是多少？”

rate(node_cpu_seconds_total[5m])

2. prometheus_query_range

在一段时间范围内执行查询，以进行趋势分析。

示例：“显示过去一小时的内存使用情况”

node_memory_Active_bytes

3. prometheus_series

查找符合特定标签选择器的时间序列。

示例：“node-exporter 作业有哪些可用指标？”

4. prometheus_metrics

列出系统中所有可用的指标名称。

示例：“我可以查询哪些指标？”

5. prometheus_labels

发现各项指标使用的所有标签名称。

示例：“有哪些标签可用于筛选？”

Haskell 实现细节

本服务展示了可用于生产环境的 Haskell 实践：

异常处理

• 不使用 SomeException 反模式 - 仅捕获特定且可恢复的异常
• I/O 操作使用 IOException - 妥善处理 stdin/stdout 故障
• 网络调用使用 HttpException - 提供详细的 Prometheus 连接错误信息

线程安全与性能

• 使用 BangPatterns 进行严格求值 - 防止日志记录中的惰性 I/O 挂起
• 带时间戳的结构化日志 - 线程安全、原子化的日志写入
• UTF-8 文本处理 - 全程正确支持 Unicode

JSON-RPC 合规性

• 妥善处理通知 - 按照规范，不对通知作出响应
• 类型安全的消息解析 - 全面的错误恢复
• 协议版本匹配 - 完全兼容 Claude Desktop

手动安装

先决条件

• GHC 9.12+ 和 Cabal 3.0+
• 或使用 GHCup（推荐）：

curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

构建

git clone https://github.com/drewstreib/mcp-prom-haskell.git
cd mcp-prom-haskell/mcp-prometheus-server
make build

测试

使用 Docker 运行测试

docker-compose run --rm mcp-prometheus-server-test

手动运行测试

# Unit tests only
cabal test

# With integration tests (requires Prometheus)
export PROMETHEUS_URL=http://your-prometheus-server:9090
cabal test

配置

环境变量

• PROMETHEUS_URL - Prometheus 服务的 URL（默认值：http://your-prometheus-server:9090）

命令行选项

mcp-prometheus-server --prometheus-url http://prometheus:9090

开发

项目结构

mcp-prometheus-server/
├── app/            # Main executable
├── src/            # Library source code
│   ├── MCP/        # MCP protocol implementation
│   └── Prometheus/ # Prometheus client
├── test/           # Test suites
├── Dockerfile      # Docker image definition
└── docker-compose.yml # Development environment

添加新端点

1. 在 src/Prometheus/Client.hs 中添加客户端函数
2. 在 src/MCP/Server.hs 中添加工具定义
3. 在 test/IntegrationSpec.hs 中添加测试
4. 更新文档

故障排除

Docker 问题

容器立即退出：MCP 服务需要通过 stdio 进行交互。使用 -it 标志：

docker run -it --rm mcp-prometheus-server:latest

无法连接到 Prometheus：确保容器位于同一网络：

docker network create mcp-net
docker run --network mcp-net ...

构建问题

Cabal 依赖项错误：更新软件包索引：

cabal update

GHC 版本不匹配：使用 GHCup 安装正确的版本：

ghcup install ghc 9.6.4
ghcup set ghc 9.6.4

贡献

欢迎贡献！请参阅 ROADMAP.md 了解计划中的功能。

1. Fork 此仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交 pull request

许可证

BSD 3-Clause License — 详情请参阅 LICENSE 文件。

致谢

• 特别感谢 Adeon 在 Haskell 最佳实践、异常处理模式以及避免常见惰性求值陷阱方面提供的宝贵指导
• 使用 Model Context Protocol 构建
• 由 Prometheus 提供支持
• 使用 Haskell 编写

“The Adeon Special” - v1.0.1

此版本代表了可用于生产环境的 Haskell 代码，可避免常见陷阱：

• ✅ 无 SomeException 反模式
• ✅ 在 I/O 密集型函数中进行严格求值
• ✅ 线程安全的日志记录模式
• ✅ 正确处理 JSON-RPC 通知
• ✅ 全面的错误恢复机制，不会导致崩溃