codecanvas

CodeCanvas MCP

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

CodeCanvas 是一个面向 Python 的本地静态分析 Model Context Protocol 服务。它将项目范围的调用路径和控制流，转化为精简且可引用的答案，涵盖分支、调用方、被调用方、副作用和变更影响。

基准测试现已涵盖 Google ADK、LangGraph 和 FastAPI 的固定版本。在 Apple M4 Pro 上，这些代码库的冷分析耗时为 4.38s 至 61.62s，find_symbols 的热运行中位延迟为 48.264ms 至 293.778ms。在受控的 54 次会话 Agent 测试套件中，两组条件都使用相同的内置代码搜索工具；实验组仅额外启用了 logic_flow。仅此一项新增功能，就在三轮配对测试中使总 token 中位数减少了 22.95%，证明它在常规代码探索之上带来了显著的增量价值。未缓存 token 增加了 0.78%，且答案尚未经过盲评。请参阅方法、完整表格和局限性。

可用它回答如下问题：

• 哪些函数会直接或传递地调用此函数？
• 此函数能触达什么内容，副作用又发生在哪里？
• 在哪些守卫条件下可能返回该结果或引发异常？
• 在请求的模式下，此源代码是否真的能触达目标？
• 差异会影响哪些 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 应如何谨慎地概括结果。

快速开始

如果尚未安装 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 并公开完整的工具目录。有关本地检出测试和验证命令，请参阅插件包。

如果你的客户端不支持插件，请直接注册该服务。Claude Code 的配置如下：

claude mcp add codecanvas -- uvx codecanvas-mcp

此命令会公开完整的工具目录。如果你的 MCP 客户端支持按需发现工具或搜索工具，请保持完整目录启用：客户端可以仅在需要时加载相关架构，因此其余 CodeCanvas 工具仍可用，而不会在每次模型请求时都产生架构成本。

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

如果你的客户端会在每次模型请求时主动注入所有已启用工具的架构，请改用此兼容配置：

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

这个三工具允许列表是为主动注入架构的客户端提供的备用方案，并不建议因此舍弃 CodeCanvas 的其他功能。对于其他 MCP 客户端，请使用等效的 stdio 配置：

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

首次调用工具时，传入绝对路径 project_path。在本次服务会话的其余时间里，CodeCanvas 会记住最近一次明确选择的项目。

启用完整目录后，project_status 会报告嵌套 Python 项目的候选分析根目录。使用精简配置的用户应明确传入所需的嵌套根目录。

教会你的 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 能与两者互补。它适用于行为类问题；否则，这类问题需要反复搜索并手动重建信息。

需求	grep	LSP	CodeCanvas
精确文本	最适合	不适用	继续使用 grep
定义和直接引用	手动查找	最适合	在结构化结果中解析符号
传递调用方和被调用方	反复手动跳转	引用并非调用路径	有界的上游和下游图
分支守卫和结果	阅读并重建源代码	通常不会建模	结构化流程及带守卫条件的返回/抛出
副作用和变更影响	手动推断	通常不会建模	通过调用路径和入口点归因效果
不确定性	无置信度模型	取决于解析结果	证据等级、歧义、截断情况和指导信息

答案为何可信

静态分析并不等同于运行时事实，因此 CodeCanvas 会明确呈现不确定性，而不是将其隐藏起来。

每个成功的 MCP 响应都会标明选定的 analysis_root，并包含元数据，帮助 Agent 判断可以多有把握地陈述结果：

• evidence_grade 描述已解析证据的强度。
• inferred_edge_count 和 ambiguous_calls 揭示不确定的调用边。
• truncated 表示有界响应是否省略了结果。
• safe_to_summarize 表示结果是否支持无条件断言。
• response_guidance 说明结果不支持无条件断言时应如何限定表述。

verify_claim 更进一步，会结合候选调用路径与分支及返回/抛出守卫条件。它会返回 true、false 或 uncertain；不受支持的限定条件和仅基于推断的路径不会悄然变成确定的 true。

工具

探索和理解

工具	用途
project_status	检查当前根目录、Python 文件数量、缓存、工作进程解释器和嵌套项目候选项
list_entrypoints	查找 FastAPI 路由、脚本、函数入口点和分布式库导出项
find_symbols	通过精确优先、语义或混合搜索定位函数、方法和类
logic_flow	获取函数分支、结果、下游调用和效果的精简视图，可直接用于引用
what_does	根据函数签名、文档字符串、调用、副作用、异常和直接风险，对函数进行初步判断
function_flow	检查包含主题、条件、作用域和嵌套关系的结构化分支树
reaching_conditions	获取每个返回或抛出处的外围守卫条件，以及复杂度和不可达代码

跟踪行为并评估变更

工具	用途
who_calls	向上遍历直接或传递调用方
call_tree	向下遍历项目内部的被调用函数，并归因直接/传递效果
verify_claim	根据路径和守卫条件，谨慎核验限定的 source reaches target 声明
analyze_impact	将内联差异或 git ref 映射到已变更函数及受影响的入口点/公共接口

重现与状态相关的 Bug

工具	用途
validate_state_schema	将函数的状态读取、写入和映射返回值与调用方提供的架构进行比较
simulate_state_transition	使用不变量和依赖项覆盖，执行针对性的生成状态案例或显式状态案例

大型结果集会受到限制。在将答案视为完整结果之前，请使用各工具的 filter、kind、path、depth 或分页参数缩小范围。

工作原理

1. 选择项目。 CodeCanvas 会解析并记住明确指定的 Python 项目根目录。遇到有歧义的嵌套根目录时，必须由用户选择，不能自行猜测。
2. 构建结构索引。 Python AST 分析会构建项目范围的调用图和各函数的控制流数据。提取器还会添加 FastAPI 路由和 Depends() 链、脚本、通用函数入口点和包导出。
3. 复用兼容的分析结果。 调用图和入口点会缓存在 <project>/.codecanvas/ 中；MCP 会话期间会复用进程内的构建器。
4. 生成精简答案。 每个 MCP 工具都会查询共享分析结果，并返回有界结果，其中包含来源、证据、歧义和截断元数据。

默认分析上限为 5,000 个 Python 文件。可通过以下变量调整大型项目的处理方式：

变量	默认值	描述
CODECANVAS_MAX_FILES	5000	要分析的 Python 文件上限
CODECANVAS_BATCH_SIZE	50	每次处理后让出执行权的文件数
CODECANVAS_THROTTLE_MS	10	批次间的延迟时间，单位为毫秒

安全性与限制

• CodeCanvas 分析 Python 源代码；它无法对所有可能的动态导入、猴子补丁、反射路径或运行时值建模。
• 推断出的边和有歧义的边会作为限定信息报告，不会被提升为确凿证据。
• 静态分析工具会读取项目文件并写入本地 .codecanvas/ 缓存。无需使用远程 CodeCanvas 服务。
• simulate_state_transition 则有所不同：它会在单独进程中导入并执行可信的项目代码。这是为定向复现提供的隔离机制，并非安全沙箱。项目代码仍可能访问文件系统、网络或子进程，也可能产生导入时副作用。
• 模拟器会优先使用 <project>/.venv 或 venv，然后查找父项目中的同名目录。可使用 python_executable 明确指定，并在导入失败时检查返回的 worker 元数据。

证据

本地延迟测试套件测量了三个固定版本的项目，这些项目包含 148–1,650 个 Python 文件和 4,468–16,960 个已索引函数。测试报告冷启动分析、首次和热启动搜索延迟，以及 8 个工作进程的吞吐量；原始结果与基准测试产物一同提交。

模型评估使用了针对 Google ADK、LangGraph 和 FastAPI 的冻结任务与隐藏评分标准。该评估比较了内置代码探索加 logic_flow 与单独使用内置代码探索的效果。在 54 个隔离会话中，进行了 3 组配对重复测试，整个测试套件报告的服务器总 Token 数中位数减少了 22.95%。所有 27 个实验组会话都完成了所需的工具调用，直接证明了一个 CodeCanvas 工具能带来有意义的价值，同时不会取代 Agent 现有的搜索工具。未缓存的输入与输出 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 授权的开源软件。