mcp-agent-trace-inspector

MCP Agent Trace Inspector

npm mcp-agent-trace-inspector package

以本地优先、原生支持 MCP 的方式观测 Agent 工作流。每次工具调用、提示词转换、延迟和令牌数都会记录在本地 SQLite 数据库中——无需云账户或 API 密钥，追踪数据绝不会离开你的设备。本工具专为 MCP 构建，而非生硬地附加在通用大模型代理上。

工具参考 | 配置 | 贡献 | 故障排除 | 设计原则

主要功能

• 工具调用追踪：捕获工作流每个步骤的输入、输出、延迟和令牌用量。
• 持久化存储：追踪记录在会话重启后仍会保留；数据本地存储于 SQLite，无外部依赖。
• HTML 仪表板：生成独立的单文件仪表板，内含交互式步骤时间线。
• 令牌成本估算：使用可配置的模型定价表计算每条追踪记录的美元成本——无需调用 API。
• 追踪对比：并排对比两条追踪记录，衡量提示词或工具变更的影响。
• 低开销：每个步骤增加的耗时不到 5ms，绝不会成为瓶颈。

为什么选择它，而不是 LangSmith / AgentOps？

	mcp-agent-trace-inspector	LangSmith / AgentOps
数据位置	本地 SQLite——绝不会离开你的设备	托管于云端；追踪数据会发送到外部服务器
设置	一条 npx 命令，无需配置	注册账户、获取 API 密钥、通过 SDK 进行埋点
支持 MCP	原生支持——将工具调用记录为一等步骤	通用大模型代理；MCP 结构不透明
运行对比	内置 compare_traces 差异对比	需单独付费的功能或手动导出
成本估算	离线 tiktoken + 可配置的定价表	需要通过其代理发送实时 API 流量
开销	每个步骤 <5ms	每个事件都需要一次网络往返

如果你的追踪记录包含敏感的工具输出、专有提示词或必须留在设备上的数据，那么这就是合适的工具。如果你需要跨团队共享追踪记录或托管式 SaaS，请使用 LangSmith。

免责声明

mcp-agent-trace-inspector 会将工具调用的输入和输出本地存储在 SQLite 数据库中。追踪记录可能包含传递给工具或由工具返回的敏感信息。分享仪表板导出内容前，请检查追踪记录。追踪记录不会自动传输；你可以选择使用提醒 Webhook。

要求

• Node.js v22.5.0 或更高版本。
• npm。

快速开始

将以下配置添加到你的 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"
      ]
    }
  }
}

MCP 客户端配置

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

你的第一个提示词

在 MCP 客户端中输入以下内容，验证一切是否正常运行：

Start a trace called "test-run", then list the files in the current directory, then end the trace and show me the summary.

你的客户端应返回一份摘要，其中显示步骤数、令牌总数和延迟。

工具

追踪生命周期（3 个工具）

• trace_start — 开始一条新的追踪记录；返回供后续调用使用的 trace_id
• trace_step — 记录一次工具调用步骤（输入、输出，以及可选的令牌数和延迟）
• trace_end — 将追踪记录标记为已完成

检查（4 个工具）

• list_traces — 列出已存储的追踪记录，包括名称、状态和时间戳
• get_trace_summary — 获取追踪记录的令牌总数、步骤数、延迟和成本估算
• compare_traces — 并排对比两条追踪记录的差异（步骤数、令牌数、延迟）
• extract_reasoning_chain — 仅提取追踪记录中的推理／思考步骤

导出（3 个工具）

• export_dashboard — 生成包含延迟瀑布图的独立单文件 HTML 仪表板
• export_otel — 以 OpenTelemetry OTLP JSON span 格式导出一个或全部追踪记录
• export_compliance_log — 将合规审计日志导出为 JSON 或 CSV，并可选按日期范围筛选

运维（3 个工具）

• configure_alerts — 配置针对延迟、错误率或成本的告警规则；触发后发送到 Slack 或通用 Webhook
• set_retention_policy — 设置保留追踪记录的天数（存储于内存中；必须在调用 apply_retention 前调用）
• apply_retention — 归档超过已配置阈值的追踪记录；删除超过该阈值 2 倍的追踪记录

配置

--db / --db-path

用于存储追踪记录的 SQLite 数据库文件路径。

类型：string 默认值：~/.mcp/traces.db

--retention-days

自动删除超过 N 天的追踪记录。设为 0 可禁用。

类型：number 默认值：0

--pricing-table

包含自定义模型定价（$/1K tokens）的 JSON 文件路径。此文件会覆盖内置定价表。

类型：string

--no-token-count

禁用基于 tiktoken 的令牌计数。追踪记录中将不包含令牌用量指标。

类型：boolean 默认值：false

通过 JSON 配置中的 args 属性传递标志：

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

设计原则

• 仅追加追踪记录：记录后，步骤不可更改。信任有赖于完整性。
• 本地优先：所有核心功能都可在没有网络连接的情况下运行。
• 可移植的仪表板：HTML 导出始终是单文件；无需服务器即可查看。

验证

发布新版本前，请使用 MCP Inspector 验证服务，确认所有工具均已正确公开，且协议握手成功。

交互式 UI（打开浏览器）：

npm run build && npm run inspect

CLI 模式（适用于脚本 / CI）：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_traces

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list_traces --tool-arg key=value

发布前运行此检查，以发现工具注册和运行时启动方面的回归问题。

贡献

完整的贡献指南请参阅 CONTRIBUTING.md。

npm install && npm test

MCP 注册表与市场

此插件可在以下平台获取：

• MCP 注册表
• MCP Market

搜索 mcp-agent-trace-inspector。