# mcp-agent-trace-inspector 中文文档

规范地址：https://npmcn.com/package/mcp-agent-trace-inspector/

版本：1\.0\.1
npm 元数据更新时间：2026-11-04T02:11:57.112Z
中文译文更新时间：2026-11-04T05:51:24.984Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/mcp-agent-trace-inspector
原文对照：https://npmcn.com/package/mcp-agent-trace-inspector/?lang=original
项目主页：https://github.com/dbsectrainer/mcp-agent-trace-inspector#readme
源码仓库：https://github.com/dbsectrainer/mcp-agent-trace-inspector

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：717 kB，83 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.13\.0
- 运行依赖：4 个
- 首次发布：2026-03-23T19:56:42.111Z
- 最新版本发布：2026-11-04T02:11:56.908Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

MCP代理工作流的逐步可观察性

## 安装

```sh
npm install mcp-agent-trace-inspector
```

也可以使用：`pnpm add mcp-agent-trace-inspector`、`yarn add mcp-agent-trace-inspector`、`bun add mcp-agent-trace-inspector`

## README

# MCP代理跟踪检查员

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

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

[工具](https://npmcn.com/package/mcp-agent-trace-inspector/#readme-tools) · [配置](https://npmcn.com/package/mcp-agent-trace-inspector/#readme-configuration) · [HTTP传输](https://npmcn.com/package/mcp-agent-trace-inspector/#readme-streamable-http-transport) · [验证](https://npmcn.com/package/mcp-agent-trace-inspector/#readme-verification) · [已知的限制](https://npmcn.com/package/mcp-agent-trace-inspector/#readme-known-limitations) · [贡献](https://npmcn.com/package/mcp-agent-trace-inspector/#readme-contributing)

## 概述

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

```text
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 （ESM，内置） `node:sqlite`） |
| 语言 | TypeScript 5，严格模式 |
| 协议 | `@modelcontextprotocol/sdk` （工具、资源、提示） |
| HTTP | Express 5 + MCP可流HTTP传输 |
| 存储 | SQLite通过 `node:sqlite` |
| 标记 | `gpt-tokenizer` （`cl100k_base`） |
| CLI | `yargs` |
| 测试 | Vitest + V8覆盖率 |
| Lint /格式化 | ESLint + Prettier |
| CI | GitHub操作（安装、审计、检测、格式化、测试、构建） |

## 需求

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

## 快速入门（MCP客户端）

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

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

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

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

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

```text
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服务器自动。

### 从源

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

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

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

## 可流式HTTP传输

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

```bash
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
```

初始化端点：

```bash
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帧。调用工具：

```bash
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":{}}}'
```

| 行为 | 价值 |
| --- | --- |
| 端点 | `POST /mcp` |
| `GET` / `DELETE /mcp` | `405` 与 `Allow: POST` |
| 默认绑定地址 | `127.0.0.1` (仅回送) |
| 请求体限制 | 10 MB |
| 速率限制 | 60个请求/ 60秒每个验证的API密钥或客户端IP |
| 身份验证(可选) | `X-API-Key` 和/或 `Authorization: Bearer <HS256 JWT>` |
| DNS-rebinding警卫 | 绑定环回时，主机头必须为localhost/127.0.0.1 |

### HTTP身份验证

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

```bash
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旗帜

| 国旗 | 默认的 | 描述 |
| --- | --- | --- |
| `--db`， `--db-path` | `~/.mcp/traces.db` | SQLite数据库文件。 `~` 是扩大。 `:memory:` 用于测试。 |
| `--retention-days` | `0` | 启动时，删除超过N天的跟踪。 `0` 禁用。 |
| `--pricing-table` | 内置的表 | 的JSON文件 `{ "model": { "input": number, "output": number } }`． 在内置速率上合并。 |
| `--no-token-count` | `false` | 禁用自动令牌计数(`token_count` 价值观成为 `null`）. |
| `--http-port` | 设置 | 在此端口（1-65535）上以HTTP模式启动，而不是stdio。 |
| `--http-host` | `127.0.0.1` | HTTP绑定地址。除非使用身份验证和TLS，否则首选环回。 |
| `--help` | \- - - - - - | 显示使用。 |
| `--version` | \- - - - - - | 打印软件包版本。 |

### 环境变量

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

| 变量 | 默认的 | 目的 |
| --- | --- | --- |
| `MCP_API_KEY` | 设置 | 仅HTTP: require `X-API-Key` 每一个请求。 |
| `MCP_JWT_SECRET` | 设置 | 仅HTTP：需要一个有效的HS256承载JWT。 |
| `MCP_AUDIT_LOG_PATH` | `~/.mcp/trace-inspector-audit.jsonl` | 合规性审计日志路径。已创建所有者可读/可写(`0600`）. |
| `MCP_SLACK_WEBHOOK` | 设置 | 警报触发时使用的Slack传入webhook URL。 |
| `MCP_ALERT_WEBHOOK` | 设置 | 触发警报时使用的通用JSON webhook URL。 |

看到 [`.env.example`](https://npmcn.com/package/mcp-agent-trace-inspector/.env.example) 用于复制粘贴模板。永远不要真正承诺 机密或数据库文件；两者都被忽略 `.gitignore`。

## 工具

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

### 跟踪生命周期

| 工具 | 目的 |
| --- | --- |
| `trace_start` | 开始追踪。返回一个 `trace_id`。通过 `"auto"` 或者为生成的名称使用空字符串。 |
| `trace_step` | 为a记录一个步骤 **运行** 跟踪。以下步骤被拒绝 `trace_end`。 |
| `trace_end` | 标记跟踪已完成，评估警报规则，并返回触发的警报。重复调用是幂等的。 |

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

### 检查

| 工具 | 目的 |
| --- | --- |
| `list_traces` | 列出踪迹，最新的优先。可选的正整数 `limit`。 |
| `get_trace_summary` | 步骤/令牌/延迟总数、持续时间、成本估计、推理检测。 |
| `compare_traces` | 有两个不同的轨迹：聚合、工具覆盖和每个位置的步骤。 |
| `extract_reasoning_chain` | 只返回推理/思考/计划步骤。 |

### 出口

| 工具 | 目的 |
| --- | --- |
| `export_dashboard` | 包含错误行、可扩展JSON和延迟瀑布的自包含HTML仪表板。 |
| `export_otel` | OTLP/JSON文件(`resourceSpans → scopeSpans → spans`)用于一个或所有的痕迹。 |
| `export_compliance_log` | 审计日志为JSON或CSV，可选地通过 `from_date` / `to_date` （仅限日期的上限包括全天）。 |

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

### 操作

| 工具 | 目的 |
| --- | --- |
| `configure_alerts` | 持久化警报规则(`latency`， `error_rate`， `cost`）. 可选的Slack/generic webhooks。 |
| `set_retention_policy` | 设置进程内保留策略（天）。必须在 `apply_retention` 在这个过程中。 |
| `apply_retention` | 超过N天的档案记录；删除超过2×N天的存档跟踪。 |

## 资源和提示

-   **资源** -每个跟踪都暴露为 `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保留先前配置的通道。

## 验证

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

```bash
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验证：

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

### 视觉证据

仪表盘是由实物生成的 `export_dashboard` 工具从一个真实的痕迹和 在Chrome中打开桌面和移动视窗大小。看到 [核查报告](https://npmcn.com/package/mcp-agent-trace-inspector/docs/evidence/verification-report.md) 对于命令， 测试结果，以及每个截图的工作流关联。

![Desktop dashboard showing the trace timeline, stats, and error row](https://npmcn.com/package/mcp-agent-trace-inspector/docs/evidence/screenshots/dashboard-desktop.png)

![Mobile dashboard with responsive stat cards and card-style step timeline](https://npmcn.com/package/mcp-agent-trace-inspector/docs/evidence/screenshots/dashboard-mobile.png)

![Dashboard with an error step's input expanded](https://npmcn.com/package/mcp-agent-trace-inspector/docs/evidence/screenshots/dashboard-error-step.png)

## 安全

跟踪包含工具输入和输出，可能包括秘密、提示或个人信息 数据。检查器将它们存储在本地，并且不会传输它们，除非您 配置警报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](https://npmcn.com/package/mcp-agent-trace-inspector/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](https://npmcn.com/package/mcp-agent-trace-inspector/ROADMAP.md)。

## 贡献

看到 [CONTRIBUTING.md](https://npmcn.com/package/mcp-agent-trace-inspector/CONTRIBUTING.md)。在打开PR之前运行完整的本地gate：

```bash
npm ci
npm run verify
```

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

## 许可证

MIT -见 [许可证](https://npmcn.com/package/mcp-agent-trace-inspector/LICENSE)。

## 常见问题

### mcp-agent-trace-inspector 是什么？

MCP代理工作流的逐步可观察性

### 如何安装 mcp-agent-trace-inspector？

在项目目录运行 npm install mcp-agent-trace-inspector，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-agent-trace-inspector，可以用 npx mcp-agent-trace-inspector 直接运行。

### mcp-agent-trace-inspector 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/mcp-agent-trace-inspector 是否存在。

### mcp-agent-trace-inspector 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### mcp-agent-trace-inspector 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### mcp-agent-trace-inspector 可以商用吗？

mcp-agent-trace-inspector 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### mcp-agent-trace-inspector 还在维护吗？

最新版本 1\.0\.1 发布于 2026/11/04（今天）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。