Doramagic.ai
English

Doramagic 项目包 · 项目说明书

mcptail 项目

看清你的 AI agent 实际在做什么：面向 MCP 服务器的被动流量抓取、token 成本统计与请求回放，一条命令即可启动。

项目概述与系统架构

mcptail 是一个面向 MCP（Model Context Protocol）服务器的记录-回放（record-and-replay）调试与观测工具。它以本地代理的形式插入到 IDE 客户端（如 Cursor、Windsurf）与 stdio MCP 服务器之间，逐字透传 JSON-RPC 流量，同时把每一次关联调用以 JSONL 格式落盘到 ~/.mcptail/se...

章节 相关页面

继续阅读本节完整说明和来源证据。

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.tsJSONL 顺序写入、按大小轮转、提供查询与清理 API 资料来源：src/store.ts:40-120
导出src/export.ts会话到 HAR 等外部格式的映射 资料来源：src/export.ts:1-40
前端 UIui/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
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。

来源：https://github.com/Neal006/mcptail / 项目说明书

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 帧边界与 JSON-RPC 解码

继续阅读本节完整说明和来源证据。

章节 请求-响应配对

继续阅读本节完整说明和来源证据。

章节 Taps 与客户端配置改写

继续阅读本节完整说明和来源证据。

概述与设计目标

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

来源：https://github.com/Neal006/mcptail / 项目说明书

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Claude Code

继续阅读本节完整说明和来源证据。

章节 Cursor

继续阅读本节完整说明和来源证据。

章节 VS Code

继续阅读本节完整说明和来源证据。

概览与设计目标

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) 即按此模式扩展：在 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 推荐的扩展方式。资料来源：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）：清理 ~/.mcptail/sessions/ 中累积的会话，支持时间过滤并打印"removed N sessions, X MB"摘要；
  • mcptail replay <session> 与 mcptail test <spec.yaml>（issue #20）：分别驱动 src/replay.ts 与新提议的 YAML 规范，实现记录-回放与回归测试；
  • mcptail export --otlp <endpoint>（issue #19）：批量把 JSONL 会话导出为 OpenTelemetry span，不在代理热路径上引入网络开销。

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

扩展指南

新增一个客户端支持（按 issue #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。

来源：https://github.com/Neal006/mcptail / 项目说明书

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

mcptail 是一个面向 MCP（Model Context Protocol）服务器的本地代理与诊断工具，整体由三层组成：CLI 入口（src/cli.ts）、本地 HTTP 服务与回放引擎（src/server.ts、src/replay.ts）、以及与之配套的浏览器仪表盘（ui/）。代理把 stdio MCP 服务器的 JSON-RPC 流量透传给下游客户端，同时把...

章节 相关页面

继续阅读本节完整说明和来源证据。

系统总览

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

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 提供，入口脚本是 ui/src/main.tsx，它把 ui/src/app.tsx 渲染到页面上。数据层封装在 ui/src/api.ts 中，通过后端 HTTP 接口（src/server.ts）拉取会话列表、调用明细，订阅事件流。

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

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

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

回放引擎

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

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

可扩展性

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

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

2. 导出器 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 当前仅覆盖 Claude 模型。由于 MCP 负载会作为任意下游模型的输入上下文，社区提议按字母序补充 OpenAI、Gemini 的输入价格（Issue #9），让仪表盘上的成本估算跨模型一致。

维护性说明

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

来源：https://github.com/Neal006/mcptail / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 来源证据：Export a captured call as a regression test

可能增加新用户试用和生产接入成本。

medium 来源证据：Session log rotation: cap per-session file size

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 失败模式：configuration: Adapter: Cline

Developers may misconfigure credentials, environment, or host setup: Adapter: Cline

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录