@tonyclaw/agent-inspector-mcp

v3.0.7

Published

14 days ago

MCP-first companion CLI for Agent Inspector.

0High
0Medium
0Low

tonyclaw

mcp model-context-protocol agent-inspector agent-observability coding-agent evidence

Agent Inspector MCP

@tonyclaw/agent-inspector-mcp 是 @tonyclaw/agent-inspector 的 MCP-first 配套命令行工具。

Agent Inspector 本身已经内置了 Streamable HTTP MCP endpoint：

http://localhost:9527/api/mcp

Agent Inspector v3 默认 CLI 会在兼容窗口内保留 http://localhost:25947/api/mcp 作为 legacy alias，但新 MCP 配置建议使用 9527。

这个包额外提供一个 stdio bridge，给那些不能直接连接 Streamable HTTP MCP 的客户端使用。它不会启动第二个 Inspector 服务，也不会创建独立的观测实例。它只是把 stdio 中的 JSON-RPC 消息转发到正在运行的 Agent Inspector /api/mcp，再把 MCP 响应写回 stdout。

同一个 MCP client 中，同一个 Inspector 实例只配置一种 transport：

支持 Streamable HTTP MCP 的客户端：直接配置 http://localhost:9527/api/mcp。
只支持 stdio 的客户端：配置 agent-inspector-mcp stdio。

如果两个都配，客户端里可能会出现重复的 Inspector tools。

什么时候使用

以下场景适合使用 agent-inspector-mcp：

MCP client 只支持 stdio server。
希望 Codex、Claude Desktop、Cursor 或其他客户端通过本地命令调用 Inspector tools。
需要评测证据流：声明 run、挂载 session、导出 evidence pack、生成报告。
评测系统会启动多个 coding-agent 进程，并希望按模型或 provider 聚合 session。
希望 agent 可以查看已捕获的请求、日志、session、provider 和本地知识候选，而不是手工暴露原始文件。

如果你的 MCP client 已经支持 Streamable HTTP MCP，优先直接使用内置 endpoint。这样路径最短，也少一个 bridge 进程。

安装

npm install -g @tonyclaw/agent-inspector @tonyclaw/agent-inspector-mcp

先启动 Agent Inspector：

agent-inspector

然后验证 MCP bridge：

agent-inspector-mcp doctor

正常输出会包含：

OK health: health check ok
OK mcp: mcp initialize ok

命令

| 命令 | 用途 | | --- | --- | | agent-inspector-mcp stdio [--url <endpoint>] | 启动到 Agent Inspector /api/mcp 的 stdio bridge。 | | agent-inspector-mcp doctor [--url <endpoint>] [--json] | 检查 /api/health 和 MCP initialize 握手。 | | agent-inspector-mcp config codex [--url <endpoint>] [--config <path>] [--dry-run] | 如果 Codex 配置中还没有 Inspector，则添加 stdio MCP 配置。 |

endpoint 解析优先级：

--url <endpoint>
AGENT_INSPECTOR_MCP_URL
http://localhost:9527/api/mcp

示例：

agent-inspector-mcp stdio --url http://localhost:9527/api/mcp
agent-inspector-mcp doctor --json
AGENT_INSPECTOR_MCP_URL=http://localhost:9527/api/mcp agent-inspector-mcp stdio

配置 API / Options

| 配置面 | 名称 | 示例 | 说明 | | --- | --- | --- | --- | | CLI option | --url | --url http://localhost:9527/api/mcp | 针对单次命令覆盖 Agent Inspector MCP endpoint。 | | 环境变量 | AGENT_INSPECTOR_MCP_URL | http://localhost:9527/api/mcp | stdio、doctor、config codex 使用的默认 endpoint。 | | HTTP endpoint | GET /api/health | http://localhost:9527/api/health | agent-inspector-mcp doctor 使用的健康检查接口。 | | MCP endpoint | POST /api/mcp | http://localhost:9527/api/mcp | Agent Inspector 暴露的 Streamable HTTP MCP endpoint。 | | JSON config | mcpServers.agent-inspector.command | agent-inspector-mcp | stdio-only MCP client 使用的命令。 | | JSON config | mcpServers.agent-inspector.args | ["stdio", "--url", "..."] | stdio bridge 参数。 | | JSON config | mcpServers.agent-inspector.env | { "AGENT_INSPECTOR_MCP_URL": "..." } | 支持 per-server env 的 MCP client 可使用的环境变量块。 | | JSON config | mcpServers.agent-inspector.url | http://localhost:9527/api/mcp | 支持直接连接 Streamable HTTP MCP 的客户端使用。 | | JSON config | mcpServers.agent-inspector.type | streamable-http | 部分客户端使用的直接 HTTP MCP transport 标记。 | | JSON config | mcpServers.agent-inspector.transport | streamable-http | 另一类客户端使用的 transport 标记。 | | Codex TOML | [mcp_servers.agent-inspector] | command = "agent-inspector-mcp" | agent-inspector-mcp config codex 生成的 Codex MCP server 配置块。 | | OpenCode JSON | mcp.agent-inspector.type | local | OpenCode MCP server 类型。stdio bridge 使用 local。 | | OpenCode JSON | mcp.agent-inspector.command | ["agent-inspector-mcp", "stdio", "--url", "..."] | OpenCode 为本地 MCP server 执行的命令数组。 | | OpenCode JSON | mcp.agent-inspector.enabled | true | 启用 OpenCode 中的 Inspector MCP server。 | | OpenCode JSON | mcp.agent-inspector.environment | { "AGENT_INSPECTOR_MCP_URL": "..." } | 本地 MCP 进程可选环境变量。 | | OpenCode JSON | mcp.agent-inspector.url | http://localhost:9527/api/mcp | OpenCode 使用 type: "remote" 时的直接 MCP URL。 |

stdio bridge 和直接 HTTP URL 指向同一个 Inspector 实例。每个 MCP client entry 只选择一种。

MCP JSON 配置

只支持 stdio 的 MCP client：

{
  "mcpServers": {
    "agent-inspector": {
      "command": "agent-inspector-mcp",
      "args": ["stdio", "--url", "http://localhost:9527/api/mcp"]
    }
  }
}

如果客户端支持为单个 server 配置环境变量：

{
  "mcpServers": {
    "agent-inspector": {
      "command": "agent-inspector-mcp",
      "args": ["stdio"],
      "env": {
        "AGENT_INSPECTOR_MCP_URL": "http://localhost:9527/api/mcp"
      }
    }
  }
}

支持直接连接 Streamable HTTP MCP 的客户端：

{
  "mcpServers": {
    "agent-inspector": {
      "url": "http://localhost:9527/api/mcp",
      "type": "streamable-http"
    }
  }
}

有些客户端使用 transport 而不是 type：

{
  "mcpServers": {
    "agent-inspector": {
      "url": "http://localhost:9527/api/mcp",
      "transport": "streamable-http"
    }
  }
}

不要在同一个客户端名称下同时配置 stdio bridge 和 Streamable HTTP URL。

Codex 配置

自动配置 Codex：

agent-inspector-mcp config codex

只预览，不写入：

agent-inspector-mcp config codex --dry-run

等价的 Codex TOML：

[mcp_servers.agent-inspector]
command = "agent-inspector-mcp"
args = ["stdio", "--url", "http://localhost:9527/api/mcp"]

OpenCode 配置

OpenCode 配置使用 opencode.json 或 opencode.jsonc 中的 mcp 对象。它不使用上面通用 MCP JSON 示例里的 mcpServers 对象。enabled: true 在 OpenCode 自己生成的配置里是可选字段，Agent Inspector 示例中保留它是为了让启用状态更明确。最快配置方式：

agent-inspector onboard --opencode-only
opencode mcp list

生成的配置是一个本地 MCP server，运行 stdio bridge：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-inspector": {
      "type": "local",
      "command": [
        "agent-inspector-mcp",
        "stdio",
        "--url",
        "http://localhost:9527/api/mcp"
      ],
      "enabled": true
    }
  }
}

如果你希望把 endpoint 放到环境变量里：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-inspector": {
      "type": "local",
      "command": ["agent-inspector-mcp", "stdio"],
      "environment": {
        "AGENT_INSPECTOR_MCP_URL": "http://localhost:9527/api/mcp"
      },
      "enabled": true
    }
  }
}

OpenCode 也支持 remote MCP server。如果你的 OpenCode 版本可以直接连接 Agent Inspector 的 Streamable HTTP endpoint，可以使用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-inspector": {
      "type": "remote",
      "url": "http://localhost:9527/api/mcp",
      "enabled": true
    }
  }
}

本地 stdio bridge 和 remote URL 二选一。编辑配置后运行：

opencode mcp list

在 prompt 里按 server name 引用：

Use agent-inspector to inspect the latest failed coding-agent session.

网络说明

如果 coding agent 和 Agent Inspector 不在同一个容器或机器里，把 localhost 替换成可访问的 host 或 IP：

{
  "mcpServers": {
    "agent-inspector": {
      "command": "agent-inspector-mcp",
      "args": ["stdio", "--url", "http://192.168.1.20:9527/api/mcp"]
    }
  }
}

需要对外可访问时，启动 Inspector 时指定 host：

agent-inspector --host 0.0.0.0

然后验证网络连通性：

agent-inspector-mcp doctor --url http://192.168.1.20:9527/api/mcp

MCP 能力列表

Agent Inspector 暴露 tools、resources 和 prompts。stdio bridge 暴露的能力与内置 /api/mcp endpoint 相同。

Tools

| Tool | 用途 | | --- | --- | | inspector_list_logs | 列出已捕获 agent/model 日志的有界摘要。 | | inspector_search_logs | 按 id、session、model、provider、API path、status、error 或 client context 搜索紧凑日志。 | | inspector_get_log | 读取一条完整捕获日志。 | | inspector_get_log_chunks | 读取流式日志的 SSE chunks。 | | inspector_list_sessions | 列出 Inspector 观测到的 session id。 | | inspector_get_session | 读取适合做证据的 session 信息，包括 URL、数量、模型、provider、token 汇总和最近紧凑日志。 | | inspector_create_run | 在 coding-agent 任务开始前声明一次评测 run。 | | inspector_get_run | 读取一个已声明的 Inspector run。 | | inspector_update_run | 更新 run 状态或 metadata。 | | inspector_export_evidence | 将一个 run 的 evidence pack 导出为 JSON、Markdown 和 HTML。 | | inspector_get_recent_failures | 列出最近失败或取消的 run 以及证据摘要。 | | inspector_list_groups | 列出用于聚合 sessions/runs 的 group。 | | inspector_create_group | 声明一个评测或批处理 group。 | | inspector_get_group | 读取一个 group 及其成员。 | | inspector_update_group | 更新 group 状态或 metadata。 | | inspector_delete_group | 删除 group，可选择同时删除已导出的 evidence。 | | inspector_add_group_session | 在 group 中挂载或更新 session/run 成员。 | | inspector_export_group_evidence | 将 group evidence 导出为 JSON、Markdown 和 HTML。 | | inspector_list_models | 列出已捕获日志中出现过的模型名。 | | inspector_list_providers | 列出已配置 providers，默认隐藏 API key。 | | inspector_get_provider | 读取一个 provider，默认隐藏 API key。 | | inspector_replay_log | 使用原 provider replay 一条已捕获请求。 | | inspector_add_provider | 向本地 Inspector 配置中新增 provider。 | | inspector_update_provider | 更新已有 provider。 | | inspector_test_provider | 执行与 UI 相同的 provider 连通性测试。 | | inspector_create_session_knowledge | 从 session 生成脱敏后的知识候选草稿。 | | inspector_list_knowledge_candidates | 列出本地知识候选。 | | inspector_promote_knowledge_candidate | 将已审核候选提升到配置的知识后端。 | | inspector_search_knowledge | 搜索 Inspector/OpenClaw-backed knowledge。 | | inspector_get_project_context | 为 agent 任务读取相关 project context。 |

Resources

| Resource | URI | 用途 | | --- | --- | --- | | inspector_sessions | inspector://sessions | 已观测到的 session ids。 | | inspector_session | inspector://sessions/{sessionId} | 适合证据使用的 session summary。 | | inspector_log | inspector://logs/{id} | 一条捕获到的 proxy log。 | | inspector_runs | inspector://runs | 已声明的 evaluation runs。 | | inspector_run | inspector://runs/{runId} | 一个已声明 run。 | | inspector_evidence | inspector://evidence/{runId} | 一个 run 的 Markdown evidence pack。 | | inspector_recent_failures | inspector://failures/recent | 最近 run failures。 | | inspector_groups | inspector://groups | 已声明 groups。 | | inspector_group | inspector://groups/{groupId} | 一个 group 及其挂载成员。 | | inspector_group_sessions | inspector://groups/{groupId}/sessions | group 中挂载的 session/run members。 | | inspector_group_evidence | inspector://groups/{groupId}/evidence | 一个 group 的 Markdown evidence pack。 |

Prompts

| Prompt | 用途 | | --- | --- | | inspector_analyze_session_failure | 分析一个 coding-agent session 为什么失败。 | | inspector_triage_recent_failures | 对最近失败进行优先级排序并给出下一步动作。 | | inspector_generate_jenkins_report | 基于 run 生成 Jenkins-friendly Markdown 报告。 | | inspector_generate_group_report | 基于 group 生成模型或 provider 评测报告。 | | inspector_extract_repro_steps | 将 session 转换为简洁可复现步骤。 |

常见评测流程

评测系统可以按这个顺序使用 MCP tools：

在评测矩阵开始前调用 inspector_create_group。
为每个 model/provider worker 调用 inspector_create_run，并传入 group 的 groupId。
通过 Agent Inspector proxy 启动 coding agent。
发现或传入 Inspector sessionId。
调用 inspector_update_run 写入真实 sessionId；带 groupId 的 run 会自动挂载到 group。
可选调用 inspector_add_group_session，补充或覆盖 model/provider 标签。
每个 worker 完成或失败时调用 inspector_update_run。
对每个 run 调用 inspector_export_evidence。
对整个矩阵调用 inspector_export_group_evidence。
让 MCP client 使用 inspector_generate_group_report 生成报告。

排障

GET /api/mcp 返回 406 Not Acceptable。

这是正常现象。MCP endpoint 不是浏览器页面。请使用 POST 发送 MCP JSON-RPC，并携带 Accept: application/json, text/event-stream，或者使用 agent-inspector-mcp stdio。

MCP client 中出现重复的 Inspector tools。

移除一种 transport。保留 Streamable HTTP config 或 stdio bridge config 中的一个即可。

doctor 的 health 或 initialize 失败。

检查 Agent Inspector 是否已经启动：

agent-inspector
agent-inspector-mcp doctor

如果 Inspector 运行在另一个容器或机器里，把 localhost 替换成可访问的 host/IP，并确认端口开放。