CodeCanvas MCP

在花费成千上万个 token 逐文件阅读之前，先理解一个陌生的 Python 系统。

CodeCanvas 是一个运行在本地的静态分析 Model Context Protocol 服务器，面向 Python。它能把整个项目范围的调用路径和控制流转化为关于分支、调用方、被调用方、副作用和变更影响的紧凑、可引用的答案。

当前基准测试覆盖了固定版本的 Google ADK、LangGraph 和 FastAPI。在 Apple M4 Pro 上，实测冷分析时间范围为 4.38s 到 61.62s，暖启动 find_symbols 的中位延迟在 48.264ms 至 293.778ms 之间（覆盖上述仓库）。在一组受控的 54 会话 agent 测试中，两种条件都保留了相同的内置代码搜索工具；实验组只额外增加了 logic_flow。仅这一个新增工具，在三次成对重复中即使用了中位数 22.95% 更少的总 token，体现出了在常规代码探索之外的显著增量价值。未缓存 token 增加了 0.78%，回答结果尚未进行盲评。参见 方法论、完整表格和局限性。

用它来回答此类问题：

• 谁直接或间接调用了这个函数？

• 这个函数能触达什么，副作用发生在哪里？

• 在哪些守卫条件下才会发生这次 return 或 exception？

• 这段代码真的能在所请求的模式下到达那个目标吗？

• 一次 diff 会影响哪些 API 路由、脚本或导出的公开对象？

CodeCanvas 仅针对 Python，并且需要 Python 3.10 或更高版本。

试试看

只提问一个问题：

Use logic_flow on UserService.update_user. Show its branches, outcomes,
downstream effects, and evidence quality.

以下是来自 随附 FastAPI 示例 的一条实际回复摘录：

{
  "function": "app.services.user_service.UserService.update_user",
  "source": "app/services/user_service.py:13",
  "flow": [
    "15  user = await self.user_repo.find_by_id(...)",
    "16  if user is None:",
    "17      → return None",
    "18  → return await self.user_repo.update(user_id, user)"
  ],
  "outcomes": [
    {"at": 17, "detail": "None", "guards": ["user is None"]},
    {"at": 18, "detail": "await self.user_repo.update(user_id, user)", "guards": []}
  ],
  "downstream": [
    {
      "function": "app.repositories.user_repo.UserRepository.find_by_id",
      "location": "app/repositories/user_repo.py:13",
      "effects": ["db"]
    },
    {
      "function": "app.repositories.user_repo.UserRepository.update",
      "location": "app/repositories/user_repo.py:18",
      "effects": ["db"]
    }
  ],
  "evidence_grade": "inferred",
  "safe_to_summarize": false,
  "response_guidance": "Do not turn inferred call edges into unconditional claims."
}

这一个回答就清楚呈现了提前返回、成功路径、下游数据库操作、精准的源码位置，以及 agent 在总结前应如何谨慎。

Related MCP server: python-mcp-server

快速入门

如果还没有 uvx，请先安装 uv。本仓库包含一个共享插件包，为 Claude Code 和 Codex 提供原生描述清单。从 CodeCanvas 市场中安装：

# Claude Code
claude plugin marketplace add donggyun112/codecanvas
claude plugin install codecanvas@codecanvas

# Codex
codex plugin marketplace add donggyun112/codecanvas
codex plugin add codecanvas@codecanvas

两个插件都会启动 uvx codecanvas-mcp 并暴露完整的工具目录。有关本地 checkout 的测试及验证命令，查看插件包。

如果你的客户端不支持插件，也可以直接注册服务。用 Claude Code 时为：

claude mcp add codecanvas -- uvx codecanvas-mcp

那条命令会暴露完整的工具目录。当你的 MCP 客户端支持按需工具发现或搜索时，请保留完整目录可用：客户端只在需要时加载相关 schema 就能调用即可，其余 CodeCanvas 工具也因此仍然存在，不必在每个模型请求中都支付这些 schema 的代价。

[mcp_servers.codecanvas]
command = "uvx"
args = ["codecanvas-mcp"]

如果你的客户端会不加辨别地把每个已启用的工具 schema 注入到每个模型请求中，可改用这个“兼容模式”配置文件：

[mcp_servers.codecanvas]
command = "uvx"
args = ["codecanvas-mcp"]
enabled_tools = ["logic_flow", "who_calls", "call_tree"]

三个工具的白名单是给 eager-schema 客户端作后退的方案，不建议因此丢掉 CodeCanvas 的其他工具。对于其他 MCP 客户端，可使用等价的 stdio 配置：

{
  "mcpServers": {
    "codecanvas": {
      "command": "uvx",
      "args": ["codecanvas-mcp"]
    }
  }
}

在第一次工具调用时传入绝对路径 project_path，CodeCanvas 会记住你明确选择的那个项目，后续整个服务器会话期都会保留。

打开完整目录后，project_status 会报告嵌套的 Python 项目中候选分析根节点。使用 compatibility profile 的用户应显式传入预期的嵌套项目根目录。

训练你的 agent 如何使用

添加工具不能保证你的 agent 在正确的时机自动使用它。要在 AGENTS.md、CLAUDE.md 或你的编码 agent 所用的等价文件里加入类似这样的简短说明：

## Code analysis

Use CodeCanvas before text search when you need to know:

- how a Python function branches, returns, and produces side effects;
- who calls it directly or transitively;
- what it reaches downstream through project-internal calls.

Pass `project_path` once, then reuse the active project. Treat
`safe_to_summarize: false`, inferred edges, ambiguity, and truncation as
qualifications rather than unconditional facts.

Start with `logic_flow`. Use `who_calls` for upstream impact and `call_tree`
for a deeper downstream trace.

然后用自然语言请求你的 agent：

Use logic_flow first to understand checkout without repeated source searches.
What calls UserService.update_user, up to three hops?
What does checkout reach downstream, including HTTP or database effects?

在完整组合可用时，CodeCanvas 还可以回答：

List the entrypoints in this project.
Under exactly what conditions can authenticate raise?
Verify that dry-run publish reaches _call_api.
Analyze the impact of the current diff.

为什么 grep 或 LSP 不够？

CodeCanvas 是对两者的补充，它解决那些需要用重复搜索与手动重组才能回答的行为性问问题。

答案为什么可信

静态分析不是运行时的真相，因此 CodeCanvas 不让不确定性隐藏，而是让其可见。

每次成功的 MCP 响应都会指出所选的分析 analysis_root，并提供帮助 agent 判断能以多大把握表述回答的元数据：

• evidence_grade 指示已解析证据的强度。

• inferred_edge_count 和 ambiguous_calls 提示了不确定度量边。

• truncated 说明有界响应有没有丢弃结果。

• safe_to_summarize 表示该结果是否支持无条件对外结论。

• response_guidance 解释当结果不支持无条件表述时，该如何限定你的断言。

verify_claim 则更近一步，它将候选调用路径与分支和返回/抛出守卫结合起来，返回 true、false 或 uncertain；夸大的修饰语和仅可推断为真的路径都不会被悄悄变成明确的 true。

工具

发现与了解

跟踪行为和分析变化

重现状态类 Bug

大的返回结果设置会被封顶。请先通过每个工具的 filter、kind、path、depth 或 分页参数将结果缩小，然后再把它当完整结果。

原理

1. 选择项目。CodeCanvas 会解析并记录一个显式的 Python 项目根目录。简单的嵌套项目根需要显式选择，而不是自动猜。

2. 建立结构索引。Python AST 分析先建立整个项目的调用图以及每个函数的控制流信息；另通过额外 extractor 提取 FastAPI 路由、Depends() 链、scripts、通用函数入口点和包 exports。

3. 可以复用兼容分析。调用图和入口点在 <项目>/.codecanvas/ 被缓存；进程内的构建器在 MCP 会话中使用。

4. 生成紧凑的答案。每个 MCP 工具查询相同的共享分析结果（并返回带数据出处、置信度、歧义性和截断元数据的受限结果）。

默认的最大分析文件数为 5,000。通过下面的变量清除限制：

局限性与安全边界

• CodeCanvas 分析的是 Python 源码，而不是所有可能动态导入、猴子补断、反射路径或运行时值的模型。

• 推断出的边与有歧义的边都会归为限定条件，不会被冒认为证据。

• 静态分析工具会读取项目文件并在您 .codecanvas/ 目录写入缓存，无需远程 CodeCanvas 服务云。

• simulate_state_transition 例外，这一点不同：它会将可信的项目代码导入并执行到独立进程里。这种隔离只适用于针对性复现，并不是沙箱。被模拟的项目代码仍可能访问文件系统、网络或子进程，并且虽然没有明确逃逸，也可能有导入时副作用。

• 模拟器会优先 <project>/.venv 或 venv，然后同为父项目目录层级中的同级目录。要指定明确路径时使用 python_executable，并在导入出错时查看返回的 worker 元数据。

评价与验证

测量了本地延迟的套件包括三个固定版本项目，其包含 100–1,650 个 Python 文件，和 4,468–16,960 个已投用 ## functions。它能报告冷启动分析时间、首次以及暖启动查找的延迟，还有八个并发（worker）的处理吞吐；原始结果连同基准测试资源已提交到仓库中。

该模型驱动的评估涵盖 Google ADK、LangGraph 和 FastAPI 的冻结任务与隐藏评分标准。它将内置代码探索加上 logic_flow 与单独使用相同内置探索进行对比。在 54 个相互隔离的会话中，三次配对重复运行后，整个套件的中位结果为：服务器报告的 token 总数减少了 22.95%。全部 27 个处理会话均完成了所需的工具调用，这直接证明，一个 CodeCanvas 工具就能在不替换智能体现有搜索工具的前提下带来实实在在的价值。未缓存输入加输出的 token 中位数增加了 0.78%，而答案尚未经过盲评，因此这还不是一个“同等质量下更高效”或“计费成本更低”的结论。

请参阅完整方法论、基准结果、复现命令和审计工件。

开发

git clone https://github.com/donggyun112/codecanvas.git
cd codecanvas/core
uv sync --extra dev
cd ..
core/.venv/bin/python -m pytest

包源码位于 core/ 下。根测试配置会同时运行 tests/ 下的产品测试和 core/tests/ 下的包级测试。

欢迎提出问题和聚焦的复现案例： https://github.com/donggyun112/codecanvas/issues。

许可证

CodeCanvas MCP 是依据 MIT License 许可的开源软件。