Mackerel MCP服务器
使用说明（Markdown 格式）
-
项目简介
- 该仓库实现了一个基于 Model Context Protocol (MCP) 的后端服务器，用于向 MCP 客户端提供资源管理、工具执行和提示模板渲染等能力，便于将外部数据源（如 Mackerel API）接入到 LLM 的对话和推理过程中。
-
主要功能点
- 资源(Resource)托管与访问能力：通过 Mackerel API 获取和展示可用数据。
- 工具(Tools)注册与执行：将各种对外 API 封装为可在 MCP 客户端调用的工具，例如 list_alerts、get_dashboard、list_hosts、get_host_metrics、list_traces、get_trace 等，支持输入校验、错误处理与分页等。
- Prompts/模板：提供可渲染的提示模板结构与描述，帮助构建与展示符合上下文需求的交互策略。
- JSON-RPC 通信：服务器端按 MCP 约定处理请求并返回统一的 JSON-RPC 响应格式。
- 会话与能力声明：服务器端维护工具注册、能力描述，便于客户端动态发现可用功能。
- 多传输协议：默认通过标准输入输出传输（用于容器/CLI 场景），并可扩展支持 SSE、WebSocket 等。
- 安全与易用性：通过对外部 API 调用的统一封装、错误信息模板化输出，以及对响应大小的令牌化限制等实现稳健性。
-
安装与运行步骤
- Docker 运行（推荐方式之一）：
- 使用 ghcr.io 容器镜像，设置环境变量 MACKEREL_APIKEY，运行容器后服务器就可通过 MCP 客户端连接。
- 使用 npx 启动（另一种方式）：
- 通过 npx 直接启动内置的 MCP 服务器实现，需提供 MACKEREL_APIKEY。
- Docker 运行（推荐方式之一）：
-
服务器配置（供 MCP 客户端使用的连接信息示例） 说明：以下是为 MCP 客户端配置 MCP 服务器时需要的 JSON 配置要点。服务器名称、启动命令和参数需根据实际运行方式填写。示例仅做格式与字段说明，不代表代码实现。
{ "serverName": "mackerel", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MACKEREL_APIKEY", "ghcr.io/mackerelio-labs/mcp-server:latest" ], "env": { "MACKEREL_APIKEY": "<YOUR_MACKEREL_APIKEY>" } }
配置说明：
- serverName：服务器在 MCP 客户端中的标识名称，建议与实际部署保持一致。
- command 和 args：指定启动 MCP 服务器所需的执行命令及参数（如通过 Docker 启动时的参数）。
- env：环境变量，示例中包含 MACKEREL_APIKEY，需替换为实际的授权密钥。
- 客户端不需要这段配置信息的实现细节代码，只需读取并传递给启动逻辑以建立连接。
-
基本使用方法
- 准备工作
- 确保已获取 MACKEREL_APIKEY，并在环境变量中正确设置（在 Docker 启动时通过 -e 传入，或在本地执行时设置）。
- 选择启动方式：Docker 容器方式或 npm/npx 直接启动。
- 启动 MCP 服务器
- 使用 Docker 启动镜像并传入 APIKey，即可启动 MCP 服务器并监听 MCP 客户端连接。
- 使用 npx 启动时，确保环境变量 MACKEREL_APIKEY 已设置，客户端即可通过 MCP 协议连接。
- 使用 MCP 客户端连接
- MCP 客户端需要指定服务器名称、以及通过配置给定的 command 和 args 来启动/连接服务器。服务器端实现支持按 MCP 规定的 JSON-RPC 请求格式处理请求，返回相应的 JSON-RPC 响应。
- 常用操作
- 调用如 list_alerts、get_dashboard、list_hosts、get_host_metrics、list_traces、get_trace 等工具，浏览或获取数据，并通过输出结构化的文本内容与错误信息帮助 LLM 进行后续对话和推理。
- 维护与扩展
- 新增工具时，按现有工具的注册方式将工具实现类与输入输出 Schema 进行绑定，服务端即可对外暴露新的工具能力。
- 准备工作