MCP代理跟踪检查员

代理工作流的本地优先、mcp本地可观察性。每一个工具调用，提示 转换、延迟、令牌估计和成本估计记录在本地 SQLite数据库-没有云帐户，没有API密钥，没有痕迹离开您的机器。

专门为MCP构建，而不是固定在通用的LLM代理上。

工具 · 配置 · HTTP传输 · 验证 · 已知的限制 · 贡献

概述

mcp-agent-trace-inspector 是一台MCP服务器。特工们调用它的工具开始追踪， 记录他们走的每一步，并完成跟踪。然后人类检查总结， 比较运行，导出自包含的HTML仪表板，导出OTLP/JSON范围，或者 对遵从性审计日志进行流处理。

Agent / MCP client
      │  trace_start → trace_step → trace_end
      ▼
MCP Agent Trace Inspector
      ├── SQLite (~/.mcp/traces.db)
      ├── JSONL audit log (~/.mcp/trace-inspector-audit.jsonl)
      └── tools: summaries, diffs, HTML, OTLP/JSON, retention, alerts

关键特性

• Tool-call跟踪 -输入、输出、延迟、呼叫者提供或自动 每个步骤的令牌估计。
• 持久本地存储 - SQLite通过Node的内置 node:sqlite;痕迹 在重新启动中存活，并且永远不需要服务。
• 自包含的HTML仪表板 -错误突出显示，步骤时间线，延迟 瀑布式、响应式布局和可扩展的输入/输出JSON。
• 成本估算 ——离线 cl100k_base 标记器加上可配置的定价 表;没有API调用，也没有账单账户数据。
• 跟踪对比 -两次运行之间的累计和逐步差异。
• 推理链提取 -找到推理/思考/计划步骤。
• OTLP / JSON出口 ——标准 resourceSpans → scopeSpans → spans 文档。
• 合规性审计日志 -只追加记录步骤的JSON，可导出为JSON 或CSV与日期过滤。
• 警报 -持久延迟、错误率和成本阈值在 跟踪结束;可选的Slack或通用webhook交付。
• 保留控制 -启动清除或显式归档/删除策略。
• 两个传输 - stdio（默认）和无状态可流HTTP（可选） API-key/JWT认证和速率限制。

技术堆栈

需求

• Node.js 22.13.0或更新版本。 node:sqlite 第一次在Node 22.5.0中可用 后面 --experimental-sqlite;它从22.13.0开始没有标记。这个项目没有 把旗子递过来。
• npm。
• 核心跟踪不需要数据库服务器、API密钥或外部帐户。

快速入门（MCP客户端）

将服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-agent-trace-inspector@latest"]
    }
  }
}

使用特定于项目的数据库：

{
  "mcpServers": {
    "trace-inspector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-agent-trace-inspector@latest",
        "--db=~/traces/my-project.db"
      ]
    }
  }
}

然后让你的代理跟踪自己的工作：

Start a trace named "test-run" with trace_start.
Record a trace_step for each tool you call, including that tool's input and output.
Call trace_end when you are done, then call get_trace_summary for the trace.

摘要包含步数、估计令牌总数、记录的总延迟、 挂钟持续时间，成本估计和推理链检测。跟踪是显式的： 当座席呼叫时，检查员记录步骤 trace_step;它不会拦截 其他MCP服务器自动。

从源

npm ci
npm run build
node dist/index.js --db=~/.mcp/traces.db

开发模式直接运行TypeScript，并在stderr上记录MCP协议消息：

npm run dev -- --db=/tmp/traces.db

可流式HTTP传输

HTTP模式对于本地团队实例或容器非常有用。它是 无状态的： 每个POST都得到一个新的MCP服务器和传输，没有 Mcp-Session-Id，和 端点不提供服务器发起的SSE流。将每个JSON-RPC消息发送为 自己的 POST /mcp 请求。

node dist/index.js --db=~/.mcp/traces.db --http-port=3000 --http-host=127.0.0.1
# stderr: MCP Agent Trace Inspector HTTP server listening on http://127.0.0.1:3000/mcp

初始化端点：

curl -s http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

响应是SSE帧。调用工具：

curl -s http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_traces","arguments":{}}}'

HTTP身份验证

启动服务器前设置一个或两个环境变量：

MCP_API_KEY=change-me \
MCP_JWT_SECRET=change-me-too \
node dist/index.js --http-port=3000 --http-host=127.0.0.1

• 如果 MCP_API_KEY ，则每个HTTP请求都必须发送 X-API-Key: <value>。
• 如果 MCP_JWT_SECRET ，则每个HTTP请求都必须发送 Authorization: Bearer <HS256 JWT>； exp 和 nbf 索赔被检查。
• 如果两者都设置，则两者都是必需的。
• 演播室传输忽略这两个变量。

--http-host=0.0.0.0 允许，但服务器会发出警告。放置TLS和身份验证 反向代理在任何非环回部署前；不公开原始端点 到一个不受信任的网络。

当服务器被绑定到反向代理后面的环回时，代理必须重写 Host 头来 127.0.0.1:<port>． loopback DNS-rebinding保护拒绝其他 Host 值和 403 通过设计。

配置

CLI旗帜

环境变量

服务器会 不 负载 .env 自动文件。中导出变量 shell或在您的MCP客户端中配置它们。

看到 .env.example 用于复制粘贴模板。永远不要真正承诺 机密或数据库文件；两者都被忽略 .gitignore。

工具

服务器公开13个工具。工具注释标记状态更改工具 （readOnlyHint: false)和破坏性滞留(destructiveHint: true）.

跟踪生命周期

trace_step 需要 trace_id， tool_name， input (对象), output (对象)。 token_count 必须是一个非负整数； latency_ms 必须是有限的， 非负数字。调用者提供的令牌计数按原样使用。

检查

出口

export_otel 返回文档；它 不 推给收集器。写 生成一个文件，并使用OTLP工具提交它，或者在您的客户机中调整它。 非uuid跟踪/步骤id被散列成有效的小写32/16个字符的十六进制id。

操作

资源和提示

• 资源 -每个跟踪都暴露为 trace://{trace_id} 使用跟踪元数据， 并将步骤元数据转换为JSON。
• 提示 - - - - - - analyze-trace 接受 trace_id 并返回一个结构化的调查 提示覆盖性能、错误、推理链和优化机会。

代币计数、定价和成本

• 自动计数使用 cl100k_base BPE编码 gpt-tokenizer。
• 有效载荷达到 128年简约 都被精确地标记了。更大的自动载荷使用 标准 ceil(characters / 4) 估计保持同步步长记录有界。 通过 token_count 如果您需要大型有效负载的确切计数，则显式地。
• --no-token-count 完全禁用自动计数。
• 内置的价格表包含克劳德作品/十四行诗/俳句的输入和输出率。 --pricing-table 合并这些条目，以便自定义文件可以添加模型或 在保留默认值的同时覆盖速率。
• get_trace_summary 从总令牌计数中估计成本 输入 率。令牌计数没有分为输入/输出类别，所以这是一个估计， 不是账单数字。
• 默认模型为 claude-sonnet-4-6． 未知型号报告 N/A。

保留语义

有两种相关机制：

1. 启动清洗 （--retention-days=N)删除 started_at 是老 比N天还要多，加上他们的步数这是不可逆的，应用时的过程 就开始了。
2. 政策工具 （set_retention_policy 然后 apply_retention)被保存在内存中 进程的生命周期。它集 archived = 1 在超过N天的痕迹上 删除超过2×N天的存档痕迹及其步骤。政策是 重启时不持久；呼叫 set_retention_policy 再次启动后。 存档的跟踪在删除之前保持可查询。

警报

中的规则被持久化 alert_rules 表，并在 trace_end 运行:

• latency -所有存储走线的平均记录步长延迟（毫秒）。
• error_rate -输出包含。的步骤的百分比 error 或 isError: true。
• cost -总记录代币×默认输入率（$0.003 / 1K代币）。

指标对于数据库是全局的，而不局限于刚刚结束的跟踪。当规则 ，则警报包含在 trace_end 响应(alerts_fired， alerts), 交付给已配置的webhook。Webhook请求在5秒后超时 在没有工具调用失败的情况下记录故障。没有重试和重复数据删除。

通道url是流程配置，而不是数据库行：将它们传递给 configure_alerts，或设置 MCP_SLACK_WEBHOOK / MCP_ALERT_WEBHOOK． 省略URL 稍后 configure_alerts Call保留先前配置的通道。

验证

自动检查（不需要外部服务）：

npm ci
npm run verify          # lint + format check + typecheck + tests
npm test -- --coverage  # unit/integration tests + V8 coverage
npm run build           # compile to dist/
npm run verify:e2e      # build, then run real stdio + HTTP MCP processes
npm run screenshots     # Chrome/CDP capture of the generated dashboard (set CHROME_PATH if needed)

npm run verify:e2e 启动构建的服务器，针对一个临时服务器练习所有13个工具 SQLite数据库，驱动两个连续的HTTP请求来证明无状态传输 工作，检查验证/验证失败，并将机器可读的证据写入 docs/evidence/test-results/． 它不使用模拟传输。

可选MCP Inspector验证：

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

视觉证据

仪表盘是由实物生成的 export_dashboard 工具从一个真实的痕迹和 在Chrome中打开桌面和移动视窗大小。看到 核查报告 对于命令， 测试结果，以及每个截图的工作流关联。

安全

跟踪包含工具输入和输出，可能包括秘密、提示或个人信息 数据。检查器将它们存储在本地，并且不会传输它们，除非您 配置警报webhook。在共享HTML导出之前检查跟踪内容。

• 默认数据库为 ~/.mcp/traces.db;审计日志以mode方式创建 0600。
• HTTP服务器绑定到 127.0.0.1 默认情况下。配置 MCP_API_KEY 和/或 MCP_JWT_SECRET 在绑定非环回地址之前，使用上行TLS。
• HTTP请求主体被限制在10mb以内，并且请求受到速率限制。
• 不要承诺 .env， *.db， *.db-wal，或审计日志。
• 中所述的私下报告漏洞 SECURITY.md。

已知的限制

• 仅限无状态HTTP。 没有会话恢复，服务器启动SSE流， 或OAuth 2.0授权（尚未）。GET/DELETE返回设计的405。
• 单节点SQLite。 WAL模式支持并发本地进程，但不支持 分布式跟踪存储。
• 令牌计数是估计值。 它们不能代替提供商计费，而且 非常大的自动有效载荷使用char /4近似值。
• 警报仅在 trace_end 在数据库范围的度量中，使用 尽最大努力webhook交付，无需重试/重复数据删除。
• 保留工具状态在内存中。 set_retention_policy 必须在各自之后调用吗 重新启动;只有CLI启动清除是自动的。
• 仪表板是一个文件。 没有托管的仪表板或共享链接；HTML是 独立的，可以保存/共享故意。
• 按照约定，审计日志的完整性只能追加，而不是加密或 明显被拆封了的。
• node:sqlite 仍在发展 （更新的Node版本中的候选版本）。销一个 如果需要API稳定性，则生产中的节点版本。
• 没有团队共享、搜索UI或SSO。 这些都被记录在 ROADMAP.md。

贡献

看到 CONTRIBUTING.md。在打开PR之前运行完整的本地gate：

npm ci
npm run verify

提交消息遵循常规提交。每个拉取请求一个重点更改。

许可证

MIT -见 许可证。