ezstat-mcp-server

EzStat MCP 服务

一个适用于 EzStat 的独立 Model Context Protocol 服务。让 Claude / Cursor / 任何兼容 MCP 的 Agent 直接推送和读取你的指标——无需复制粘贴，也不用切换仪表板。这正是“由你的 Agent 自行写入和读取指标”这一定位背后的产品：每个能接触你代码的 Agent，也能接触你的可观测性数据。

该服务支持 stdio（本地 Agent 运行器的标准传输方式），并且作为托管端点 https://mcp.ezstat.dev 支持 流式 HTTP，提供相同的七个专用工具。每个工具的描述都面向 Agent 编写，让模型知道何时调用它。

托管端点——零安装

Agent 只需 EzStat API 密钥，即可连接托管的流式 HTTP 端点——无需安装 npm，也无需本地进程：

{
  "mcpServers": {
    "ezstat": {
      "type": "http",
      "url": "https://mcp.ezstat.dev",
      "headers": {
        "Authorization": "Bearer ezkey_your_api_key_here"
      }
    }
  }
}

• 多租户：每个请求都携带你自己的密钥作为 Authorization: Bearer <ezkey>；服务本身不持有任何密钥，每个连接只能访问自己的账户。
• 免费发现：initialize 和 tools/list 无需密钥即可使用，因此客户端和注册表检查工具可在任何配置前查看可用工具。
• 调用工具需要密钥：未提供密钥（或密钥无效）时，调用会返回清晰的 MCP 工具内错误，告知 Agent 应发送什么——绝不会挂起或崩溃。
• 无状态：不会签发或要求会话；每个 POST 请求都独立完整。

此托管端点也符合 MCP 注册表对托管／远程列表的要求（例如 Smithery 的托管服务路径）——请参阅 server.json 中的 remotes 条目。

下方的 stdio 传输方式仍受完整支持；如果你希望在自己的运行器下本地运行服务，它仍是合适的选择。

工具

工具	功能
track_metric	记录应用“产生”的一个指标数据点——计数器（+N，默认为 +1）或仪表（例如 42.5 ms）。
ask_ezstat	用自然语言询问有关指标的问题（供 Agent 读取）。
read_stat	以结构化方式读取统计数据：指定时间窗口内的最新值、序列和摘要（count/min/max/avg/sum）。
list_stats	列出账户的指标（名称、类型和描述）。
create_alert	为某项统计数据创建 webhook 警报（阈值／百分比变化／心跳／持续触发）。
list_alerts	列出账户的警报（id、统计数据、条件、渠道、启用状态、上次触发时间）。
delete_alert	按 id 删除警报。

工具描述针对 Agent 推理进行了优化——请参阅 src/server.ts。

安装（Claude Desktop / Claude Code / Cursor）

单行安装（npm/pnpm）

# pnpm
pnpm add -g ezstat-mcp-server

# npm
npm install -g ezstat-mcp-server

配置 MCP 客户端

Claude Desktop（macOS/Linux 上为 ~/.config/Claude/claude_desktop_config.json， Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ezstat": {
      "command": "ezstat-mcp-server",
      "env": {
        "EZSTAT_API_KEY": "ezkey_your_api_key_here"
      }
    }
  }
}

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "ezstat": {
      "command": "ezstat-mcp-server",
      "env": {
        "EZSTAT_API_KEY": "ezkey_your_api_key_here"
      }
    }
  }
}

在 https://ezstat.dev 获取你的 API 密钥（即“ezkey”）。

Smithery

npx -y @smithery/cli install ezstat-mcp-server --client claude

也可以访问 https://smithery.ai/server/ezstat-mcp-server 并点击 安装。

关于 EzStat

EzStat 是一项极其简单的托管指标服务：发送一个 HTTP POST， 即可获得实时图表。无需 SDK、采集器守护进程、YAML 或仪表板构建器。计数器 和数值／仪表盘统计数据会在首次 POST 时自动创建；图表、分享／嵌入以及 CSV/JSON 导出 均已内置，而 Ask-Your-Data（实时）可用通俗英语回答关于你自己指标的问题，并会在 将每个数字呈现给你之前，先根据检索到的数据进行核实。

按跟踪的统计项数量收取固定月费——$19 / $49 / $149——另有需要绑定银行卡的免费套餐 （不收费；付费前即可实时查看数据）。数据归你所有：随时导出，随时取消。异常检测和指标相关性功能已上线。尚未推出的功能（告警、每周摘要）会在网站上标注为即将推出，而不是提前出售——你现在看到的上线功能都已可用。

从 StatHat 迁移？

如果你的 api.stathat.com 调用已停止、仪表板也变得一片空白：EzStat 支持 StatHat 的传输格式——相同的 /ez、/c、/v 端点，相同的参数，相同的 响应。迁移通常只需改一行：

# before
curl -X POST https://api.stathat.com/ez -d "stat=messages sent" -d "ezkey=KEY" -d "count=1"
# after — change the host, use your EzStat key; stats auto-create
curl -X POST https://api.ezstat.dev/ez -d "stat=messages sent" -d "ezkey=EZSTAT_KEY" -d "count=1"

有一点要特别注意，而且非常重要：检查响应正文，而不是状态码。 由于采用 StatHat 的传输格式，被拒绝的写入（密钥过期、密钥错误、超出配额） 仍会返回 HTTP 200，判定结果则在正文中——{"status":200,"msg":"ok"} 表示 已记录，{"status":"error","msg":"..."} 表示未记录。未经修改的 StatHat 客户端 会将这些情况报告为成功，但你的图表仍会显示旧数据，因此看起来一切正常。新代码应在 /ez 请求中 发送 X-EzStat-Strict: 1，以获取真实的 HTTP 状态码。（此服务已正确处理：无论 HTTP 状态码如何， 只要正文中有 error，就会将其视为失败。）切换后，请使用 ezstat.dev/tools/ezstat-verify.py 确认数据点确实 已到达——相关说明见 ezstat.dev/docs#verify。

大多数 StatHat 客户端库都支持通过一行代码覆盖基础 URL。保存了 StatHat 的 CSV/JSON 导出文件？导入器会重新创建你的统计项并回填历史数据（每个文件上限为 8 MB / 500k 个数据点）。完整指南：docs/stathat-migration.md · ezstat.dev/migrate/stathat——包括迁移优惠：先使用免费套餐实时查看效果， 锁定价格 12 个月，并为前 25 位迁移用户提供专人导入服务。

为什么需要 Agent 原生指标

你的编码 Agent 负责部署、测试和发布——它也应该负责跟踪和读取数据。这正是此服务的用途：让你的 Agent 自行写入和读取指标。 相关原理：docs/agent-native-metrics.md · 与 StatHat/StatFlow/Datadog 的 比较：ezstat.dev/vs。

环境变量

变量	必需	默认值	说明
EZSTAT_API_KEY	是	—	你的 EzStat API 密钥（即“ezkey”）。切勿硬编码，切勿记录到日志中。
EZSTAT_BASE_URL	否	https://api.ezstat.dev	用于覆盖为预发布环境／可自托管服务。
EZSTAT_TIMEOUT_MS	否	10000	每个请求的超时时间，单位为毫秒。
EZSTAT_INGEST_PATH	否	/api/ez	通过代理转发 EZ 端点时用于覆盖路径。
EZSTAT_QUERY_PATH	否	/api/v1/query	Ask-Your-Data 路径。
EZSTAT_STATS_LIST_PATH	否	/api/v1/stats	统计列表路径。

随附基础版 .env.example 文件。

如何与 EzStat 通信

这些工具对应真实的 EzStat API 路由（均使用 EzStat API 密钥进行身份验证）：

工具	方法	路径	身份验证
track_metric	POST	/api/ez	JSON 请求体中的 ezkey
ask_ezstat	POST	/api/v1/query	Authorization: Bearer <ezkey>
read_stat	GET	/api/v1/stats/:name	Authorization: Bearer <ezkey>
list_stats	GET	/api/v1/stats	Authorization: Bearer <ezkey>
create_alert	POST	/api/v1/alerts	Authorization: Bearer <ezkey>
list_alerts	GET	/api/v1/alerts	Authorization: Bearer <ezkey>
delete_alert	DELETE	/api/v1/alerts/:id	Authorization: Bearer <ezkey>

• track_metric 调用兼容 StatHat 的 EZ 数据写入接口（{"ezkey","stat","count"?,"value"?,"t"?}）。 计数器语义：省略 count 和 value，即可记录 count=1（计数器 +1）。
• ask_ezstat 调用 Ask-Your-Data（{"query":"..."} → {answer, data, intent, ...}）。 这是 Agent 的读取路径——使用情况跟踪时，将其计为一次 Agent 读取。
• read_stat 返回统计数据最近的序列和摘要；传入 from/to（Unix 秒数， 在 HTTP 边界转换为 ISO 8601）可限定时间范围。分桶宽度会根据请求的时间跨度自动确定（≤6h → 分钟，≤7d → 小时，>7d → 天）。
• list_stats 返回账户的统计数据；传入 type 可筛选 counter 或 value。

在本地构建和运行

pnpm install
pnpm build       # tsc → dist/
pnpm start       # node dist/index.js  (stdio MCP server)
pnpm test        # vitest run  — fully mocked network, no real HTTP
pnpm dev         # tsx watch src/index.ts

pnpm start 需要设置 EZSTAT_API_KEY；否则服务器会退出并显示明确的错误 （且绝不会记录密钥）。

安全性

• API 密钥仅从 EZSTAT_API_KEY 读取——绝不硬编码，也绝不打印。
• 所有错误消息都会清理：API 密钥绝不会包含在工具结果中。
• HTTP 错误包含稳定、机器可读的 code（unauthorized、rate_limited、 timeout、not_found、server_error 等）以及可安全转发、供人阅读的 message。
• 测试会模拟网络——测试进程不会发出真实 HTTP 请求。

注册表元数据

用于 Smithery / mcp.so / Glama 列表：

• 名称：ezstat-mcp-server
• 显示名称：EzStat
• 描述：让任何 AI Agent 都能通过 EzStat 推送和读取指标。跟踪计数器和值， 然后针对生产环境遥测数据提出自然语言问题。
• 主页：https://ezstat.dev
• 版本：0.8.0
• 传输方式：stdio（本地）+ streamable-http（托管于 https://mcp.ezstat.dev）
• 许可证：MIT
• 代码库：此软件包的源代码

package.json 中的 mcp 块包含相同的元数据，供注册表爬虫抓取。

提交步骤（提交内容及提交位置）

1. Smithery：将代码库推送到 GitHub，然后运行 npx -y @smithery/cli publish（或通过网页 UI 提交）。随软件包提供的 smithery.yaml 会提供安装架构。
2. mcp.so：在 https://mcp.so/submit 提交，并附上上述元数据和 GitHub URL。
3. Glama：在 https://glama.ai/mcp/submit 提交。

此软件包不会自动发布到 npm——请在发布审核后手动发布。

许可证

MIT。