TRACE-MCP

_{适用于  ·  Claude Code  ·  Cursor  ·  Codex  ·  Windsurf  ·  Zed  ·  任何 MCP 客户端}

trace-mcp 会为 Agent 反复读取的内容建立索引，并直接提供答案。
审查拉取请求所需的输入 token 减少 72.7% — 数据取自我们并不拥有的开源仓库中 60 个已合并拉取请求的中位数。

_{我们会修改你也可以自行修改的配置。我们不会修补客户端二进制文件、拦截其流量或重写其文件。只有一项可拒绝的例外：Max 层级的 tweakcc 配套操作会为你运行第三方修补工具。}

npm install -g trace-mcp   # MCP server, no app
trace init                 # wire it into your agent, once per machine
trace add                  # index the repo you are in

审查一个拉取请求所需的输入 Token 减少了 72.7%——在 6 个非本项目仓库中合并的 60 个 PR 上取中位数，每个拉取请求从 13,595 降至 3,291。方法与复现 →

_{测量结果来自 2026 年 9 月 7 日的 trace-mcp 3.23.2（cb8ab30c）——这是该构建版本的结果，并非对当前版本的声明。测量目标、必须达到的标准以及最终结论：预注册。}

更便宜不等于更好，因此我们对同样的 60 个拉取请求各审查了两次，并进行了盲评。trace-mcp 组对其中 67% 的拉取请求正确理解了变更，而朴素文件加载组为 65%；每个 PR 的误报数分别为 0.80 和 0.58。基准测试的质量部分 →

_{桌面应用：基于 MCP 服务所提供的同一索引构建的 GPU 图谱浏览器。}

问题

AI Agent 会反复为已经完成的工作付费。每一轮中，Agent 都会重新读取相同的文件、重新遍历相同的依赖关系，还会把五步之前发现的结构再次塞进上下文窗口。这些重复工作占据了长时间会话中大部分的 Token 开销和延迟。

trace-mcp 会一次性为你的代码库构建一个感知框架的图谱，然后通过 MCP 提供服务，让 Agent 基于预计算的结构进行推理，而不是蛮力读取整个仓库。询问 “如果我修改这个模型，哪些部分会出问题？”——Agent 无需调用 80 次 Grep、读取 190 个文件，只需调用一次 get_change_impact，即可获得涵盖 PHP、Vue、迁移文件和 DI 的影响范围。支持 81 种语言的 91 种框架集成，以及 182 个工具。

真正的限制因素是重复计算，而不是模型能力：Token 费用、延迟和幻觉都会随着项目规模增长，而不是随着任务复杂度增长。trace-mcp 消除了重复计算的开销。图谱只需构建一次，并保持增量更新；任何 Agent 查询时都能获取图谱——因此，同一项工作不会被反复付费。

• 降低成本——平均而言以及在峰值情况下，每个成功答案所需的 Token 更少
• 降低延迟——顺序调用的工具更少，与模型的往返交互更少
• 提高准确性——上下文中的噪声更少，意味着幻觉更少，首次响应更准确
• 保障生产稳定性——上下文增长与任务复杂度相关，而不是与仓库规模相关

我们从代码智能入手，因为其中的重复工作代价最高；如今，同一引擎也将 Markdown 知识库（Obsidian、Logseq、纯 MD）作为同级领域进行索引。维基链接、标签、frontmatter 和嵌入内容都会成为图谱边和符号元数据；search、find_usages、get_change_impact 和 apply_rename 在两类领域中的工作方式完全相同。

trace-mcp 能为你做什么

在相近工具中少见的四项能力：

1. 感知框架的边 — trace-mcp 理解 Inertia::render('Users/Show') 会连接 PHP 和 Vue，@Injectable() 会创建 DI 依赖，$user->posts() 表示迁移文件中定义的 posts 表。支持 91 种框架集成。

2. 与代码关联的决策记忆 — 当你记录“选择 PostgreSQL 是为了支持 JSONB”时，这条记录会关联到 src/db/connection.ts::Pool#class。有人对该符号运行 get_change_impact 时，就能看到这项决策。MemPalace 将决策存储为文本；trace-mcp 则将它们与依赖图关联起来。

3. 跨会话智能 — 系统会从过往会话中提取决策并为其建立搜索索引。开始新会话时，get_wake_up 会用约 300 个 token 为你梳理情况；plan_turn 会展示与你的任务相关的过往决策；get_wake_up { scope: "resume" } 会从之前的会话中延续结构化上下文。

4. 代码和知识共用一张图 — 将 trace-mcp 指向一个 Markdown 知识库（Obsidian、Logseq 或纯 Markdown），同一引擎就会为其建立索引：每篇笔记成为一个 note:<basename> 符号，标题成为嵌套章节，[[wikilinks]] 和 ![[embeds]] 成为图的边，frontmatter 和 #tags 则作为元数据处理。PageRank、Signal Fusion 排序、嵌入和重命名重构都无需调整即可应用。Agent 无需学习第二种工具：它使用的是同一张图，其中同时包含代码库和笔记。

为什么 Agent 总是反复阅读

AI 编码 Agent 每轮都会重新计算相同的工作，而且在这个过程中无法感知框架。

它们先重新阅读 UserController.php，下一轮又读一遍。它们不知道 Inertia::render('Users/Show', $data) 会将 Laravel 控制器与 resources/js/Pages/Users/Show.vue 连接起来。它们不知道 $user->posts() 指的是三次迁移之前定义的 posts 表。它们无法追踪从 URL 到渲染像素的请求流程，因此每个会话中都会一遍又一遍地重新追踪。

结果是：单个任务中对热点文件反复读取 5–15 次，将上下文窗口当作临时数据库使用；而且项目越大，Agent 的成本就越高，而非能力越强。

解决方案

trace-mcp 会从源代码中构建跨语言依赖关系图，并通过 Model Context Protocol 将其开放出来——这是 Claude Code、Cursor、Windsurf 及其他 AI 编码 Agent 使用的插件格式。任何兼容 MCP 的 Agent 都能开箱即用地理解框架级信息。

桌面应用

trace-mcp 附带一个可选的 Electron 桌面应用（packages/app），以可视化界面呈现 MCP 服务所使用的同一份索引。它可以管理多个项目、连接 MCP 客户端，并提供 GPU 加速的图谱浏览器——无需打开终端。

项目与客户端。 菜单窗口会列出已编入索引的项目及其实时状态（Ready / 正在编制索引 / 出错），并提供重新编制索引和移除控件。MCP Clients 选项卡会检测已安装的客户端（Claude Code、Claw Code、Claude Desktop、Cursor、Windsurf、Continue、Junie、JetBrains AI、Codex、AMP、Warp、Factory Droid），并支持一键将 trace-mcp 接入其中，还可设置强制级别（Base / Standard / Max — 仅 CLAUDE.md、+ hooks、+ tweakcc 与 Agent 行为规则；Max 级功能仅适用于 Claude Code）。Warp 和 JetBrains AI 需要在 IDE 中手动粘贴配置，因为它们的配置存储只能通过 GUI 操作。

项目概览。 每个项目都会在独立的选项卡式窗口中打开，包含：Overview（文件、符号、边、覆盖率、已关联的服务、重新编制索引）、Ask（针对索引进行自然语言查询）和 Graph。概览还会显示 Most Symbols 文件、上次编制索引的时间戳以及依赖覆盖率仪表。

GPU 图谱浏览器。 Graph 选项卡通过 cosmos.gl 在 GPU 上渲染完整依赖关系图——数万个节点和边也能以交互式帧率呈现。可按 Files / Symbols 筛选、叠加检测到的社群、突出显示组、切换标签/FPS 显示，并逐步调整图谱深度。在深入使用工具前，它有助于了解代码耦合、热点，以及代码库的实际结构。

**在 Windows 上安装：**从 Releases 运行 trace-mcp.Setup.<version>.exe。

**应用内更新卡在旧版本？**macOS/Windows 上 3.10.0 及更早版本的应用无法自行更新 — “Check for updates…”会显示 Cannot set properties of undefined (setting 'autoDownload')，然后没有任何反应。这个问题已在 3.11.0 中修复，但受影响的版本无法通过自身更新来解决。请手动重新安装：下载 .dmg（macOS），或从 Releases 下载最新的 trace-mcp.Setup.<version>.exe（Windows）— 或者，如果已安装 CLI，请运行 trace-mcp install-app。

此应用与 MCP 客户端使用同一个 trace-mcp 守护进程（http://127.0.0.1:3741）通信，因此你在应用中索引的任何内容都能立即供 Claude Code / Cursor / 等使用。如果你只需要 MCP 服务和 CLI，则完全不需要此应用 — npm install -g trace-mcp 就是完整的安装方式。

trace-mcp 的对比

trace-mcp 在一个工具中整合了代码图导航、跨会话记忆和实时代码理解。大多数同类项目只解决其中一项 — trace-mcp 将三者融为一体，并且是唯一支持框架感知的跨语言边（91 种框架集成）和与代码关联的决策记忆的工具。

• 与高效利用令牌的探索工具相比（Repomix、jCodeMunch、cymbal）— trace-mcp 在符号查找的基础上增加了框架边、重构、安全性和子项目支持。
• 与会话记忆工具相比（MemPalace、claude-mem、ConPort）— trace-mcp 将决策关联到特定符号/文件，因此这些决策会自动显示在影响分析中。
• 与 RAG / 文档生成工具相比（DeepContext、smart-coding-mcp）— trace-mcp 回答的是“展示执行路径、依赖项和测试”，而不是“查找与此查询相似的代码”。
• 与代码图 MCP 服务相比（Serena、Roam-Code）— trace-mcp 的语言覆盖范围最广（81 种语言），并且是唯一支持跨语言框架边的工具。

GitHub 星标数、语言和各项能力覆盖范围的完整对照表：trace-mcp 与其他代码智能 MCP 服务对比。

正面对比：与 Repomix 对比 · 与 Serena 对比 · 与 codegraph 对比 · 与 codebase-memory-mcp 对比 · 与 Claude Code context mode 对比 · 与 code-review-graph 对比 · Repomix 与 codegraph 对比。

令牌缩减 — 我们测量了什么

AI Agent 会耗费令牌，重新计算上一轮已经发现的内容 — 重新读取文件、重新遍历依赖项、重新扩充上下文。trace-mcp 通过精准上下文取而代之：仅提供与查询相关的符号、边和签名，并从只计算一次的图中返回这些内容。 从不属于我们的那项测量开始。 本节其他所有数据，都是 trace-mcp 在自己的代码仓库上测得的——第一行表格基于真实响应，其余数据则来自 trace-mcp 自己的合成估算。PR 评审上下文基准是个例外：为六个开源仓库中 60 个已合并的拉取请求整理评审上下文——hono、axios、express、requests、flask、got——中位输入 token 数为 3,291，而加载差异及其涉及的所有文件需要 13,595，减少了 72.7%；此数据由 gpt-tokenizer 计数，而非估算。基准数据集中的基础和头部 SHA 固定记录在 benchmarks/pr-context/dataset.json 中，运行 npx tsx scripts/bench-pr-context.ts 即可重测。未能从索引中获益的 56 个拉取请求也与有效案例一并发布：其中 13 个比直接读取文件耗费更多 token，另有 42 个因捆绑包的 token 预算不足，未能提供每个变更符号的正文；直到本次运行开始评估实际交付内容，而非仅统计列出的内容，基准才发现这一不足。

预期效果——按工作负载划分：

67.4% 是值得据此规划的真实数字，而它发生变化并非因为产品变快了。 我们过去会印上“平均约减少 40–50%”。这个数字源自一个在工具运行前就给每次调用打分的计数器——RAW_COST_ESTIMATES[tool] × 0.15，这是一个没有方差的常数。我们在#915中发现并修复了这个问题。随着覆盖率扩大到已记录调用的 97.2%，更真实的替代数字先后变为 29.3%、21.1% 和 21.0%。随后我们发现，占权重 76% 的三个工具都只根据一个样本定价；而四种合理的样本选择方法，对同一构建的测算结果分别为 21.0%、30.7%、56.0% 和 67.4%。因此，现在会先生成、冻结并提交抽样框架，再运行使用该框架的测量；所有关于框架构建方式的说法也都会在 CI 中对照代码仓库重新核验（预注册）。67.4% 是注册框架测得的结果；应将从 21% 到 67.4% 的跃升理解为框架变了，而非产品变了。此结果将真实响应的 o200k_base token 计数按单台机器记录的 18,329 次调用加权（各工具明细表，由此生成 docs/_data/response_tokens.json）。此数字附带三项注意事项：基准的另一半——Read／Grep 原本会耗费多少 token——仍是手写估算；测量的 23 个工具中有 4 个返回的 token 比它们替代的更多，旧计数器却仍将其记为节省；另有两个工具（register_edit、reindex）根本不替代任何文件读取，因此现在将其节省计为零，并列为开销——将其纳入支出后，整体降幅为 66.5%。下文所述峰值（单次结构化调用最多减少 99%）是按调用而非按会话计算的合成估算。 于 2026 年 9 月 21 日在 trace-mcp 3.31.0（76996eb9）上测得。其预注册将其公布为我们在测量前声明的 25% 门槛的首个通过结果；同时也明确指出，这次通过源于注册抽样框，而非推出更快的产品。运行前写下的预测给出了一个区间，实际结果高于该区间；预测错了，仍会保留在此。

Benchmark Lab——由应用提出同一个问题。 桌面应用的 Benchmark Lab 选项卡会运行一组固定的 8 个回忆测试样例，覆盖 3 种方案，并将每次运行保存到 ~/.trace/benchmark-runs。于 2026 年 9 月 26 日在 trace-mcp 3.33.0（4e1ac4fd）上测得：读取文件的对照组通过 13 次调用消耗了 82,412 个 token（8/8 答对）；最简方案用 512 个 token 答对 8 题中的 7 题（−99.4%）；标准方案用 13,657 个 token 答对全部 8 题（−83.4%）。最简方案的漏答是真实测量结果——原始 search_text 未能将 src/indexer/pipeline.ts 排入前 10 名——我们将其如实公布，而不是不断重跑直到通过。方法、测试集哈希与重跑 →

基准测试：trace-mcp 自身代码库（694 个文件、3,831 个符号 → v1.30 中的 929 个文件、5,197 个符号）：

Task                    Without trace-mcp    With trace-mcp    Reduction
───────────────────────────────────────────────────────────────────────────
Symbol lookup                42,518 tokens       1,162 tokens       97.3%
File exploration             27,486 tokens         855 tokens       96.9%
Search                       22,860 tokens       8,000 tokens       65.0%
Find usages                  11,430 tokens       1,720 tokens       85.0%
Context bundle               12,847 tokens       3,485 tokens       72.9%
Batch overhead               16,831 tokens       8,299 tokens       50.7%
Impact analysis              49,141 tokens       1,856 tokens       96.2%
Call graph                  178,345 tokens       9,285 tokens       94.8%
Type hierarchy               94,762 tokens         855 tokens       99.1%
Tests for                    22,590 tokens       1,150 tokens       94.9%
Composite task              223,721 tokens      14,245 tokens       93.6%
───────────────────────────────────────────────────────────────────────────
Total                       702,532 tokens      50,812 tokens       92.8%

在 11 类结构化任务中，当 Agent 复用图而非重新读取文件时，每次调用的重复计算最多可减少约 99%。这应理解为在支持良好的 TS/Vue 代码库上，结构化任务的峰值结果，而不是你在每个项目上都能达到的数值。在生产环境的混合工作负载中，应预期67.4%——这是上文测得的数据，而非这个合成数据。上下文中的噪声减少，也意味着幻觉更少、首次响应准确率更高；这种质量收益无法从 token 数量中体现出来。

节省量随项目规模增长——这是论点，并非测量结果。没有 trace-mcp 时，Agent 会在找到正确文件前读取更多错误文件；而图遍历的复杂度保持为 O(相关边)，而非 O(总文件数)。我们没有可用于支撑这一点的项目规模测量数据，因此本 README 不再引用相关数值；此前列在此处的单次会话 token 数，与“40–50%”一样，来自 #915 前使用的同一估算器。

复合任务带来最大的收益。 一次 get_task_context 调用即可替代一串约 10 次的顺序操作（search → get_symbol × 5 → Read × 3 → Grep × 2）。这意味着一次往返，而非十次，也是大部分延迟节省的来源。

自行运行

npx trace-mcp benchmark .

约 5 分钟即可了解针对你实际代码仓库的各类别 Token 节省情况——无需安装、无需注册，所有操作均在本地完成。它会读取现有索引；如果项目尚未注册，请先运行 trace-mcp index .。上方数据来自 trace-mcp 自身的 TypeScript/Vue 代码库（929 个文件、5,197 个符号），并基于结构化基准测试；混合工作负载下的生产环境缩减幅度较低（实测为 67.4%，见上文），但各任务的规律适用于所有支持良好的技术栈。

这是合成估算值，并非实测节省量：“不使用 trace-mcp”一侧根据索引中的文件大小计算，“使用 trace-mcp”一侧则根据各场景的乘数计算，而非基于实际工具调用。它展示的是理论上限。若要衡量你实际使用时的节省量，请先运行 trace-mcp 一段时间，然后：

trace-mcp analytics savings   # real sessions: reads vs. what trace-mcp would have cost
trace-mcp analytics optimize  # recommendations based on your actual usage

详情请参阅会话分析与 Token 节省跟踪。

# Via CLI (no install)
npx trace-mcp benchmark /path/to/project

# Or via MCP tool
benchmark_project  # runs against the current project

核心功能

• 请求流追踪 — 跨后端框架追踪 URL → 路由 → 中间件 → 控制器 → 服务
• 组件树 — 展示包含 props / emits / slots 的渲染层级（Vue、React、Blade）
• 从迁移文件生成架构 — 无需连接数据库
• 事件链 — 事件 → 监听器 → Job 扇出（Laravel、Django、NestJS、Celery、Socket.io）
• 变更影响分析 — 跨语言反向遍历依赖关系，并结合关联的架构决策进行增强
• 图感知任务上下文 — 描述开发任务 → 获取最优代码子图（执行路径、测试、类型）以及相关的历史决策，并根据 bug 修复 / 功能开发 / 重构意图进行调整
• 调用图与 DI 树 — 双向调用图，具备 4 级解析置信度；可选用 LSP 增强，实现编译器级精度；支持 NestJS 依赖注入
• ORM 模型上下文 — 支持 7 种 ORM 的关系、架构和元数据
• 死代码与测试缺口检测 — 查找未测试的导出项 / 符号（分类为“unreached”与“imported_not_called”）、死代码，并在影响分析中逐个符号展示测试覆盖情况
• 安全扫描 — 扫描 OWASP Top-10 模式并进行污点分析（source→sink 数据流）。可导出 MCP 服务安全上下文，供 skill-scan 使用
• 语义搜索，默认离线 — 内置 ONNX 嵌入模型，开箱即用，无需 API 密钥；切换到 Ollama/OpenAI，即可使用大模型驱动的摘要生成
• 决策记忆 — 从会话中提取决策，将其关联到符号 / 文件，并在影响分析中自动呈现
• 多服务子项目 — 通过 API 契约关联跨服务图；支持跨服务影响分析和限定服务范围的决策
• CI/PR 变更影响报告 — 在每个 PR 中自动分析影响范围、评估风险、检测测试缺口和架构违规

支持的技术栈

语言： PHP、TypeScript、JavaScript、Python、Go、Java、Kotlin、Ruby、Rust、C、C++、C#、Swift、Objective-C、Objective-C++、Dart、Scala、Groovy、Elixir、Erlang、Haskell、Gleam、Bash、Lua、Perl、GDScript、R、Julia、Nix、SQL、PL/SQL、HCL/Terraform、Protocol Buffers、GraphQL、Prisma、Vue SFC、HTML、CSS/SCSS/SASS/LESS、XML/XUL/XSD、YAML、JSON、TOML、Assembly、Fortran、AutoHotkey、Verse、AL、Blade、EJS、Zig、OCaml、Clojure、F#、Elm、CUDA、COBOL、Verilog/SystemVerilog、GLSL、Meson、Vim Script、Common Lisp、Emacs Lisp、Dockerfile、Makefile、CMake、INI、Svelte、Astro、Markdown、MATLAB、Lean 4、FORM、Magma、Wolfram/Mathematica、Ada、Apex、D、Nim、Pascal、PowerShell、Solidity、Tcl

框架： Laravel（+ Livewire、Nova、Filament、Pennant）、Django（+ DRF）、FastAPI、Flask、Express、NestJS、Fastify、Hono、Next.js、Nuxt、Rails、Spring、tRPC

ORM： Eloquent、Prisma、TypeORM、Drizzle、Sequelize、Mongoose、SQLAlchemy

前端： Vue、React、React Native、Blade、Inertia、shadcn/ui、Nuxt UI、MUI、Ant Design、Headless UI

其他： GraphQL、Socket.io、Celery、Zustand、Pydantic、Zod、n8n、React Query/SWR、Playwright/Cypress/Jest/Vitest/Mocha

知识库： Obsidian、Logseq、纯 Markdown — [[wikilinks]]、![[embeds]]、[text](path.md)、frontmatter（YAML）、#tags、ATX 标题。每条笔记都会成为一个 note:<basename> 符号，章节嵌套在其中；wikilinks 会解析为笔记之间的 references / embeds 边。可在同一项目中混合知识库和代码 — 将 root 指向同时包含两者的目录，即可对它们执行一次 find_usages。

完整详情：支持的框架 · 全部工具

快速开始

先看看你的浪费——5 分钟，无需设置或注册：

npx trace-mcp benchmark .

为项目建立索引，运行 11 项结构化任务基准测试（符号查找、影响分析、调用图、类型层次结构等），并输出每项任务的预估令牌成本——对比有无 trace。你会清楚看到 Agent 在哪些地方重复计算了本可以复用的工作。这是根据你的索引计算得出的模拟估算，并非真实工具调用记录（请参阅上文“令牌减少”下的“方法”部分）；若要查看你自己会话中经测量得出的节省情况，请使用 trace-mcp analytics savings。

然后将其接入你的 AI Agent：

npm install -g trace-mcp
trace init        # one-time global setup (MCP clients, hooks, CLAUDE.md)
trace add         # register current project for indexing

• init — 配置你的 MCP 客户端（Claude Code、Cursor、Windsurf、Claude Desktop 等），安装防护钩子，并将路由规则添加到 ~/.claude/CLAUDE.md。
• add — 检测框架，创建项目索引并注册项目。在每个你希望 trace 理解的项目中重新运行此命令。

（npm 包仍名为 trace-mcp——只是安装的命令缩短了。trace-mcp init、trace-mcp add 和其他所有 trace-mcp … 调用仍可正常使用。）

所有状态都存储在 ~/.trace/ 中（并会自动回退到 ~/.trace-mcp/）——除非你选择使用 .traceignore 或 .trace/.config.json，否则项目目录会保持整洁。

使用 Claude Code 或 Codex CLI？ 运行 npm install -g trace-mcp 后，可以跳过 trace init 中的客户端接入步骤，直接安装插件——无论哪种方式都不需要 git clone：

# Claude Code
claude plugin install @nikolai-vysotskyi/trace-mcp

# Codex CLI
codex plugin marketplace add nikolai-vysotskyi/trace-mcp
codex plugin install trace-mcp@nikolai-vysotskyi-trace-mcp

两者都会通过一个步骤注册 trace-mcp MCP 服务和 Bash 防护钩子。详情见： .claude-plugin/README.md · .codex-plugin/README.md。

然后在你的 MCP 客户端中：

> get_project_map to see what frameworks are detected
> get_task_context("fix the login bug") to get full execution context for a task
> get_change_impact on app/Models/User.php to see what depends on it

为 Markdown 知识库（Obsidian / Logseq / 纯 Markdown）建立索引。 将知识库根目录指定给 trace add——默认会收录 .md/.mdx/.markdown 文件。每篇笔记都会成为一个 note:<basename> 符号，标题会嵌套为章节，[[wikilinks]] 和 ![[embeds]] 会解析为图边，frontmatter 中的 aliases: 会让别名也能被解析，#tags 则会聚合，因此只需一次 find_usages，就能找到每篇带有 #sgr 的笔记。

> find_usages on note:my-concept     // backlinks across the vault
> find_usages on tag:sgr             // every note tagged #sgr
> get_change_impact on note:legacy   // what breaks if I rename or delete it
> search "schema-guided reasoning"   // PageRank + embeddings over the vault

更喜欢图形界面？桌面应用可处理安装、建立索引、接入 MCP 客户端和重新建立索引，无需使用终端。

深入了解：添加更多项目 / 升级 / 手动设置 · stdio 与 HTTP 设置（按仓库或团队） · 语义搜索（本地 ONNX） · 建立索引与文件监视器 · .traceignore。

从 trace-mcp 迁移到 trace

项目仍叫 trace-mcp。现在的命令是 trace。 重命名仅限于这一处，其他地方均不变——npm 包、此仓库、域名和注册表条目都仍保留 trace-mcp 这个名称。这样做是为了使用方便，类似于 ripgrep 使用 rg，或 kubernetes 使用 kubectl，而不是为了节省令牌：缩短 MCP 工具前缀带来的节省虽确实存在，但幅度很小，具体取决于分词器和预设，每轮可节省 66–366 个令牌；对于本身就需要 8k–45k 个令牌的工具列表而言，仅占 0.74–1.23%。

npm 包名不会更改。 它仍是 trace-mcp，并且永远如此——npm 上的 trace 是另一位作者发布的无关包。请使用 npm install -g trace-mcp 或 npx -y trace-mcp@latest 进行安装。

以下是会更改和保持不变的内容：

• 命令名称 — 新的写法是 trace <cmd>。trace-mcp <cmd> 将永久保留为别名——在 macOS 上，/usr/bin/trace 是 Apple 自带的 trace(1)，因此在脚本、CI 或任何你无法自行控制的 PATH 中，请继续使用 trace-mcp。
• MCP 客户端条目 — trace init 和 trace upgrade 会将现有的 mcpServers["trace-mcp"] 条目重命名为 mcpServers["trace"]，并将其指向新命令。不会删除任何内容；保留为 trace-mcp 的条目仍可正常工作，只是会消耗更多令牌。
• 状态目录 — 使用 ~/.trace/；如果旧目录存在而新目录不存在，则回退到 ~/.trace-mcp/。不会重建索引。
• 项目配置 — 优先读取 .trace.json，然后读取 .trace-mcp.json。现有文件保留原位置，仍可正常工作。
• 插件和注册表标识符 — 保持不变：Claude Code 插件使用 @nikolai-vysotskyi/trace-mcp，MCP 注册表中使用 io.github.nikolai-vysotskyi/trace-mcp。

有一件事 init 无法替你完成。 MCP 工具前缀也会更改——mcp__trace-mcp__search 会变成 mcp__trace__search。init 会迁移它管理的 mcpServers 条目，但不会修改你自行编写的文本：Claude Code 权限允许列表、钩子匹配器，或你在 CLAUDE.md/AGENTS.md 文本中自行添加的 mcp__trace-mcp__* 提及。如果升级后钩子不再匹配，或允许列表中的工具开始重新请求授权，请在自己的配置中搜索 mcp__trace-mcp__，并将其替换为 mcp__trace__。以上其他更改都会在你下次运行 trace init 或 trace upgrade 时自动完成——详情请参阅：配置。

本地优先的设计理念

trace-mcp 完全在你的机器上运行。你的源代码不会被上传，也无需创建账户。

• 索引在本地构建。 MCP 服务是由你自行运行的 Node 进程——通过 stdio 或 http://127.0.0.1:3741 运行。
• 索引存放在 ~/.trace/ 中（如果你已有 ~/.trace-mcp/，则使用该目录），绝不会放在项目中，也绝不会被上传。除非你选择使用 .traceignore 或 .trace/.config.json，否则仓库目录会保持干净。
• 语义搜索默认离线运行——使用内置的 ONNX 嵌入模型，无需 API 密钥，也不会发起外部请求。你可以通过配置切换为 Ollama（本地）或 OpenAI（选择启用）。
• 不会收集与你的代码、查询或使用情况相关的遥测数据。 唯一会离开你机器的内容如下文和隐私页面所述——不会有其他内容回传。
• AI 客户端看到的内容由你的 AI 客户端决定。 trace-mcp 会通过 MCP 返回图结果；Claude Code / Cursor / Codex / Windsurf 如何将这些结果转发给模型，取决于该客户端的隐私模型。
• 守护进程只信任回环地址。 serve-http 按设计无需身份验证：来自 127.0.0.1 的调用者就是你。因此，除非你传入 --allow-remote 并在端口前配置自己的身份验证，否则会拒绝非回环地址的 --host——请参阅配置。
• **要清除所有内容，**删除 ~/.trace/（尚未迁移的安装则删除 ~/.trace-mcp/）——该目录就是全部数据。

使用情况遥测

trace-mcp 每个安装每天最多发送一次匿名 ping，以便我们统计活跃安装数：版本、操作系统、MCP 客户端和汇总计数。不包含代码、路径、IP 地址，也没有任何每安装标识符，除了在你机器上本地生成的 UUID。CI 环境中会禁用此功能；其 GA4 凭据以明文形式包含在已发布的程序包中，方便你验证 ping 的发送目标。

设置 TRACE_MCP_TELEMETRY=off，或在 ~/.trace/.config.json 中设置 "telemetry": { "usage_ping": false }，即可关闭此功能。

完整字段列表、两种关闭方式以及删除本地状态的方法，请参阅隐私页面。源文件：src/telemetry/usage-ping.ts。

对于安全敏感环境，请在使用前查看 SECURITY.md。

充分发挥 trace-mcp 的作用

trace-mcp 通过三个层级，让 AI Agent 使用其工具，而不是直接读取原始文件：

第 1 级：自动（开箱即用）

MCP 服务会提供指令和包含路由提示的工具描述，告知 AI Agent 何时应优先使用 trace-mcp，而不是原生的 Read/Grep/Glob。此功能适用于任何兼容 MCP 的客户端——无需配置。

第 2 级：CLAUDE.md（推荐）

trace-mcp init 会在 ~/.claude/CLAUDE.md（或项目的 CLAUDE.md）中添加一个 Code Navigation Policy 区块，告知 Agent 针对每类任务应优先使用哪个 trace-mcp 工具，而不是 Read/Grep/Glob。如果你跳过了 init，请参阅系统提示词路由，查看完整区块以及如何调整强制执行设置。

第 3 级：钩子强制执行（仅限 Claude Code）

要强制执行，trace-mcp init 会安装一个 PreToolUse 守卫钩子，阻止对源文件使用 Read/Grep/Glob，并将 Agent 重定向到 trace-mcp 工具（非代码文件、编辑前读取和安全的 Bash 命令则会正常通过）。使用 trace-mcp setup-hooks --global / --uninstall 手动管理。详情请参阅：系统提示词路由。

Level 4：Max 层级 — 系统提示词改写 + Agent 行为规则

在 trace-mcp init 期间选择 Max（默认选项），会额外叠加两种增强措施：

• tweakcc 系统提示词改写会修改 Claude Code 的核心工具描述，让模型从一开始就将“使用 trace-mcp search”内化为默认做法，而不是“使用 Grep”。仅适用于 Claude Code。
• **agent_behavior: "strict"**通过 MCP 指令提供一套精简的行为规范——不阿谀奉承、对错误前提提出异议、绝不捏造、以目标为导向执行、两次违规后保持会话纪律、不顺手重构。适用于多个客户端（Claude Code、Cursor、Codex、Windsurf），并会在 npm upgrade trace-mcp 后自动更新，无需重新运行 init。

此设置可让每位队友的 Agent 都遵守相同的行为规范，无需任何人进行配置。通过 ~/.trace/.config.json 中的 tools.agent_behavior 调整或禁用此设置——请参阅工具开放与 Agent 行为。

决策记忆

AI Agent 对话中的决策、权衡和发现通常会在会话结束后消失。trace-mcp 会捕获这些内容，并将每项决策与相关代码关联起来——因此，之后有人对 src/db/connection.ts::Pool#class 运行 get_change_impact 时，“我们选择 PostgreSQL 是为了使用 JSONB”这一决策会自动显示出来。

• 挖掘——mine_sessions 扫描 Claude Code / Claw Code JSONL 日志，并通过模式匹配提取决策（不调用 LLM）。类型包括：架构、技术选型、Bug 根因、权衡、约定。
• 关联——每项决策都会关联到一个符号或文件；支持针对子项目的服务级决策。
• 呈现——决策会自动补充到 get_change_impact、plan_turn 和 get_wake_up 的结果中。时间有效性（valid_from/valid_until）使“2025-01-15 当时的情况是什么？”这类查询成为可能。
• 搜索——使用 query_decisions（FTS5 + 筛选条件）搜索决策；使用 search_sessions 搜索所有过往会话中的原始对话内容。

trace memory mine                           # extract decisions from sessions
trace memory search "GraphQL migration"     # search past conversations
trace memory timeline --file src/auth.ts    # decision history for a file

完整工具列表、CLI、时间有效性、服务范围：请参阅决策记忆。

子项目

子项目是项目生态系统中的任何代码仓库——微服务、前端、共享库、CLI 工具。trace 会关联不同子项目之间的依赖图：如果服务 A 调用了服务 B 中的某个端点，那么更改服务 B 中的该端点时，系统会将其显示为对服务 A 的破坏性变更。

子项目会自动发现。每次索引时，trace 都会检测子项目（Docker Compose、扁平或分组工作区、单体仓库回退模式），解析 API 契约（OpenAPI、GraphQL SDL、Protobuf/gRPC），扫描代码中的 HTTP 客户端调用（fetch、axios、Http::、requests、http.Get、gRPC 存根、GraphQL 操作），并将调用关联到已知端点。

cd ~/projects/my-app && trace add
# → auto-detects user-service (openapi.yaml) and order-service
# → links order-service → user-service via /api/users/{id}

trace subproject impact --endpoint=/api/users
# → [order-service] src/services/user-client.ts:42 (axios, confidence: 85%)

可以使用 trace subproject add --repo=... --project=... 手动添加外部子项目。MCP 工具：get_subproject_graph、get_subproject_impact、get_subproject_clients、subproject_add_repo、subproject_sync。

完整 CLI、检测模式、MCP 工具参考、拓扑配置：请参阅配置 — 拓扑与子项目。

CI/PR 变更影响报告

trace ci-report --base main --head HEAD 会为每个拉取请求生成 Markdown 或 JSON 报告，内容包括：摘要、影响范围（深度为 2 的反向依赖遍历）、测试覆盖缺口（每个符号的 hasTestReach）、风险分析（复杂度占 30% + 变更频率占 25% + 耦合度占 25% + 影响范围占 20%）、架构违规（自动检测 clean / hexagonal 预设），以及新增的无用导出。

使用 --fail-on high 可阻止合并高风险变更。请参阅 .github/workflows/ci.yml，了解可直接使用的 GitHub Action。它会运行 build → test → impact-report，并在每次推送时发布一条固定的 PR 评论。

试点计划 — 面向在生产环境中运行大模型的团队

如果你正在生产环境中交付 AI 功能——内部副驾驶、面向客户的助手、基于代码库或知识库的 RAG——并且遇到了成本、延迟或质量瓶颈，我们可以与你开展一次有针对性的试点。

形式： 2–4 周。尽量减少集成工作。选取一到两个真实的生产用例，而不是演示。

我们衡量的指标（前后对比）：

• 每个成功回答消耗的令牌数
• 首次响应准确率（无需重试即可解决的查询占比）
• 重试次数和回退调用次数
• 端到端延迟
• 固定评估集上的用户成功率

你将获得： 一份清晰的前后对比报告，说明上下文优化是否改善了对你的技术栈真正重要的指标；并提供一条可靠扩大使用规模的路径，让你无需因成本而限制使用。

我们的目标是打造一个使用量增长时依然表现可预测的系统，而非一次性降低成本：团队通常希望先实现可靠的生产运行，再扩大大模型的应用范围。

联系我们： 在 github.com/nikolai-vysotskyi/trace-mcp/issues 提交一个标记为 pilot 的议题，或联系 @nikolai-vysotskyi。

工作原理

Source files (PHP, TS, Vue, Python, Go, Java, Kotlin, Ruby, HTML, CSS, Blade)
    │
    ▼
┌──────────────────────────────────────────┐
│  Pass 1 — Per-file extraction            │
│  tree-sitter → symbols                   │
│  integration plugins → routes,           │
│    components, migrations, events,       │
│    models, schemas, variants, tests      │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Pass 2 — Cross-file resolution          │
│  PSR-4 · ES modules · Python modules    │
│  Vue components · Inertia bridge         │
│  Blade inheritance · ORM relations       │
│  → unified directed edge graph           │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Pass 3 — LSP enrichment (opt-in)       │
│  tsserver · pyright · gopls ·           │
│  rust-analyzer → compiler-grade         │
│  call resolution, 4-tier confidence     │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  SQLite (WAL mode) + FTS5               │
│  nodes · edges · symbols · routes       │
│  + embeddings (local ONNX by default)   │
│  + optional: LLM summaries              │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Decision Memory (decisions.db)         │
│  decisions · session chunks · FTS5      │
│  temporal validity · code linkage       │
│  auto-mined from session logs           │
└────────────────────┬─────────────────────┘
                     │
                     ▼
          MCP server (stdio or HTTP/SSE)
          182 tools · 10 resources

默认采用增量处理 — 文件会进行内容哈希；重新索引时会跳过未更改的文件。

插件架构 — 语言插件（符号提取）和集成插件（语义边）会根据项目检测结果加载，并按类别组织：框架、ORM、视图、API、验证、状态、实时、测试、工具链。

详情：架构与插件系统 — 索引工作原理

文档

完整文档位于 trace-mcp.com（与此仓库中的 docs/ 内容相同）。

Star History

Project health

License

MIT

Built by Nikolai Vysotskyi