AI导哈

自然语言查询服务器

一个智能的模型-上下文-协议（MCP）服务器，作为SigNoz可观测性平台API的自然语言客户端，将人类语言查询转换为有效的SigNoz API查询。

  • by Champion2049
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 champion2049/mcp_server_signoz

使用说明

SigNoz MCP服务器

作为SigNoz Observability Platform API的自然语言客户端的智能模型内容协议（MCP）服务器。该服务器将有关日志和跟踪的类似人类的问题转换为有效的SigNoz API查询，从而更容易与您的可观察性数据交互。

特性

  • 自然语言查询：用简单的英语询问日志、跟踪和指标。
  • 日志和跟踪分析:
    • 使用关键字和属性过滤搜索原始日志和跟踪跨度。
    • 对日志和跟踪执行强大的聚合（计数、求和、平均值、百分位数）。
  • 上下文感知会话：设置默认服务名称和时间范围，以简化后续查询。
  • 服务发现：自动列出向SigNoz发送数据的所有可用服务。
  • 可扩展工具集：采用模块化工具架构构建，易于添加新功能。
  • TypeScript和Zod：强类型，代码健壮且可维护。

入门指南

按照以下说明在本地计算机上启动并运行服务器。

先决条件

  • Node.js（建议使用v18或更高版本）
  • npm（通常随Node.js一起提供）
  • 正在运行的SigNoz实例（云或自托管）

安装

  1. 克隆存储库：
    git clone https://github.com/Champion2049/MCP_Server_SigNoz.git
cd <repository-directory>
  2. 安装依赖项：
    npm install

配置

服务器需要API凭据才能连接到SigNoz实例。

  1. 创建一个 .env 项目根目录中的文件。

  2. 将以下环境变量添加到 .env 文件：

    # The base URL of your SigNoz API endpoint
# For SigNoz Cloud, find this in Settings -> Ingestion Settings
# Example: [https://us.signoz.cloud](https://us.signoz.cloud)
SIGNOZ_API_BASE_URL="<YOUR_SIGNOZ_BASE_URL>"

# Your SigNoz API Key
# Generate this from Settings -> API Keys in your SigNoz instance
# API keys can only be created/managed by users with the Admin role. If you don't have the Admin role, contact your organization's admin to create an API key for you.
SIGNOZ_API_KEY="<YOUR_SIGNOZ_API_KEY>"

    将占位符值替换为实际的SigNoz URL和API密钥。

用法

配置后，您可以构建和运行服务器。

  1. 构建TypeScript源代码：
    npm run build
  2. 运行服务器：
    node <BUILD_PATH_DIR>
    您应该看到一条消息，指示服务器正在运行：
    SigNoz MCP Server is running and connected via stdio.

MCP客户端配置

要将此服务器连接到MCP客户端（如聊天机器人或其他应用程序），您需要配置客户端以启动服务器。为MCP客户端创建一个配置文件，以下是一个示例配置：

{
  "mcpServers": {
    "SigNoz": {
      "command": "node",
      "args": ["/path/to/your/project/build/index.js"]
    }
  }
}

备注：确保 command 和 args 指向编译的正确位置 index.js 文件。

示例提示

以下是您可以向服务器询问的一些示例。

  • 为您的会话设置上下文：

    • "Set the default service to 'frontend' and the time range to the last 90 minutes."

  • 搜索特定日志：

    • "Show me the latest logs from the 'api-gateway' service that contain the word 'error'."
    • "Find logs for the 'payment-service' in the last 30 minutes."

  • 聚合日志数据：

    • "Count the number of logs per service over the last hour."
    • "Show me a graph of error logs per minute for the 'frontend' service."

  • 查找并分析痕迹：

    • "Find traces for the 'checkout-service' that have an error."
    • "Show me the slowest traces from the 'user-service' in the last day."

  • 计算性能指标：

    • "What is the P99 latency for the 'api-gateway' service?" （这将使用 aggregate-traces 随着 durationNano)
    • "Calculate the average duration of traces for the 'data-processor' service grouped by operation name."

  • 发现服务：

    • "List all available services."

工具概述

服务器公开了几个与SigNoz API交互的工具。

工具名称 描述 参数
search-logs 根据过滤器获取原始日志条目的列表。 query, serviceName, startTimeUnix, endTimeUnix, pageSize, limit
aggregate-logs 根据日志数据计算聚合指标（例如计数、平均值）。非常适合创建图表和表格。 aggregationFunction, panelType, groupBy, aggregateField, serviceName, startTimeUnix, endTimeUnix, stepInterval
search-traces 基于过滤器获取原始跟踪跨度列表。 serviceName, hasError, startTimeUnix, endTimeUnix, pageSize, limit
aggregate-traces 根据跟踪数据计算聚合指标（例如P99延迟）。 aggregationFunction, groupBy, aggregateField, serviceName, hasError, startTimeUnix, endTimeUnix
list-services 获取已发送数据的所有唯一服务名称的列表。 无

项目结构

代码库被组织成逻辑模块，以促进关注点的分离和可维护性。

src/
├── tools/                # Contains individual tool definitions
│   ├── aggregate-logs.ts
│   ├── aggregate-traces.ts
│   ├── list-services.ts
│   ├── search-logs.ts
│   ├── search-traces.ts
├── constants.ts          # Global constants (e.g., User-Agent)
├── index.ts              # Main application entry point (loads .env, starts server)
├── server.ts             # MCP server setup and tool registration
├── signoz-api.ts         # Helper functions for querying the SigNoz API
└── types.ts              # Core TypeScript interfaces and types

相关 MCP