### 项目简介 VictoriaTraces MCP 服务器是基于 Model Context Protocol (MCP) 实现的后端应用，旨在将您的 VictoriaTraces 实例无缝集成到各种支持 MCP 的 LLM 客户端中。它通过标准化的方式，允许 LLM 客户端访问 VictoriaTraces 的 API 接口，查询追踪数据、服务信息以及进行文档搜索，从而增强 LLM 在可观测性、调试和自动化任务中的能力。 ### 主要功能点 * **追踪数据查询:** 允许 LLM 查询、探索和分析 VictoriaTraces 中的追踪数据。 * **服务及操作列表:** 获取 VictoriaTraces 中所有被追踪的服务及其 Span 名称（操作）。 * **服务依赖图:** 查询服务之间的依赖关系图。 * **离线文档搜索:** 内嵌 VictoriaTraces 的最新文档，支持 LLM 客户端无需在线访问即可搜索文档。 * **LLM 工具集成:** 将 VictoriaTraces 的读写 API 封装成可供 LLM 调用的“工具”，实现 LLM 与追踪系统的深度交互。 * **可定制的 Prompt 模板:** 支持定义和渲染 Prompt 模板，以适应不同的 LLM 交互模式。 ### 安装步骤您可以选择通过 Go 工具、下载预编译二进制文件、使用 Docker 或从源代码构建来安装 VictoriaTraces MCP 服务器。 * **通过 Go 安装:** 如果您已安装 Go 1.25 或更高版本，可运行以下命令： ```bash go install github.com/VictoriaMetrics-Community/mcp-victoriatraces/cmd/mcp-victoriatraces@latest ``` * **下载二进制文件:** 直接从 [GitHub Releases 页面](https://github.com/VictoriaMetrics-Community/mcp-victoriatraces/releases) 下载最新版本的预编译二进制包，解压后将其可执行文件（例如 `mcp-victoriatraces_Linux_x86_64`）添加到您的系统 PATH 中。 * **使用 Docker 运行:** 推荐使用 Docker 快速部署，无需安装 Go 环境。 ```bash docker run -d --name mcp-victoriatraces \ -e VT_INSTANCE_ENTRYPOINT=https://localhost:10428 \ -e MCP_SERVER_MODE=http \ -e MCP_LISTEN_ADDR=:8081 \ -p 8081:8081 \ ghcr.io/victoriametrics-community/mcp-victoriatraces ``` 请将 `VT_INSTANCE_ENTRYPOINT` 替换为您的 VictoriaTraces 实例地址。 * **从源代码构建:** 克隆仓库后，进入项目目录执行 `make build`。 ### 服务器配置 MCP 客户端需要配置 MCP 服务器的启动命令及其环境变量才能建立连接。以下是常见 MCP 客户端的配置示例。您需要将 `` 替换为您的 VictoriaTraces 实例 URL，并可选提供 `` 和自定义 HTTP 头部。 * **对于 Cursor, Claude Desktop, JetBrains IDEs, Windsurf 客户端:** 在您的客户端 MCP 配置文件中添加如下 JSON 片段： ```json { "mcpServers": { "victoriatraces": { "command": "/path/to/mcp-victoriatraces", "env": { "VT_INSTANCE_ENTRYPOINT": "<您的VictoriaTraces实例URL，例如 https://localhost:10428>", "VT_INSTANCE_BEARER_TOKEN": "<可选：您的VictoriaTraces API认证Bearer Token>", "VT_INSTANCE_HEADERS": "<可选：自定义HTTP头部，例如 \"X-Auth-Key=your_key,X-Request-ID=123\"，键值对用逗号分隔>" } } } } ``` * **对于 Claude Code 客户端 (命令行):** 运行以下命令： ```sh claude mcp add victoriatraces -- /path/to/mcp-victoriatraces \ -e VT_INSTANCE_ENTRYPOINT=<您的VictoriaTraces实例URL> \ -e VT_INSTANCE_BEARER_TOKEN=<可选：您的VictoriaTraces API认证Bearer Token> \ -e VT_INSTANCE_HEADERS="<可选：自定义HTTP头部，键值对用逗号分隔>" ``` * **对于 Visual Studio Code 客户端:** 在您的 VS Code MCP 配置文件中添加如下 JSON 片段： ```json { "servers": { "victoriatraces": { "type": "stdio", "command": "/path/to/mcp-victoriatraces", "env": { "VT_INSTANCE_ENTRYPOINT": "<您的VictoriaTraces实例URL>", "VT_INSTANCE_BEARER_TOKEN": "<可选：您的VictoriaTraces API认证Bearer Token>", "VT_INSTANCE_HEADERS": "<可选：自定义HTTP头部，键值对用逗号分隔>" } } } } ``` * **对于 Zed 客户端:** 在您的 Zed 配置文件中添加如下 JSON 片段： ```json "context_servers": { "victoriatraces": { "command": { "path": "/path/to/mcp-victoriatraces", "args": [], "env": { "VT_INSTANCE_ENTRYPOINT": "<您的VictoriaTraces实例URL>", "VT_INSTANCE_BEARER_TOKEN": "<可选：您的VictoriaTraces API认证Bearer Token>", "VT_INSTANCE_HEADERS": "<可选：自定义HTTP头部，键值对用逗号分隔>" } }, "settings": {} } } ``` * **使用 Docker 代替本地二进制的配置方式 (适用于所有客户端):** 您可以将 `command` 设置为 `docker`，并在 `args` 中传入 `docker run` 命令所需的参数，如下所示： ```json { "mcpServers": { "victoriatraces": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "VT_INSTANCE_ENTRYPOINT=<您的VictoriaTraces实例URL>", "-e", "VT_INSTANCE_BEARER_TOKEN=<可选：您的VictoriaTraces API认证Bearer Token>", "-e", "VT_INSTANCE_HEADERS=<可选：自定义HTTP头部，键值对用逗号分隔>", "ghcr.io/victoriametrics-community/mcp-victoriatraces" ], "env": {} } } } ``` ### 基本使用方法配置完成后，您可以在支持 MCP 的 LLM 客户端中直接与 VictoriaTraces MCP 服务器交互。您可以通过以下方式启动对话，让 AI 助手知道要使用 VictoriaTraces： ``` Use MCP VictoriaTraces in the following answers ``` 或者，AI 助手也可能根据您的问题自动识别并调用 VictoriaTraces 的功能。您可以直接向 AI 提问，例如： * “列出所有追踪到的服务。” (对应 `services` 工具) * “查询服务 'my-app' 的所有操作名称。” (对应 `service_names` 工具) * “查找所有包含错误的服务追踪。” (对应 `traces` 工具) * “根据追踪 ID 'abc-123' 获取详细追踪信息。” (对应 `trace` 工具) * “搜索 VictoriaTraces 文档中关于 'span attributes' 的内容。” (对应 `documentation` 工具)

"追踪系统集成" 标签

VictoriaTraces MCP 服务器