内容
# Signoz MCP Server
一个使用 Go 实现的模型上下文协议（Model Context Protocol，MCP）服务器，提供与 [SigNoz](https://signoz.io/) 的无缝集成，SigNoz 是一个开源的可观察性平台。该服务器使 AI 助手和其他 MCP 客户端能够与 SigNoz API 交互，以查询仪表板、指标、追踪、日志等。
## 特性
Signoz MCP Server 提供以下工具：
- **`signoz_test_connection`**: 验证与您的 Signoz 实例和配置的连接性
- **`signoz_fetch_dashboards`**: 列出所有可用的仪表板
- **`signoz_fetch_dashboard_details`**: 通过 ID 检索特定仪表板的详细信息
- **`signoz_fetch_dashboard_data`**: 根据名称和时间范围获取给定仪表板的所有面板数据
- **`signoz_fetch_apm_metrics`**: 检索给定服务和时间范围的标准 APM 指标（请求率、错误率、延迟、apdex）
- **`signoz_fetch_services`**: 从 Signoz 获取所有被监控的服务，并可选择时间范围过滤
- **`signoz_execute_clickhouse_query`**: 通过 Signoz API 执行自定义 ClickHouse SQL 查询，支持时间范围
- **`signoz_execute_builder_query`**: 执行 Signoz 构建器查询以获取自定义指标和聚合，支持时间范围
- **`signoz_fetch_traces_or_logs`**: 使用 ClickHouse SQL 从 SigNoz 获取追踪或日志
## 架构
该项目遵循清晰架构原则，具有以下结构：
```
├── cmd/server/ # 应用程序入口点
├── internal/
│ ├── domain/ # 领域模型和接口
│ ├── application/service/ # 应用服务
│ └── infrastructure/ # 外部集成
│ ├── config/ # 配置管理
│ └── signoz/ # Signoz API 客户端
├── pkg/mcp/ # MCP 协议实现
│ ├── transport/ # 传输层（STDIO）
│ └── server/ # MCP 服务器实现
└── configs/ # 配置文件
```
## 先决条件
- Go 1.22 或更高版本
- 访问 SigNoz 实例
- SigNoz API 密钥（如果需要身份验证）
## 安装
### 选项 1：从源代码构建
1. 克隆代码库：
```bash
git clone https://github.com/CalmoAI/mcp-server-signoz.git
cd signoz-mcp-server
```
2. 安装并更新依赖：
```bash
go mod tidy
```
3. 构建服务器：
```bash
go build -o signoz-mcp-server ./cmd/server
```
4. （可选）获取配置的绝对路径：
```bash
pwd
# 这将显示您的二进制文件的完整路径：/path/to/signoz-mcp-server
```
5. 验证安装：
```bash
# 测试二进制文件是否运行（它将启动 MCP 服务器）
./signoz-mcp-server
# 按 Ctrl+C 停止服务器
```
### 选项 2：使用 Go 安装
```bash
go install github.com/CalmoAI/mcp-server-signoz/cmd/server@latest
```
## 配置
服务器可以使用环境变量、配置文件或命令行标志进行配置。
### 环境变量
**任何配置值**都可以使用 `SIGNOZ_MCP_` 前缀的环境变量进行覆盖。这为部署和运行时配置提供了完全的灵活性。
#### 环境变量模式
```
SIGNOZ_MCP_<SECTION>_<KEY>
```
#### 示例
```bash
# 核心 SigNoz 配置
export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key"
# 日志配置
export SIGNOZ_MCP_LOG_LEVEL="debug"
export SIGNOZ_MCP_LOG_FORMAT="text"
# 服务器配置
export SIGNOZ_MCP_SERVER_TIMEOUT="60s"
export SIGNOZ_MCP_SERVER_DEBUG="true"
# 遥测配置
export SIGNOZ_MCP_TELEMETRY_ENABLED="false"
```
#### 完整的环境变量参考
**服务器配置:**
- `SIGNOZ_MCP_SERVER_NAME` - 服务器名称（默认: "signoz-mcp-server"）
- `SIGNOZ_MCP_SERVER_VERSION` - 服务器版本（默认: "1.0.0"）
- `SIGNOZ_MCP_SERVER_ENVIRONMENT` - 环境（默认: "development"）
- `SIGNOZ_MCP_SERVER_DEBUG` - 启用调试模式（默认: false）
- `SIGNOZ_MCP_SERVER_TIMEOUT` - 服务器超时（默认: "30s"）
**SigNoz 配置:**
- `SIGNOZ_MCP_SIGNOZ_URL` - SigNoz 实例 URL（必需）
- `SIGNOZ_MCP_SIGNOZ_API_KEY` - 身份验证的 API 密钥
- `SIGNOZ_MCP_SIGNOZ_TIMEOUT` - 请求超时（默认: "30s"）
- `SIGNOZ_MCP_SIGNOZ_RETRY_ATTEMPTS` - 重试次数（默认: 3）
- `SIGNOZ_MCP_SIGNOZ_RETRY_DELAY` - 初始重试延迟（默认: "1s"）
- `SIGNOZ_MCP_SIGNOZ_MAX_RETRY_DELAY` - 最大重试延迟（默认: "30s"）
- `SIGNOZ_MCP_SIGNOZ_TLS_ENABLED` - 启用 TLS（默认: true）
- `SIGNOZ_MCP_SIGNOZ_TLS_SKIP_VERIFY` - 跳过 TLS 验证（默认: false）
- `SIGNOZ_MCP_SIGNOZ_MAX_CONNECTIONS` - 最大 HTTP 连接数（默认: 100）
- `SIGNOZ_MCP_SIGNOZ_IDLE_TIMEOUT` - 连接空闲超时（默认: "90s"）
- `SIGNOZ_MCP_SIGNOZ_KEEP_ALIVE` - 保持活动持续时间（默认: "30s"）
**日志配置:**
- `SIGNOZ_MCP_LOG_LEVEL` - 日志级别：debug、info、warn、error、fatal（默认: "info"）
- `SIGNOZ_MCP_LOG_FORMAT` - 日志格式：json、text（默认: "json"）
- `SIGNOZ_MCP_LOG_OUTPUT` - 日志输出：stdout、stderr（默认: "stderr"）
- `SIGNOZ_MCP_LOG_STRUCTURED` - 结构化日志（默认: true）
**遥测配置:**
- `SIGNOZ_MCP_TELEMETRY_ENABLED` - 启用遥测（默认: true）
- `SIGNOZ_MCP_TELEMETRY_SERVICE_NAME` - 服务名称（默认: "signoz-mcp-server"）
- `SIGNOZ_MCP_TELEMETRY_SERVICE_VERSION` - 服务版本（默认: "1.0.0"）
- `SIGNOZ_MCP_TELEMETRY_ENVIRONMENT` - 环境（默认: "development"）
- `SIGNOZ_MCP_TELEMETRY_TRACE_ENDPOINT` - 追踪端点 URL
- `SIGNOZ_MCP_TELEMETRY_METRICS_ENDPOINT` - 指标端点 URL
- `SIGNOZ_MCP_TELEMETRY_SAMPLE_RATE` - 采样率 0-1（默认: 1.0）
- `SIGNOZ_MCP_TELEMETRY_BATCH_TIMEOUT` - 批处理超时（默认: "5s"）
- `SIGNOZ_MCP_TELEMETRY_EXPORT_TIMEOUT` - 导出超时（默认: "30s"）
- `SIGNOZ_MCP_TELEMETRY_MAX_EXPORT_BATCH_SIZE` - 最大批处理大小（默认: 512）
**缓存配置:**
- `SIGNOZ_MCP_CACHE_ENABLED` - 启用缓存（默认: true）
- `SIGNOZ_MCP_CACHE_TTL` - 缓存 TTL（默认: "5m"）
- `SIGNOZ_MCP_CACHE_MAX_ENTRIES` - 最大缓存条目（默认: 1000）
#### 配置优先级
1. **环境变量**（最高优先级）
2. **配置文件**（config.yaml）
3. **默认值**（最低优先级）
### 配置文件
在当前目录、`./configs/` 或 `/etc/signoz-mcp-server/` 创建一个 `config.yaml` 文件：
```yaml
server:
name: "signoz-mcp-server"
version: "1.0.0"
environment: "production"
debug: false
timeout: "30s"
signoz:
url: "https://your-signoz-instance.com"
api_key: "your-api-key"
timeout: "30s"
retry_attempts: 3
retry_delay: "1s"
max_retry_delay: "30s"
tls_enabled: true
tls_skip_verify: false
max_connections: 100
idle_timeout: "90s"
keep_alive: "30s"
log:
level: "info"
format: "json"
output: "stdout"
structured: true
telemetry:
enabled: true
service_name: "signoz-mcp-server"
service_version: "1.0.0"
environment: "production"
sample_rate: 1.0
batch_timeout: "5s"
export_timeout: "30s"
max_export_batch_size: 512
cache:
enabled: true
ttl: "5m"
max_entries: 1000
```
### 必需的配置
唯一必需的配置是 SigNoz URL：
- `SIGNOZ_MCP_SIGNOZ_URL` 或配置文件中的 `signoz.url`
可选但推荐：
- `SIGNOZ_MCP_SIGNOZ_API_KEY` 或 `signoz.api_key` 以进行身份验证访问
## 使用
### 运行服务器
```bash
# 使用环境变量
export SIGNOZ_MCP_SIGNOZ_URL="https://your-signoz-instance.com"
export SIGNOZ_MCP_SIGNOZ_API_KEY="your-api-key"
./signoz-mcp-server
# 使用配置文件
./signoz-mcp-server
```
服务器将启动并通过 STDIO 按照 MCP 协议规范进行通信。
### 与 Claude Desktop 集成
将服务器添加到您的 Claude Desktop 配置中：
```json
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server",
"env": {
"SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
}
}
}
}
```
**注意：** 将 `/absolute/path/to/signoz-mcp-server` 替换为您构建的二进制文件的完整路径。
### 与 Cursor IDE 集成
将服务器添加到您的 Cursor IDE MCP 配置中。创建或更新您的 MCP 配置文件：
**对于 macOS/Linux** (`~/.cursor/mcp_servers.json`):
```json
{
"mcpServers": {
"signoz": {
"command": "/absolute/path/to/signoz-mcp-server",
"env": {
"SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
}
}
}
}
```
**对于 Windows** (`%APPDATA%\Cursor\mcp_servers.json`):
```json
{
"mcpServers": {
"signoz": {
"command": "C:\\absolute\\path\\to\\signoz-mcp-server.exe",
"env": {
"SIGNOZ_MCP_SIGNOZ_URL": "https://your-signoz-instance.com",
"SIGNOZ_MCP_SIGNOZ_API_KEY": "your-api-key"
}
}
}
}
```
**配置说明：**
- 将 `/absolute/path/to/signoz-mcp-server` 替换为您构建的二进制文件的完整路径
- 如果您的 SigNoz 实例不需要身份验证，则 `SIGNOZ_MCP_SIGNOZ_API_KEY` 是可选的
- 确保二进制文件具有执行权限（在 Unix 系统上使用 `chmod +x signoz-mcp-server`）
**使用集成：**
1. 更新配置后重启 Cursor IDE
2. SigNoz 工具将自动在 Cursor 的 AI 助手中可用
3. 您可以直接要求 Cursor 使用 SigNoz 命令，例如：
- "测试我的 SigNoz 连接"
- "显示我所有的 SigNoz 仪表板"
- "获取我的服务的 APM 指标"
- "在 SigNoz 上执行此 ClickHouse 查询"
### 与其他 MCP 客户端集成
该服务器实现了标准的 MCP 协议，可以与任何兼容的 MCP 客户端一起使用。请参考您客户端的文档以获取具体的集成说明。
## 工具使用示例
### 测试连接
```
使用 signoz_test_connection 工具验证您的 Signoz 实例是否可访问。
```
### 获取仪表板
```
使用 signoz_fetch_dashboards 获取所有可用仪表板的列表。
```
### 获取仪表板详细信息
```
使用 signoz_fetch_dashboard_details 和 dashboard_id: "your-dashboard-id" 获取特定仪表板的详细信息。
```
### 获取仪表板数据
```
使用 signoz_fetch_dashboard_data 和：
- dashboard_name: "My Dashboard"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"
```
### 获取 APM 指标
```
使用 signoz_fetch_apm_metrics 和：
- service_name: "my-service"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"
```
### 执行 ClickHouse 查询
```
使用 signoz_execute_clickhouse_query 和：
- sql: "SELECT * FROM signoz_traces.signoz_spans WHERE service_name = 'my-service' LIMIT 100"
- start_time: "2023-12-01T00:00:00Z"
- end_time: "2023-12-01T01:00:00Z"
```
## 开发
### 先决条件
- Go 1.22+
- Make（可选，用于使用 Makefile）
### 设置
1. 克隆代码库
2. 安装依赖：`go mod download`
3. 运行测试：`go test ./...`
4. 构建：`go build -o signoz-mcp-server cmd/server/main.go`
### 项目结构
- **领域层** (`internal/domain/`): 核心业务逻辑和接口
- **应用层** (`internal/application/`): 用例和应用服务
- **基础设施层** (`internal/infrastructure/`): 外部依赖和实现
- **表现层** (`pkg/mcp/`): MCP 协议处理
### 测试
运行测试套件：
```bash
# 运行所有测试
go test ./...
# 运行带覆盖率的测试
go test -cover ./...
# 运行带竞争检测的测试
go test -race ./...
```
### 添加新工具
1. 在 `internal/domain/interfaces.go` 中定义工具接口
2. 在 `internal/application/service/mcp_service.go` 中实现业务逻辑
3. 在 `pkg/mcp/server/server.go` 中添加工具定义
4. 在 `executeTool` 方法中添加工具执行逻辑
## 安全考虑
- **API 密钥**: 使用环境变量或安全配置管理安全存储 API 密钥
- **网络安全**: 在生产环境中使用 HTTPS 进行 Signoz 连接
- **输入验证**: 所有用户输入在处理前都经过验证
- **速率限制**: 内置速率限制以防止 API 滥用
- **错误处理**: 错误被记录，但敏感信息不会暴露
## 性能
服务器包括几个性能优化：
- **缓存**: 可配置的缓存以加速访问频繁的数据
- **连接池**: HTTP 连接池以高效调用 Signoz API
- **速率限制**: 防止 API 速率限制
- **重试逻辑**: 对失败请求进行指数退避重试
- **超时**: 可配置超时以防止请求挂起
## 故障排除
### 常见问题
1. **连接失败**
- 验证 Signoz URL 是否正确且可访问
- 检查网络连接
- 确保 API 密钥有效（如果需要）
2. **身份验证错误**
- 验证 API 密钥是否正确
- 检查 Signoz 中 API 密钥的权限
3. **查询失败**
- 验证时间范围是否有效
- 检查仪表板/服务名称是否存在
- 检查 ClickHouse 查询语法
### 日志记录
启用调试日志以进行详细故障排除：
```bash
export SIGNOZ_MCP_LOG_LEVEL="debug"
./signoz-mcp-server
```
### 健康检查
使用 `signoz_test_connection` 工具验证服务器健康和 Signoz 连接性。
## 贡献
1. Fork 代码库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开 Pull Request
### 开发指南
- 遵循 Go 约定和最佳实践
- 为新功能编写测试
- 更新 API 更改的文档
- 使用语义提交消息
- 确保在提交前所有测试通过
## 许可证
本项目根据 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。
## 支持
- **问题**: [GitHub Issues](https://github.com/CalmoAI/mcp-server-signoz/issues)
- **讨论**: [GitHub Discussions](https://github.com/CalmoAI/mcp-server-signoz/discussions)
- **文档**: [项目 Wiki](https://github.com/CalmoAI/mcp-server-signoz/wiki)
## 致谢
- [SigNoz](https://signoz.io/) 提供优秀的可观察性平台
- [Anthropic](https://www.anthropic.com/) 提供模型上下文协议规范
- Go 社区提供优秀的库和工具
- [Calmo](https://getcalmo.com/) 团队的努力使其得以实现
连接信息
猜你喜欢
暂无推荐服务器