CodeCanvas MCP

Разберитесь в незнакомой Python-системе, прежде чем тратить тысячи токенов, читая её файл за файлом.

CodeCanvas — это локальный сервер статического анализа для Model Context Protocol на Python. Он превращает общепроектные пути вызовов и поток управления в компактные, готовые к цитированию ответы о ветвлениях, вызывающих функциях, вызываемых функциях, побочных эффектах и влиянии изменений.

Бенчмарк теперь охватывает зафиксированные версии Google ADK, LangGraph и FastAPI. На Apple M4 Pro измеренное число холодных запусков варьировалось от 4.38s до 61.62s, а медианная задержка тёплого поиска find_symbols — от 48.264ms до 293.778ms в этих репозиториях. В контролируемом наборе из 54 сессий агента в обоих случаях оставались одни и те же встроенные инструменты поиска по коду; в экспериментальный вариант добавлялся только logic_flow. Это единственное добавление сократило среднее 22.95% общего количества токенов на три пары повторных запусков, что демонстрирует ощутимую дополнительную ценность в дополнение к обычному исследованию кода. Количество некэшированных токенов выросло на 0.78%, и ответы ещё не проверялись вслепую. См. методологию, полные таблицы и ограничения.

Используйте его для ответов на такие вопросы:

• Кто вызывает эту функцию напрямую или транзитивно?

• Чего может достичь эта функция и где происходят побочные эффекты?

• При каких защитных условиях может произойти этот возврат или исключение?

• Действительно ли этот источник достигает той цели в запрошенном режиме?

• Какие API-маршруты, скрипты или публичные экспорты затрагивает diff?

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."
}

Этот единственный ответ показывает ранний возврат, путь успеха, нижестоящую работу с базой данных, точные места в исходном коде и то, насколько осторожно агент может обобщить результат.

Related MCP server: python-mcp-server

Быстрый старт

Установите uv, если uvx ещё не доступен. Репозиторий содержит один общий пакет плагинов с нативными манифестами как для 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-проектов. Пользователям компактного профиля следует явно передавать нужный вложенный корень.

Научите агента использовать свои инструменты

Добавление инструментов не гарантирует, что агент выберет их в нужное время. Поместите краткую инструкцию вроде такой в AGENTS.md, CLAUDE.md или в эквивалентный файл, используемый вашим агентом разработки:

## 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.

Затем задайте своему агенту обычный вопрос:

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 и включает метаданные, которые помогают агенту решить, насколько сильно он может заявлять результат:

• evidence_grade сообщает о прочности установленных доказательств.

• inferred_edge_count и ambiguous_calls показывают неопределённые рёбра вызовов.

• truncated говорит, содержит ли ограниченный ответ усечённые результаты.

• safe_to_summarize говорит, поддерживает ли результат безоговорочную проверку.

• response_guidance объясняет, как оговорочно сформулировать результат, не поддерживающий её.

verify_claim идёт дальше, комбинируя пути вызовов из кандидатов с guard-условиями ветвей и возвратов/исключений. Она возвращает true, false или uncertain; неподдержанные уточняющие слова и только предполагаемые пути не могут незаметно стать определённым true.

Инструменты

Обнаружение и понимание

Отследи поведения и оценить изменения

Воспроизведение ошибок, формируемых состоянием

Большие наборы результатов ограничивать. Используйте аргументы filter, kind, path, depth или пагинацию для сужения ответа каждым инструментом, прежде чем считать её полной.

Как это работает

1. Выбейте проект. CodeCanvas находит и запоминает явный корень Python-проекта. Неоднозначные вложенные корни необходимо указывать, а не угадывать.

2. Постройте структурные индексы. Анализ AST для Python строит общепроектный граф вызовов и данные потока управления по каждой функции. Дополнительные экстракторы добавляют маршрутное FastAPI и цепочки Depends(), скрипты, обычные входные точки functions и экспорты пакетов.

3. Переиспользуйте совместимый анализ. Граф вызовов и точки входа кэшируются в <project>/.codecanvas/; внутрипроцессный построитель переиспользуется в течение сессии MCP.

4. Формируйте компактные ответы. Каждый инструмент MCP запрашивает общий анализ и возвращает органиченные результаты с информацией или происхождением, достоверностью, неоднозначностью и признакам усечения.

Стандартный лимит анализа — 5,000 файлов Python. Настройте работу для крупных проектов с помощью:

Безопасность и ограничения

• CodeCanvas анализирует исходный код Python; он не осознаёт все возможные динамические импорты, подмену интерпретации (monkey patch), рефлексию и значения времени выполнения.

• Инференцированные и не однозначные рёбра докладываются как ограничения, а не определяются как определённые доказательства.

• Недотрук от средства анализа читает файлы проекта и записывает локальный кэш .codecanvas/. Внешний сервис CodeCanvas не требуется.

• simulate_state_transition отличается: он импортирует и исполняет доверенный код проекта в отдельном процессе. Это изоляция для экспериментов, но не песочница безопасности. Код проекта всё ещё может взаимодействовать с файловой системой, сетью и подпрорестами/вызывать подпроцессы, а также может иметь побочные эффекты времени импорта.

• Симулятор предпочитает <project>/.venv или venv, затем те же каталоги в головном проекте. Используйте python_executable для явного выбора и проверьте возвращаемую метаданные worker, когда импорт не сработает.

Данные о производительности

Измерительная локальная latency-множество покрывает три зафиксированных проекта, в которых 148–1 650 Python-файлов и 4 468–16 960 проиндексированных функций. Она сообщает время холодного анализа, первого и «тёплого» поиска, получает пропускную способность восьми наборщиками "worker" и содержит "сырые" результаты в репозитории с бенчмарк-артефактами.

Модельная оценка охватывает замороженные задачи и скрытые рубрики для Google ADK, LangGraph и FastAPI. В ней сравнивается встроенное исследование кода вместе с logic_flow против того же встроенного исследования по отдельности. В 54 изолированных сеансах три парных повтора дали медианное по всему набору сокращение общего числа токенов по данным сервера на 22,95%. Все 27 экспериментальных сеансов выполнили требуемый вызов инструмента, что служит прямым свидетельством того, что один инструмент CodeCanvas добавляет значимую ценность, не заменяя существующие поисковые инструменты агента. Некэшированный ввод и вывод при этом выросли на медианные 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.