nats-trail

让 AI Agent 安全地访问你的生产事件总线。
_{通过一个范围受限的查询引擎，提供 Web UI、命令行工具和 MCP 服务，让人类与 Agent 基于同一真实数据源调试 NATS。}

为何构建

每个 NATS GUI 都能回答 “这个流里有什么？” 这只是简单的问题。

事件驱动系统中，难题是**“这一次流程为何失败？”**——要回答这个问题， 就得跨越四个流、三个服务和一个死信主题追踪同一个 request_id。 如今，你只能为每个流打开一个终端，手动完成这件事。

NATS Trail 直接回答这个问题，并将答案作为类型明确、范围受限、 只读的工具契约提供给 Agent——这样你就能让 Claude 查看生产环境并提出问题。

nats-trail trace --request-id req-0001d --limit 20

或者，你可以向 Agent 提问：“s3-events 的刷新为何失败？”——它会定位到 真正导致故障的消息，并已提取出重试状态和关联 ID：

别人都没做到的部分

市面上有好几个 NATS MCP 服务。它们通过 nats CLI 执行命令，返回原始数据转储， 还提供 publish 和 delete 操作，却自称只读。

NATS Trail 将 Agent 接口视为一份契约，而非包装层：

这里的“只读”意味着无法访问，而非已禁用

NATS Trail 可以写入：发布、清除、删除消息、消费者和流。这些功能位于 /api/mutate 后面，可从 UI 和 CLI 访问。

executeMcpTool() 接收的 McpRuntimeData 接口只公开读取函数。这里并不存在由功能标志控制的已禁用 publish——根本没有可调用的 publish。 环境变量配置错误也无法清除生产环境中的流，因为代码路径并不存在。CLI 写入命令在 --agent 模式下也会拒绝运行，而且测试套件会读取源码，确保这些限制不会被悄悄取消。

这也是将 prod 上下文交给 Agent 的唯一合理依据。

安装

npx nats-trail serve

打开 **http://127.0.0.1:4000**——一个进程即可同时提供 UI 和 API。

更喜欢容器？compose 文件会在启用了 JetStream 的服务旁启动 NATS Trail：

docker compose up

在 Kubernetes 上，Helm chart 会在 values.yaml 中声明上下文和关联键，并将凭据保存在 Secret 中：

helm install nats-trail ./charts/nats-trail -f my-values.yaml

请参阅 charts/nats-trail/README.md，了解声明式配置、为何使用单副本 StatefulSet，以及如何将身份验证委托给服务前端的组件。

git clone https://github.com/solsolettidev/nats-trail
cd nats-trail
npm install
npm start

npm run dev

要求： Node.js >= 22（用于关联索引内置的 SQLite），以及可访问的 NATS 服务（nats-server -js 即可）。

将其用作 MCP 服务

让任意 MCP 客户端连接到 stdio 服务。Claude Code 的配置方式：

claude mcp add nats-trail -- npx -y @nats-trail/mcp

或者手动接入：

{
  "mcpServers": {
    "nats-trail": {
      "command": "natstrail-mcp",
      "env": {
        "NATS_TRAIL_API": "http://127.0.0.1:4000",
        "NATS_TRAIL_TOKEN": "<bearer token>"
      }
    }
  }
}

提供 25 个只读工具，所有工具都返回相同的封装格式：

# start here when the topology is unknown
natstrail.discover_subjects        subjects that carry traffic + inferred payload shapes
natstrail.get_health_summary       what is broken right now, ranked
natstrail.reconstruct_flow         the causal chain for one request_id
natstrail.enrich_incident          flat context for an incident: flow + dead letters + health

# messages
natstrail.search_messages          natstrail.get_message_detail
natstrail.trace_by_request_id      natstrail.trace_by_correlation_id
natstrail.search_dlq               natstrail.run_filter

# topology
natstrail.list_streams             natstrail.get_stream_info
natstrail.list_consumers           natstrail.list_kv_buckets
natstrail.list_kv_keys             natstrail.get_kv_history
natstrail.list_object_buckets      natstrail.list_objects

# operations
natstrail.get_server_health        natstrail.list_server_connections
natstrail.list_contexts            natstrail.get_connection_status
natstrail.list_filters             natstrail.list_audit
natstrail.enrich_sentry

请参阅 docs/mcp-agent.md。

三种界面，一个引擎

                 ┌──  Web UI          explore visually, save filters
Query Engine  ───┼──  CLI             scripts, pipelines, humans in a terminal
  (core)         └──  MCP + HTTP API  agents, Sentry, dashboards

你在 UI 中保存的筛选器，与 nats-trail filter run 执行的筛选器相同，也与 natstrail.run_filter 提供给 Agent 的筛选器相同。只需配置一次上下文，即可随处使用。

• packages/ui — React + Vite。仅负责呈现。
• packages/server — Express + WebSocket 桥接服务。负责管理连接和凭据。
• packages/core — 查询引擎：封装格式、限制、截断、筛选器、错误规范化。
• packages/cli — nats-trail 二进制程序：查询命令、serve 和交互式 Shell。
• packages/mcp — 工具契约和 stdio 服务。

请参阅 docs/architecture.md。

功能

检查 — 上下文选择器（本地 / 开发 / 预发布 / 生产），带有生产环境确认门槛；实时主题订阅；支持树状视图和载荷内搜索的 JSON 美化显示；流和消费者浏览；自动检测的 DLQ 面板。

JetStream — 流、主题、数量和消费者健康状况。	NATS Core — 带筛选条件的实时主题订阅。
DLQ — 自动检测死信，并显示原因和来源。	查看器 — 树状视图、原始内容、搜索、全屏、复制路径。

理解 — 主题发现会根据真实流量推断载荷结构；流重建会将一个 request_id 转化为因果链；健康摘要会按实际故障情况排序。

查询 — 通过游标和时间窗口进行有界流扫描；按主题、日期、文本和 JSON 事件类型筛选；在所有三个界面中共享已保存的筛选条件。二进制载荷（protobuf、msgpack）会被检测出来，并以十六进制转储显示，而不是乱码。

浏览 — KV 存储桶及其每个键的修订历史（包括删除记录）、Object Store 元数据，以及来自监控端口（varz / jsz / connz）的服务健康状况。

更改 — 通过 UI 和 CLI 发布消息、请求/回复、清空和删除消息、消费者及流，并要求确认。Agent 界面绝不提供这些操作。

集成 — /api/integration 下的只读 HTTP API、带有每个令牌审计身份的 bearer 令牌，以及用于在不暴露凭据的情况下将 NATS 上下文附加到错误的 POST /api/integration/enrich/sentry。

完整列表见 docs/features.md · CLI 参考见 docs/cli.md。

安全

凭据保存在本地 data/ 下的上下文中（已加入 git 忽略）。UI 不会直接持有 NATS 连接 — 始终通过桥接服务进行连接，该服务会为每个上下文建立一个连接池。

服务器默认绑定到 127.0.0.1，因为 /api/contexts 和 /api/connect 是未经身份验证的本地端点。若要开放 Integration API 和 WebSocket，请通过 NATS_TRAIL_TOKENS=name:token 或 data/tokens.json 配置 bearer 令牌；之后，审计条目会记录每次调用所使用的已验证令牌名称。

共享部署有意不内置登录功能：身份验证由服务前端负责（例如带 OIDC 的 ingress、oauth2-proxy、Cloudflare Access、Teleport 或网络隔离），因此此处不会存储密码。通过 NATS_TRAIL_CONFIG 声明的上下文会从环境中解析 ${VAR}，且无法通过 API 编辑或删除。

路线图

记录在 docs/roadmap.md 中。

阶段 0–3 已完成。 npm 发布 · KV 和对象存储浏览 · 服务健康状态 · 二进制 负载处理 · nkey 身份验证 · subject 发现 · 流重建 · 健康摘要 · Sentry、Grafana、Datadog 和 PagerDuty 的事件 增强 · stream、consumer 和 KV 管理 · MCP 注册表列表 · 索引关联搜索 · 声明式配置和 Helm chart。所有写入操作 仅供人工执行，须使用受限令牌，并会连同操作参数一起审计。

**下一步：**集群感知功能，特意延后，而非待办工作。

明确不在计划内 — protobuf 和 msgpack 字段解码（需要按 subject 配置架构注册表）， 以及在 GUI 功能广度上与 NUI 竞争。请参阅 docs/roadmap.md。

计划中，尚未开始：对于明确希望允许 Agent 写入的团队，提供一个独立的可选二进制文件 （natstrail-mcp-write），需要用户主动安装。绝不会在只读服务中添加切换标志： 只有当上述保障不会因意外操作而被关闭时，它才有意义。

参与贡献

欢迎提交问题和 PR。有关构建布局，请参阅 docs/development.md。

许可证

Apache-2.0 © Sol Soletti