内容
# 观测性 MCP 服务器
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/jlowin/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.3+-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** · **[PRD](docs/PRD.md)** · **[更新日志](CHANGELOG.md)** · **[FastMCP 状态](docs/FASTMCP_STATUS.md)**
**FastMCP 3.3+ 控制平面，用于统一的舰队监控（Grafana / Prometheus / Loki on port 12000)**
[](https://github.com/jlowin/fastmcp)
[](https://opentelemetry.io)
[](https://prometheus.io)
[](https://grafana.com)
[](https://grafana.com/oss/loki/)
[](https://github.com/sandraschi/observability-mcp)
MCP + Web UI，用于 `mcp-central-docs/monitoring` 中的**统一**观测性堆栈（托管在 **12000–12006**）。代理获取 Grafana/Loki/Prometheus 工具；人类获取一个 **Charts** 仪表板选择器，在 **:12008** 处，可以用简单的语言解释仪表板。请参阅 [MONITORING_CURRENT_SETUP](https://github.com/sandraschi/mcp-central-docs/blob/main/monitoring/MONITORING_CURRENT_SETUP.md)。
---
## 快速开始
```powershell
git clone https://github.com/sandraschi/observability-mcp
cd observability-mcp
just
```
这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 安装依赖项，然后运行 `just serve` 或 `just dev` 启动。
### 手动设置
如果您没有安装 `just`:
## 功能
### **FastMCP 3.3+ 集成**
- **OpenTelemetry 集成** - 分布式跟踪和指标收集
- **增强存储后端** - 持久化指标和历史数据
- **生产就绪** - 构建用于高性能监控
### **全面监控**
- **实时健康检查** - 监控 MCP 服务器可用性和响应时间
- **性能指标** - CPU、内存、磁盘和网络监控，支持 Prometheus
- **分布式跟踪** - 跟踪 MCP 服务器生态系统之间的交互
- **集中式日志记录** - Loki 驱动的日志聚合和查询
- **智能警报** - 异常检测和自动警报
- **性能报告** - 自动分析和优化建议
### **高级分析**
- **使用模式分析** - 了解 MCP 服务器的使用方式
- **趋势检测** - 确定性能趋势和瓶颈
- **日志关联** - 将指标与 Loki 日志关联，进行根本原因分析
- **优化洞察** - 改进的数据驱动建议
- **多格式导出** - Prometheus、Loki、OpenTelemetry 和 JSON 导出
---
## 安装
### 先决条件
- 安装 [uv](https://docs.astral.sh/uv/)（推荐）
- Python 3.12+
### 快速开始
通过 `uvx` 立即运行：
```bash
uvx observability-mcp
```
### Claude Desktop 集成
将以下内容添加到您的 `claude_desktop_config.json`：
```json
"mcpServers": {
"observability-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/observability-mcp", "run", "observability-mcp"]
}
}
```
## 快速开始
### 1. 启动服务器
```bash
# 使用 CLI
observability-mcp run
# 或直接使用 Python
python -m observability_mcp.server
```
## 安装
### 先决条件
- 安装 [uv](https://docs.astral.sh/uv/)（推荐）
- Python 3.12+
### 快速开始
通过 `uvx` 立即运行：
```bash
uvx observability-mcp
```
### Claude Desktop 集成
将以下内容添加到您的 `claude_desktop_config.json`：
```json
"mcpServers": {
"observability-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/observability-mcp", "run", "observability-mcp"]
}
}
```
### 3. 配置 Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"observability": {
"command": "observability-mcp",
"args": ["run"]
}
}
}
```
---
## 可用工具
### 健康监控
- **`monitor_server_health`** - 实时健康检查，支持 OpenTelemetry 指标
- **`monitor_system_resources`** - 全面的系统资源监控
### 性能分析
- **`collect_performance_metrics`** - CPU、内存、磁盘和网络指标
- **`generate_performance_reports`** - 自动性能分析和建议
- **`analyze_mcp_interactions`** - 使用模式分析和优化洞察
### 日志管理与 Loki 集成
- **`send_logs_to_loki`** - 将自定义日志条目发送到 Loki 进行集中聚合
- **`query_loki_logs`** - 使用高级 LogQL 过滤查询 Loki 日志
- **`analyze_log_patterns`** - 分析日志模式、异常和趋势
- **`correlate_logs_and_metrics`** - 将 Loki 日志与 Prometheus 指标关联
### 警报与异常检测
- **`alert_on_anomalies`** - 智能异常检测和警报
- **`trace_mcp_calls`** - 分布式跟踪，用于 MCP 服务器交互
### 数据导出
- **`export_metrics`** - 以 Prometheus、OpenTelemetry 或 JSON 格式导出指标
---
## 配置
### 环境变量
```bash
# Prometheus 指标服务器端口
PROMETHEUS_PORT=12009
# Loki 配置
LOKI_URL=http://127.0.0.1:12002
LOG_FILE=/tmp/observability-mcp.log
# OpenTelemetry 服务名称
OTEL_SERVICE_NAME=observability-mcp
# OTLP 导出器端点（可选）
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# 指标保留期（天）
METRICS_RETENTION_DAYS=30
```
### 警报配置
服务器附带预配置的常见问题警报：
- **CPU 使用率 > 90%**（警告）
- **内存使用率 > 1GB**（错误）
- **错误率 > 5%**（错误）
警报持久存储，可以通过 MCP 工具自定义。
---
## 监控仪表板
### Prometheus 指标
在以下地址访问指标：`http://127.0.0.1:12009/metrics`
可用指标：
```
# 健康检查
mcp_health_checks_total{status="healthy|degraded|unhealthy", service="..."} 1
# 性能指标
mcp_performance_metrics_collected{service="..."} 1
# 系统资源
mcp_cpu_usage_percent{} 45.2
mcp_memory_usage_mb{} 1024.5
# 跟踪和警报
mcp_traces_created{service="...", operation="..."} 1
mcp_alerts_triggered{type="active|anomaly"} 1
```
### 与 Grafana 和 Loki 集成
**Grafana 仪表板是观测性的最新标准**
1. **在 Grafana 中添加数据源：**
- 使用统一堆栈：Grafana http://127.0.0.1:12000，Prometheus http://127.0.0.1:12001，Loki http://127.0.0.1:12002
2. **导入仪表板：**
- 导入提供的 `mcp-observability.json` 仪表板
- 为您的特定 MCP 生态系统定制面板
3. **日志集成：**
- 使用 Loki 查询日志：`{job="observability-mcp"} |= "ERROR"`
- 将指标与日志关联，进行全面故障排除
**为什么 Grafana + Loki = 最新观测性：**
- **统一视图**：指标、日志和跟踪的单一窗格
- **强大的查询**：PromQL + LogQL 进行复杂分析
- **丰富的可视化**：最新的仪表板，实时更新
- **警报集成**：本地警报，支持多种通知渠道
---
## 架构
### FastMCP 3.3+ 功能利用
#### **OpenTelemetry 集成**
- **分布式跟踪**：跟踪跨多个 MCP 服务器的请求
- **指标收集**：结构化性能数据收集
- **上下文传播**：在服务边界之间保持上下文
#### **增强的持久存储**
- **历史数据**：存储指标和跟踪以进行趋势分析
- **跨会话持久性**：数据在服务器重启后存活
- **高效存储**：针对时序数据优化
#### **生产架构**
```
MCP 服务器 观测性 Prometheus
（监控） MCP 服务器 指标
持久存储 Grafana
（最新） 仪表板
应用程序 Loki
日志 日志聚合
```
---
## 使用示例
### 健康监控
```python
# 检查 MCP 服务器健康状况
result = await monitor_server_health(
service_url="http://localhost:8000/health",
timeout_seconds=5.0
)
print(f"状态：{result['health_check']['status']}")
```
### 性能分析
```python
# 收集系统指标
metrics = await collect_performance_metrics(service_name="my-mcp-server")
print(f"CPU：{metrics['metrics']['cpu_percent']}%")
print(f"内存：{metrics['metrics']['memory_mb']} MB")
```
### 分布式跟踪
```python
# 记录跟踪
trace = await trace_mcp_calls(
operation_name="process_document",
service_name="ocr-mcp",
duration_ms=150.5,
attributes={"file_size": "2.3MB", "format": "PDF"}
)
```
### 生成报告
```python
# 创建性能报告
report = await generate_performance_reports(
service_name="web-mcp",
days=7
)
print("性能摘要：", report['summary'])
print("建议：", report['recommendations'])
```
### Loki 日志管理
```python
# 将自定义日志发送到 Loki
result = await send_logs_to_loki(
log_message="用户身份验证失败",
level="warning",
labels={"service": "auth-service", "user_id": "12345"}
)
# 从 Loki 查询日志
logs = await query_loki_logs(
query='{job="observability-mcp"} |= "ERROR"',
start_time="1h",
limit=100
)
# 分析日志模式
patterns = await analyze_log_patterns(
query='{service="web-mcp"}',
time_window="24h",
min_occurrences=10
)
# 将日志与指标关联
correlation = await correlate_logs_and_metrics(
log_query='{service="api"} |= "timeout"',
metric_query="rate(http_requests_total{status='500'}[5m])",
time_window="1h"
)
```
---
## 开发
### 运行测试
```bash
# 安装开发依赖项
pip install -e ".[dev]"
# 运行测试
pytest
# 运行并生成覆盖率报告
pytest --cov=observability_mcp --cov-report=html
```
### 代码质量
```bash
# 格式化代码
black src/
# 检查代码
ruff check src/
# 类型检查
mypy src/
```
### Docker 开发
```bash
# 构建开发镜像
docker build -t observability-mcp:dev -f Dockerfile.dev .
# 运行并启用热重载
docker run -p 12009:12009 -e PROMETHEUS_PORT=12009 -v $(pwd):/app observability-mcp:dev
```
---
## 性能基准
### FastMCP 3.3+ 优势
- **OpenTelemetry 开销**：<1ms 每条跟踪
- **存储性能**：1000+ 指标/秒
- **内存使用**：50MB 基线 + 10MB 每台监控服务
- **并发监控**：100+ 服务同时监控
### 推荐硬件
- **CPU**：2+ 核心用于指标处理
- **RAM**：2GB 最低，4GB 推荐
- **存储**：10GB 用于指标历史（30 天保留）
---
## 故障排除
### 常见问题
#### 服务器无法启动
```bash
# 检查 Python 版本
python --version # 应为 3.11+
# 检查 FastMCP 安装
pip show fastmcp # 应为 2.14.1+
# 检查依赖项
pip check
```
#### 指标未显示
```bash
# 检查 Prometheus 端点
curl http://127.0.0.1:12009/metrics
# 验证 OpenTelemetry 配置
observability-mcp metrics
```
#### 高内存使用
- 减少 `METRICS_RETENTION_DAYS`
- 实现指标聚合
- 使用 `monitor_system_resources` 监控
#### 存储问题
- 检查可用磁盘空间
- 清理旧指标：`rm -rf ~/.observability-mcp/metrics/*`
- 重启服务器以重新创建存储
---
## 贡献
### 开发设置
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 提交拉取请求
### 代码标准
- **FastMCP 3.3++**：使用最新功能和模式
- **OpenTelemetry**：遵循 OTEL 实践
- **Async First**：所有操作应为异步
- **类型提示**：需要完整类型覆盖
- **文档**：全面的文档字符串
### 测试策略
- **单元测试**：核心功能
- **集成测试**：MCP 服务器交互
- **性能测试**：基准测试和负载测试
- **混沌测试**：故障场景测试
---
## 工业质量堆栈
该项目遵循 **SOTA 14.1** 工业标准，用于高保真代理编排：
- **Python（核心）**：[Ruff](https://astral.sh/ruff) 用于检查和格式化。核心处理程序中禁止 `print` 语句（`T201`）。
- **Webapp（UI）**：[Biome](https://biomejs.dev/) 用于毫秒级检查。严格的 `noConsoleLog` 强制执行。
- **协议合规性**：加固的 `stdout/stderr` 隔离，确保崩溃时JSON-RPC通信的抗崩溃能力。
- **自动化**：[Justfile](./justfile) 用于所有舰队操作（`just lint`、`just fix`、`just dev`）。
- **安全**：使用 `bandit` 和 `safety` 进行自动审计。
## 许可证
MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
## 致谢
- **FastMCP 团队** - 具有 OpenTelemetry 集成的 2.14.1 框架
- **OpenTelemetry 社区** - 观测性标准和工具
- **Prometheus 团队** - 指标收集和警报系统
- **Grafana Labs** - Loki 日志聚合和 Grafana 的最新仪表板
- **Grafana 社区** - 视觉化平台支持现代观测性
- **Loki** - 日志聚合和查询
- **Promtail** - 日志传输代理
---
## 相关项目
- [**FastMCP**](https://github.com/jlowin/fastmcp) - 构建此服务器的框架
- [**OpenTelemetry Python**](https://opentelemetry.io/docs/python/) - 观测性仪表盘
- [**Prometheus**](https://prometheus.io) - 指标收集和警报
- [**Grafana**](https://grafana.com) - 最新仪表板和可视化
- [**Loki**](https://grafana.com/oss/loki/) - 日志聚合和查询
- [**Promtail**](https://grafana.com/docs/loki/latest/clients/promtail/) - 日志传输代理
---
**使用 FastMCP 3.3+、OpenTelemetry、Prometheus、Grafana 和 Loki 构建 - 最新观测性**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器