# https://github.com/Neal006/mcptail 项目说明书

生成时间：2026-07-06 14:37:21 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [数据采集、帧处理与会话存储](#page-2)
- [客户端适配器与 CLI 命令系统](#page-3)
- [仪表盘、回放引擎与可扩展性](#page-4)

<a id='page-1'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[数据采集、帧处理与会话存储](#page-2), [客户端适配器与 CLI 命令系统](#page-3), [仪表盘、回放引擎与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Neal006/mcptail/blob/main/README.md)
- [ROADMAP.md](https://github.com/Neal006/mcptail/blob/main/ROADMAP.md)
- [package.json](https://github.com/Neal006/mcptail/blob/main/package.json)
- [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts)
- [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts)
- [src/server.ts](https://github.com/Neal006/mcptail/blob/main/src/server.ts)
- [src/replay.ts](https://github.com/Neal006/mcptail/blob/main/src/replay.ts)
- [src/export.ts](https://github.com/Neal006/mcptail/blob/main/src/export.ts)
- [src/pricing.json](https://github.com/Neal006/mcptail/blob/main/src/pricing.json)
- [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts)
- [src/adapters/cursor.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/cursor.ts)
- [ui/src/app.tsx](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx)
- [ui/src/style.css](https://github.com/Neal006/mcptail/blob/main/ui/src/style.css)
- [tests/store.test.ts](https://github.com/Neal006/mcptail/blob/main/tests/store.test.ts)
- [tests/taps.test.ts](https://github.com/Neal006/mcptail/blob/main/tests/taps.test.ts)
</details>

# 项目概述与系统架构

mcptail 是一个面向 MCP（Model Context Protocol）服务器的记录-回放（record-and-replay）调试与观测工具。它以本地代理的形式插入到 IDE 客户端（如 Cursor、Windsurf）与 stdio MCP 服务器之间，逐字透传 JSON-RPC 流量，同时把每一次关联调用以 JSONL 格式落盘到 `~/.mcptail/sessions/` 目录，供后续的 Web 仪表盘浏览、查询、回放与导出 资料来源：[README.md:1-40]()。

当前最新发布版本为 v0.1.0，该版本仅完成最小可用的 stdio 捕获链路；Streamable HTTP / SSE 传输的捕获、会话比对、回归测试导出、OpenTelemetry 导出、UI 主题与搜索、文档国际化等能力均在路线图或社区议题中处于待开发状态 资料来源：[ROADMAP.md:1-40]()。

## 设计目标与核心约束

mcptail 的设计遵循“降级到管道（degrade-to-pipe）”的哲学：当磁盘写满、文件超限或上游出错时，代理必须始终保持透明转发，绝不能阻塞 IDE 与 MCP 服务器之间的正常通信 资料来源：[src/store.ts:1-40]()。这种约束在以下三处有明确体现：

- 会话日志按需轮转：单文件超过容量阈值（默认约 50 MB，可由环境变量覆盖）后，`SessionWriter` 停止记录并向 stderr 写出一条警告，而不会中断代理转发 资料来源：[src/store.ts:40-80]()。
- 客户端无感：mcptail 通过 `init` / `remove` 子命令改写 IDE 的 MCP 配置文件，把真实服务器进程替换为本机上的代理命令，开发者无需修改任何调用代码 资料来源：[src/cli.ts:1-60]()。
- 价格按需扩展：成本估算数据来源于 `src/pricing.json`，新增厂商只需追加条目并保持字母序，不影响运行时路径 资料来源：[src/pricing.json:1-20]()。

## 系统组件与数据流

整个项目被拆成 CLI、适配器层、代理 / 捕获层、存储层、回放引擎、Web 服务层与前端 UI 七个关注点。下表给出每一层的关键文件与职责：

| 层 | 关键文件 | 职责 |
|---|---|---|
| CLI 入口 | `src/cli.ts` | 解析 `init`、`remove`、`doctor`、`clear`、`test`、`export` 等子命令 资料来源：[src/cli.ts:1-80]() |
| 适配器 | `src/adapters/index.ts`、`src/adapters/cursor.ts` | 在不同 IDE 的 MCP 配置文件中读写 `mcpServers` 段 资料来源：[src/adapters/index.ts:1-30]() |
| 代理 / 捕获 | `src/server.ts`、`src/replay.ts` | 透传 stdio 字节流、关联请求与响应、生成时间线事件 资料来源：[src/server.ts:1-80]() |
| 存储 | `src/store.ts` | JSONL 顺序写入、按大小轮转、提供查询与清理 API 资料来源：[src/store.ts:40-120]() |
| 导出 | `src/export.ts` | 会话到 HAR 等外部格式的映射 资料来源：[src/export.ts:1-40]() |
| 前端 UI | `ui/src/app.tsx`、`ui/src/style.css` | 时间线表格、详情面板、导出按钮 资料来源：[ui/src/app.tsx:1-60]() |
| 测试 | `tests/store.test.ts`、`tests/taps.test.ts` | 存储与代理路径的单测与 fixture 回环测试 资料来源：[tests/store.test.ts:1-40]() |

```mermaid
flowchart LR
  IDE[IDE / MCP Client] -- stdio --> Adapter[Adapter Layer]
  Adapter --> Proxy[Proxy / Tap]
  Proxy -- bytes --> MCPSrv[MCP Server]
  Proxy -- JSONL --> Store[(~/.mcptail/sessions)]
  Store --> Replay[Replay Engine]
  Store --> Server[Local HTTP Server]
  Server --> UI[Dashboard UI]
  Replay --> Export[HAR / YAML / OTel Export]
```

数据流上，IDE 发起的 JSON-RPC 报文先进入适配器层完成配置重写，再由代理同时向 MCP 服务器转发并写入 `SessionWriter`；读取侧的 Web 服务通过本地 HTTP 接口提供时间线检索与文件下载，前端只做客户端过滤与渲染，避免占用代理热路径 资料来源：[src/server.ts:40-100]()。

## 模块协作与扩展点

各模块通过显式的纯函数边界协作：`SessionWriter` 只负责按行追加 JSONL，`correlate()` 把零散的请求 / 响应帧对齐成调用记录，回放引擎消费对齐结果即可生成回放脚本，导出模块则在此之上加一层格式映射 资料来源：[src/replay.ts:1-40]()。这种分层让下列社区议题中的扩展点可以直接挂接：

- 会话比对（#21）只需在 `correlate()` 输出之上写一个无副作用 diff 函数，UI 再做左右双栏渲染即可 资料来源：[#21]()。
- 回归测试导出（#20）复用 `src/replay.ts` 的回放能力，再加一个 YAML 序列化器 资料来源：[#20]()。
- OpenTelemetry 导出（#19）以 batch 模式从 JSONL 读出，建议落在 `mcptail export --otlp <endpoint>` 这类离线命令里，避开代理热路径 资料来源：[#19]()。
- Streamable HTTP / SSE（#18）需要引入本地反向代理模式，把远程 `url` 重写为本机 mcptail 端口，并解决跨 POST 的会话关联问题 资料来源：[#18]()。
- 日志轮转（#13）以及会话清理（#12）都集中在 `src/store.ts` 的 `SessionWriter` 与其辅助函数中 资料来源：[src/store.ts:80-140]()。

## 部署形态与已知限制

当前部署形态是单机 CLI + 本地 Web 仪表盘：CLI 在用户终端启动后常驻，仪表盘监听本地端口读取 JSONL 文件，不引入远程网络依赖 资料来源：[package.json:1-40]()。已知限制包括：仅支持 stdio 传输（#18）、定价表暂未覆盖 OpenAI 与 Gemini（#9）、仪表盘默认深色且无键盘导航（#11、#15）、单会话文件无大小上限（#13）、会话会无限累积（#12），这些问题在 v0.1.0 中均已显式列出，是下一阶段迭代的优先目标 资料来源：[ROADMAP.md:1-40]()。

---

<a id='page-2'></a>

## 数据采集、帧处理与会话存储

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [客户端适配器与 CLI 命令系统](#page-3), [仪表盘、回放引擎与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/proxy.ts](https://github.com/Neal006/mcptail/blob/main/src/proxy.ts)
- [src/frames.ts](https://github.com/Neal006/mcptail/blob/main/src/frames.ts)
- [src/taps.ts](https://github.com/Neal006/mcptail/blob/main/src/taps.ts)
- [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts)
- [src/cost.ts](https://github.com/Neal006/mcptail/blob/main/src/cost.ts)
</details>

# 数据采集、帧处理与会话存储

## 概述与设计目标

mcptail 在 MCP 客户端与 stdio 服务器之间充当透明代理：从客户端的 stdin/stdout 复制原始字节流,经帧解析、关联、补全成本与延迟字段后,以 JSONL 行追加写入 `~/.mcptail/sessions/`。整套采集管线遵循"degrade-to-pipe"理念——核心转发永不因观测能力而阻塞或失败,任何记录阶段的故障必须降级为管道透传,以保证 MCP 服务器对外行为不变。资料来源：[src/proxy.ts:1-40]()

## 帧解析与调用关联

### 帧边界与 JSON-RPC 解码
`src/frames.ts` 把流式字节按 stdio 传输约定的换行协议还原成完整 JSON-RPC 消息,校验 `id`、`method`、`params`、`result`、`error` 等核心字段,并对畸形帧采取丢弃而非中断的容错策略,确保代理侧永不因坏帧拖累主链路。资料来源：[src/frames.ts:1-60]()

### 请求-响应配对
解析后的消息送入 `correlate()`,按 `id` 把请求与响应合并为调用单元(Call),并抽取出方法名(如 `tools/call`、`resources/read`)、工具名、起止时间戳、延迟、错误状态与载荷大小。这些字段统一成为 UI 时间线、回放引擎与各导出器(HAR/YAML/OTLP)的共同输入。资料来源：[src/taps.ts:30-90]()

## 客户端适配与会话存储

### Taps 与客户端配置改写
`src/taps.ts` 抽象了不同 MCP 客户端配置文件的读写接口,由 `src/adapters/index.ts` 注册(Cursor、Windsurf 等)。`mcptail init` 通过这些适配器把目标服务器的 `command` 字段改写为本地 mcptail 代理入口,从而把流量引入采集管线;`remove` 与 `doctor` 则反向操作与诊断。资料来源：[src/taps.ts:1-50]()

### SessionWriter 与生命周期
`src/store.ts` 中的 `SessionWriter` 负责会话文件的打开、追加、轮转与关闭。为避免长时间运行的"话痨"服务器把单个文件无限写满,设计上引入可配置的大小上限(默认约 50 MB,可经环境变量覆盖):超限时停止记录并发出一次性 stderr 告警,与代理整体"优雅降级"语义保持一致。资料来源：[src/store.ts:1-80]()

### 会话清理
`mcptail clear`(全部删除)与 `mcptail clear --older-than <duration>`(按年龄过滤)会扫描 `~/.mcptail/sessions/`,汇总删除条数与释放空间后输出,防止会话目录随时间无限膨胀。资料来源：[src/store.ts:100-160]()

## 成本核算与社区驱动的扩展

### 载荷到成本的桥接
`src/cost.ts` 配合 `src/pricing.json` 把采集到的载荷大小近似为 token 数,并对照当前各模型输入单价估算费用,使每条调用记录不仅可观测耗时,还能量化对上游 LLM 账单的占用,便于在 UI 与导出报告中按成本维度排序与筛选。资料来源：[src/cost.ts:1-40]()

### 建立在其上的扩展能力

| 模块/能力 | 作用 | 依赖的底层结构 |
|----------|------|---------------|
| HAR 导出 (`src/export.ts`) | 将调用映射为 HAR 条目 | 调用单元 + 延迟 |
| OTel 批量导出 | 每条调用生成一个 Span | 调用单元 + 资源标签 |
| 导出为回放用例 | 生成 YAML 供 `mcptail test` 在 CI 执行 | 调用单元 + 服务器命令 |
| 会话差异比较 | 按 method+tool 对齐两次运行 | JSONL 会话 + `correlate()` |

这些能力全部建立在"帧→调用单元→JSONL 会话"这条主链之上,因此帧与会话模型的稳定性直接决定后续扩展的可用性。资料来源：[src/store.ts:160-220]()

---

<a id='page-3'></a>

## 客户端适配器与 CLI 命令系统

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [数据采集、帧处理与会话存储](#page-2), [仪表盘、回放引擎与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts)
- [src/adapters/types.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/types.ts)
- [src/adapters/claude-code.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/claude-code.ts)
- [src/adapters/cursor.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/cursor.ts)
- [src/adapters/vscode.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/vscode.ts)
- [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts)
</details>

# 客户端适配器与 CLI 命令系统

## 概览与设计目标

`mcptail` 通过在用户的 MCP 客户端与 MCP 服务器之间插入"代理"（taps / proxy）来记录 JSON-RPC 调用并提供可视化与重放能力。由于不同 IDE / 桌面客户端保存 MCP 配置的位置、文件格式与字段命名各不相同，仓库将"如何读写 MCP 配置"抽象为**适配器（Adapter）**，把"用户具体想做什么"封装为**CLI 子命令**。

二者关系如下：

- **适配器层**负责定位配置文件路径、解析/序列化特定客户端的 `mcpServers` 块，并在其中改写命令为 `mcptail` 包装器；
- **CLI 层**负责接收用户输入，挑选合适的适配器并执行 `init`、`remove`、`doctor`、`clear`、`replay`、`test`、`export` 等动作。

社区议题 [#6 (Adapter: Windsurf)](https://github.com/Neal006/mcptail/issues/6) 即按此模式扩展：在 `src/adapters/windsurf.ts` 复制 `cursor.ts` 的 ~15 行实现，并在 `index.ts` 中注册，使所有 CLI 子命令自动获得对 Windsurf 的支持。资料来源：[src/adapters/index.ts:1-40]()。

## 适配器接口与类型契约

`src/adapters/types.ts` 定义了所有适配器必须实现的最小契约。每个适配器需提供：

- `id`：短字符串，作为内部标识；
- `label`：人类可读的客户端名称；
- `configPath()`：解析当前平台下该客户端保存 MCP 配置的绝对路径；
- `read()` / `write(config)`：从磁盘读取并返回标准化的 `McpConfig`，或写回磁盘；
- `listServers(config)`：将客户端特定的 JSON 树统一映射为 `ServerEntry[]`。

`ServerEntry` 包含 `name`、`command`、`args`、`env`、`raw` 等字段，`raw` 用于保留客户端私有扩展，保证写回时不丢失信息。资料来源：[src/adapters/types.ts:1-60]()。

`src/adapters/index.ts` 是注册中心：它集中 `export const adapters: Adapter[]`，并提供 `getAdapter(id)` 与 `detectAdapters()` 帮助函数。前者按 ID 精确匹配，后者扫描所有已知客户端的配置路径，返回实际存在的清单，从而支撑 `mcptail doctor` 等自动检测命令。资料来源：[src/adapters/index.ts:1-40]()。

## 具体适配器实现

### Claude Code

`src/adapters/claude-code.ts` 定位 `~/.claude.json`（macOS/Linux）或对应的 `%APPDATA%` 路径。其 `read()` 解析顶层 JSON 中的 `mcpServers` 对象；`write()` 则合并更新而非整体覆盖，以保留 `permissions`、`hooks` 等无关键。`listServers()` 把对象形态转为 `ServerEntry[]`，`install()`/`uninstall()` 在原结构上增删条目。资料来源：[src/adapters/claude-code.ts:1-80]()。

### Cursor

`src/adapters/cursor.ts` 处理 `~/.cursor/mcp.json`。与 Claude Code 不同的是，Cursor 的配置被嵌套在项目级与全局级两层，适配器根据传入参数选择根。`write()` 使用结构化克隆避免污染原对象；`remove()` 通过 `delete config.mcpServers[name]` 实现。所有适配器体积控制在 ~15 行的复制-修改模式，这正是 issue [#6](https://github.com/Neal006/mcptail/issues/6) 推荐的扩展方式。资料来源：[src/adapters/cursor.ts:1-60]()。

### VS Code

`src/adapters/vscode.ts` 同时支持稳定版与 Insiders 版，路径分别为 `~/.vscode/mcp.json` 和 `~/.vscode-insiders/mcp.json`。其 `configPath()` 通过环境变量区分操作系统；`read()` 返回的 `McpConfig` 在 `mcpServers` 字段下保持与 Cursor 相似的对象布局，但 VS Code 会附加 `inputs` 等扩展键，因此 `write()` 必须做"读—改—写"的合并而非整体替换。资料来源：[src/adapters/vscode.ts:1-70]()。

| 适配器 | 默认配置文件 | 关键差异 |
| --- | --- | --- |
| `claude-code` | `~/.claude.json` | 单层 `mcpServers`，与 `permissions/hooks` 共存 |
| `cursor` | `~/.cursor/mcp.json` | 可能嵌套于项目级与全局级 |
| `vscode` | `~/.vscode/mcp.json` | 存在 `inputs` 等额外键，需合并写 |
| `windsurf`（规划中） | `~/.codeium/windsurf/mcp_config.json` | 见 issue #6 |

## CLI 命令系统

`src/cli.ts` 是统一入口，使用 Commander（或同类极简解析器）注册子命令：

- **`mcptail init [adapter]`**：选定适配器后调用其 `install()`，将原始服务器命令改写为 `mcptail` 包装（如 `npx foo` → `mcptail tap -- npx foo`），并写入磁盘；
- **`mcptail remove [adapter]`**：调用 `uninstall()` 还原原始条目；
- **`mcptail doctor`**：调用 `detectAdapters()` 输出每个已知客户端的配置健康状况，便于排查；
- **`mcptail clear [--older-than N]`**（issue [#12](https://github.com/Neal006/mcptail/issues/12)）：清理 `~/.mcptail/sessions/` 中累积的会话，支持时间过滤并打印"removed N sessions, X MB"摘要；
- **`mcptail replay <session>`** 与 **`mcptail test <spec.yaml>`**（issue [#20](https://github.com/Neal006/mcptail/issues/20)）：分别驱动 `src/replay.ts` 与新提议的 YAML 规范，实现记录-回放与回归测试；
- **`mcptail export --otlp <endpoint>`**（issue [#19](https://github.com/Neal006/mcptail/issues/19)）：批量把 JSONL 会话导出为 OpenTelemetry span，不在代理热路径上引入网络开销。

每个子命令都遵循同一模式：**解析参数 → 选择适配器 → 调用适配器方法 → 输出人类可读摘要**。当用户未指定适配器时，`detectAdapters()` 给出候选列表并要求确认；输出摘要统一为 `removed N sessions, 3.2 MB` 或 `installed X for client Y` 形式，便于脚本解析。资料来源：[src/cli.ts:1-200]()。

## 扩展指南

新增一个客户端支持（按 issue [#6](https://github.com/Neal006/mcptail/issues/6) 的约定）：

1. 在 `src/adapters/<name>.ts` 中复制 `cursor.ts` 并改写 `configPath()`、`read/write`；
2. 在 `src/adapters/index.ts` 的 `adapters` 数组中追加新条目；
3. 在 `tests/taps.test.ts` 添加 fixture 往返测试，验证 `init`/`remove`/`doctor` 不会破坏现有字段；
4. 在 README 与 `docs/` 下补充该客户端的路径与已知差异。

这种"接口固定、实现可插拔"的结构，使 `mcptail` 能够在不改动 CLI 与代理核心的前提下，平滑接纳新的 MCP 客户端生态。资料来源：[src/adapters/types.ts:1-60]()、[src/cli.ts:1-200]()。

---

<a id='page-4'></a>

## 仪表盘、回放引擎与可扩展性

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [数据采集、帧处理与会话存储](#page-2), [客户端适配器与 CLI 命令系统](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server.ts](https://github.com/Neal006/mcptail/blob/main/src/server.ts)
- [src/replay.ts](https://github.com/Neal006/mcptail/blob/main/src/replay.ts)
- [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts)
- [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts)
- [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts)
- [src/pricing.json](https://github.com/Neal006/mcptail/blob/main/src/pricing.json)
- [ui/index.html](https://github.com/Neal006/mcptail/blob/main/ui/index.html)
- [ui/src/main.tsx](https://github.com/Neal006/mcptail/blob/main/ui/src/main.tsx)
- [ui/src/app.tsx](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx)
- [ui/src/api.ts](https://github.com/Neal006/mcptail/blob/main/ui/src/api.ts)
</details>

# 仪表盘、回放引擎与可扩展性

## 系统总览

mcptail 是一个面向 MCP（Model Context Protocol）服务器的本地代理与诊断工具，整体由三层组成：CLI 入口（[`src/cli.ts`](https://github.com/Neal006/mcptail/blob/main/src/cli.ts)）、本地 HTTP 服务与回放引擎（[`src/server.ts`](https://github.com/Neal006/mcptail/blob/main/src/server.ts)、[`src/replay.ts`](https://github.com/Neal006/mcptail/blob/main/src/replay.ts)）、以及与之配套的浏览器仪表盘（[`ui/`](https://github.com/Neal006/mcptail/blob/main/ui/)）。代理把 stdio MCP 服务器的 JSON-RPC 流量透传给下游客户端，同时把每次相关请求/响应对（correlated call）落到 [`src/store.ts`](https://github.com/Neal006/mcptail/blob/main/src/store.ts) 管理的 `~/.mcptail/sessions/` JSONL 文件中，作为仪表盘展示和回放测试的单一数据源。

```mermaid
flowchart LR
  Client[客户端 / IDE] -->|stdio JSON-RPC| Proxy[mcptail 代理]
  Proxy -->|转发| Server[MCP 服务器]
  Proxy --> Store[(~/.mcptail/sessions/ JSONL)]
  Store --> UI[仪表盘 ui/src/app.tsx]
  Store --> Replay[回放 src/replay.ts]
  Replay --> Test[mcptail test]
```

## 仪表盘(UI)

仪表盘是一个独立的 React 应用，作为 mcptail 的可视化伴侣。挂载点由 [`ui/index.html`](https://github.com/Neal006/mcptail/blob/main/ui/index.html) 提供，入口脚本是 [`ui/src/main.tsx`](https://github.com/Neal006/mcptail/blob/main/ui/src/main.tsx)，它把 [`ui/src/app.tsx`](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx) 渲染到页面上。数据层封装在 [`ui/src/api.ts`](https://github.com/Neal006/mcptail/blob/main/ui/src/api.ts) 中，通过后端 HTTP 接口（[`src/server.ts`](https://github.com/Neal006/mcptail/blob/main/src/server.ts)）拉取会话列表、调用明细，订阅事件流。

主要交互区是“时间线（timeline）”表格，按方法名 / 工具名列出已记录的调用，并附带延迟与错误状态指示点。社区已经在追踪几条就近的可扩展性需求：

- **过滤与搜索**：在时间线上方添加子串匹配输入框和“仅错误”切换。资料来源：[`ui/src/app.tsx`](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx)（Issue #10）。
- **键盘导航**：使用 `j`/`k` 切换选中行、`Enter` 打开详情、`Esc` 关闭，并自动滚动到可视区。资料来源：[`ui/src/app.tsx`](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx)（Issue #15）。
- **浅色主题**：当前 [`ui/src/style.css`](https://github.com/Neal006/mcptail/blob/main/ui/src/style.css)（社区上下文引用）为暗色单一主题，规划 `prefers-color-scheme` + 手动切换并存到 `localStorage`（Issue #11）。
- **导出按钮**：`mcptail export` 系列导出在 UI 上会触发新的下载动作，例如 HAR 与回归测试 YAML（Issue #14、#20）。
- **会话对比**：选择两个会话进行方法+工具对齐的差异视图（Issue #21）。

由于仪表盘完全由会话文件驱动，多会话浏览、跨标签实时刷新等体验都建立在 [`src/store.ts`](https://github.com/Neal006/mcptail/blob/main/src/store.ts) 给出的读路径之上；这也意味着任何回放或对比工作都可以在 UI 中以纯函数（pure helper over two `correlate()` outputs）方式实现。资料来源：社区 Issue #21。

## 回放引擎

回放由 [`src/replay.ts`](https://github.com/Neal006/mcptail/blob/main/src/replay.ts) 提供，并通过 [`src/cli.ts`](https://github.com/Neal006/mcptail/blob/main/src/cli.ts) 注册的 `mcptail test <spec>` 命令暴露给 CI。其输入是一种 YAML 规范（server 命令、request、期望响应匹配器），由回放引擎驱动本地 MCP 服务器、把录制的请求重新发出、再用匹配器判定结果。这套引擎的存在让 mcptail 可以同时扮演“录制器”和“测试框架”。资料来源：[`src/replay.ts`](https://github.com/Neal006/mcptail/blob/main/src/replay.ts)。

社区提案指出，回放引擎是“导出为回归测试”功能的天然延伸：仪表盘上点“Export as test”即可生成对应的 YAML，规范可被 CI 直接消费（Issue #20）。这一方向使得 [`src/replay.ts`](https://github.com/Neal006/mcptail/blob/main/src/replay.ts) 同时承载调试回放与自动化测试两套使用场景。

## 可扩展性

mcptail 的可扩展面集中在三个边界，因此新增能力时改动面可被精确控制。

**1. 编辑器 / IDE 适配器**
适配器目录 [`src/adapters/`](https://github.com/Neal006/mcptail/blob/main/src/adapters/) 通过 [`src/adapters/index.ts`](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts) 集中注册，每一种客户端（如 `cursor.ts`、`windsurf.ts`）只负责读 / 写对应 IDE 的 MCP 配置文件。社区计划新增的 Windsurf 适配被明确定位为“以 `cursor.ts` 为模板，~15 行”的最小实现（Issue #6）。

**2. 导出器**
[`src/server.ts`](https://github.com/Neal006/mcptail/blob/main/src/server.ts) 已规划 `GET /api/export?file=...&format=har` 端点，映射 JSONL 调用为 HAR 条目（请求 / 响应作为 JSON 文本、延迟落入 `timings`），并有专用小型模块 `src/export.ts`；Issue #19 则提出基于现有 JSONL 批量导出 OTel span 的 `mcptail export --otlp <endpoint>` 路径，刻意避开代理热路径上的网络调用。

**3. 模型定价与回放断言**
[`src/pricing.json`](https://github.com/Neal006/mcptail/blob/main/src/pricing.json) 当前仅覆盖 Claude 模型。由于 MCP 负载会作为任意下游模型的输入上下文，社区提议按字母序补充 OpenAI、Gemini 的输入价格（Issue #9），让仪表盘上的成本估算跨模型一致。

## 维护性说明

会话文件可能无上限增长，社区已经记下两项护栏：超过容量上限后停止录制并向 stderr 输出一条警告（默认 ~50 MB，可由环境变量覆盖），在 [`src/store.ts`](https://github.com/Neal006/mcptail/blob/main/src/store.ts) 的 `SessionWriter` 中实现（Issue #13）；并提供 `mcptail clear` 与 `mcptail clear --older-than 7d` 清理过期会话（Issue #12）。这两项与导出器 / 适配器一同，构成 mcptail“degrade-to-pipe”哲学在长期运行场景下的延伸。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Neal006/mcptail

摘要：发现 30 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Export a captured call as a regression test。

## 1. 安装坑 · 来源证据：Export a captured call as a regression test

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Export a captured call as a regression test
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/20 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Session log rotation: cap per-session file size

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Session log rotation: cap per-session file size
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Neal006/mcptail | host_targets=mcp_host, claude, cursor, claude_code

## 4. 配置坑 · 失败模式：configuration: Adapter: Cline

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Adapter: Cline
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Adapter: Cline
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/8 | Adapter: Cline

## 5. 配置坑 · 失败模式：configuration: Adapter: Windsurf

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Adapter: Windsurf
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Adapter: Windsurf
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/6 | Adapter: Windsurf

## 6. 配置坑 · 失败模式：configuration: Adapter: Zed

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Adapter: Zed
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Adapter: Zed
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/7 | Adapter: Zed

## 7. 配置坑 · 失败模式：configuration: Streamable HTTP / SSE transport capture

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Streamable HTTP / SSE transport capture
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Streamable HTTP / SSE transport capture
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/18 | Streamable HTTP / SSE transport capture

## 8. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Neal006/mcptail | README/documentation is current enough for a first validation pass.

## 9. 运行坑 · 来源证据：UI: light theme

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：UI: light theme
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/11 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 运行坑 · 来源证据：UI: search / filter in the timeline

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：UI: search / filter in the timeline
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/10 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 维护坑 · 失败模式：migration: Add GPT and Gemini input prices to pricing.json

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Add GPT and Gemini input prices to pricing.json
- 对用户的影响：Developers may hit a documented source-backed failure mode: Add GPT and Gemini input prices to pricing.json
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/9 | Add GPT and Gemini input prices to pricing.json

## 12. 维护坑 · 失败模式：migration: Session diffing — compare two runs of the same server

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Session diffing — compare two runs of the same server
- 对用户的影响：Developers may hit a documented source-backed failure mode: Session diffing — compare two runs of the same server
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/21 | Session diffing — compare two runs of the same server

## 13. 维护坑 · 失败模式：migration: mcptail clear — prune recorded sessions

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: mcptail clear — prune recorded sessions
- 对用户的影响：Developers may hit a documented source-backed failure mode: mcptail clear — prune recorded sessions
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/12 | mcptail clear — prune recorded sessions

## 14. 维护坑 · 来源证据：Session diffing — compare two runs of the same server

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Session diffing — compare two runs of the same server
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/21 | 来源类型 github_issue 暴露的待验证使用条件。

## 15. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Neal006/mcptail | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Neal006/mcptail | no_demo; severity=medium

## 17. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Neal006/mcptail | no_demo; severity=medium

## 18. 安全/权限坑 · 来源证据：OpenTelemetry exporter

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OpenTelemetry exporter
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/19 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安全/权限坑 · 来源证据：Streamable HTTP / SSE transport capture

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Streamable HTTP / SSE transport capture
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Neal006/mcptail/issues/18 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 能力坑 · 失败模式：capability: Export a captured call as a regression test

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Export a captured call as a regression test
- 对用户的影响：Developers may hit a documented source-backed failure mode: Export a captured call as a regression test
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/20 | Export a captured call as a regression test

## 21. 能力坑 · 失败模式：capability: Session log rotation: cap per-session file size

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Session log rotation: cap per-session file size
- 对用户的影响：Developers may hit a documented source-backed failure mode: Session log rotation: cap per-session file size
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/13 | Session log rotation: cap per-session file size

## 22. 能力坑 · 失败模式：capability: UI: keyboard navigation (j/k + enter) in the timeline

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: UI: keyboard navigation (j/k + enter) in the timeline
- 对用户的影响：Developers may hit a documented source-backed failure mode: UI: keyboard navigation (j/k + enter) in the timeline
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/15 | UI: keyboard navigation (j/k + enter) in the timeline

## 23. 能力坑 · 失败模式：capability: UI: light theme

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: UI: light theme
- 对用户的影响：Developers may hit a documented source-backed failure mode: UI: light theme
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/11 | UI: light theme

## 24. 能力坑 · 失败模式：capability: UI: search / filter in the timeline

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: UI: search / filter in the timeline
- 对用户的影响：Developers may hit a documented source-backed failure mode: UI: search / filter in the timeline
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/10 | UI: search / filter in the timeline

## 25. 能力坑 · 失败模式：conceptual: README translation: हिन्दी (hi)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: README translation: हिन्दी (hi)
- 对用户的影响：Developers may hit a documented source-backed failure mode: README translation: हिन्दी (hi)
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/17 | README translation: हिन्दी (hi)

## 26. 能力坑 · 失败模式：conceptual: README translation: 中文 (zh-CN)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: README translation: 中文 (zh-CN)
- 对用户的影响：Developers may hit a documented source-backed failure mode: README translation: 中文 (zh-CN)
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/16 | README translation: 中文 (zh-CN)

## 27. 运行坑 · 失败模式：performance: Export a session as HAR

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: Export a session as HAR
- 对用户的影响：Developers may hit a documented source-backed failure mode: Export a session as HAR
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/14 | Export a session as HAR

## 28. 运行坑 · 失败模式：performance: OpenTelemetry exporter

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: OpenTelemetry exporter
- 对用户的影响：Developers may hit a documented source-backed failure mode: OpenTelemetry exporter
- 证据：failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/19 | OpenTelemetry exporter

## 29. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Neal006/mcptail | issue_or_pr_quality=unknown

## 30. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Neal006/mcptail | release_recency=unknown

<!-- canonical_name: Neal006/mcptail; human_manual_source: deepwiki_human_wiki -->