CodeCanvas MCP

낯선 Python 시스템을 파일 하나하나 읽으며 토큰을 소진하기 전에, 그대로 먼저 파악하세요.

CodeCanvas는 Python을 위한 로컬 정적 분석 Model Context Protocol 서버입니다. 프로젝트 전체 호출 경로와 제어 흐름을 분기, 호출자, 피호출자, 부작용, 변경 영향에 대한 간결하고 인용 가능한 답변으로 변환합니다.

벤치마크는 이제 고정(pinned) 리비전의 Google ADK, LangGraph, FastAPI를 대상으로 합니다. Apple M4 Pro에서 측정된 콜드 분석은 4.38s에서 61.62s 사이였고, 해당 저장소들에서 웜(warm) find_symbols 중간 지연(latency)은 48.264ms에서 293.778ms 사이였습니다. 통제된 54개 세션 에이전트 스위트에서 두 조건 모두 동일한 내장 코드 검색 도구를 유지했고, 실험 조건에는 logic_flow 만 추가되었습니다. 그 단일 추가만으로 세 번의 쌍체 반복 실행에서 중간 기준 총 22.95% 더 적은 토큰을 사용했고, 이는 엔진의 상위 코드 탐색 토대 위에서 뚜렷한 증분 가치를 보여줍니다. 캐시되지 않은 토큰은 0.78% 증가했으며, 답변에는 아직 눈가림 채점(blind grading)이 이루어지지 않았습니다. 방법론, 전체 표와 한계를 참조하세요.

다음과 같은 질문에 답하기 위해 사용하세요:

• 이 함수를 직접 또는 전이적으로 부르는 호출자는 누구인가요?

• 이 함수는 어떤 대상에 도달할 수 있고, 부작용은 어디에서 발생하나요?

• 어떤 가드(guard) 아래에서 이 반환(return) 또는 예외가 발생할 수 있나요?

• 이 소스는 요청한 모드에서 실제로 그 대상까지 도달하나요?

• diff에 영향을 받는 API 경로, 스크립트 또는 공개 내보내기(export)는 무엇인가요?

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

이 단일 응답은 조기 반환(early return), 성공 경로, 이후의 데이터베이스 작업, 정확한 소스 위치, 그리고 에이전트가 결과를 얼마나 신중하게 요약할 수 있는지 드러냅니다.

Related MCP server: python-mcp-server

빠른 시작

아직 uvx를 사용할 수 없다면 uv를 설치하세요. 레포지토리에는 Claude Code와 Codex 모두에 대한 native 매니페스트가 포함된 공용 플러그인 패키지가 하나 있습니다. 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 클라이언트가 온디맨드형 도구 검색 (demand-based tool discovery)을 지원한다면 전체 카탈로그를 활성화 상태로 유지하세요: 클라이언트는 스키마가 실제로 필요할 때만 스키마를 로드할 수 있으므로, 다른 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"]

세 가지 도구의 allow-list는 스키마 강제 주입(eager-schema) 클라이언트를 위한 폴백 (fallback)일 뿐, CodeCanvas의 나머지 도구를 버리라는 권장 박은 아닙니다. 다른 MCP 클라이언트에는 동일한 stdio 설정을 사용하세요:

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

첫 도구 호출에 절대 경로 project_path를 전달하세요. CodeCanvas는 서버 세션 동안 마지막으로 명시적으로 선택한 프로젝트를 기억합니다.

전체 카탈로그를 활성화한 상태에서는 중첩된 Python 프로젝트에 대한 분석 후보 루트를 project_status가 보고합니다. Compact 프로파일 주 user라면 의도한 중첩 루트를 명시적으로 전달하세요.

에이전트가 언제 사용할지 가르치기

도구를 추가한다고 해서 에이전트가 적절한 때에그 도구를 고르는다고 보장되지는 않습니다. 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는 둘 다 보완합니다. 그 밖에는 반복된 검사와 수동적인 재구성으로만 풀 수 있어 행동적 질문answering을 위한 것입니다.

답변 은, 무엇이 그것을 신뢰 가능하게 만드는가

정적 분석은 실행 진실이 아니므로 CodeCanvas는 불확실성을 숨기지 않고 드러나게 합니다.

성공적인 모든 MCP 응답은 선택된 analysis_root를 표기하고,에이전트가 결과를 얼마나 강하게 주장해도 되는지 판단하게 하는 메타데이터를 포함합니다:

• evidence_grade는 해석된 증거의 강도를 설명합니다.

• inferred_edge_count와 ambiguous_calls은 움직일 수 없는 호출 엣지(edge)를 노출합니다.

• truncated는 제한된 응답이 결과 일부를 누락했는지 알려줍니다.

• safe_to_summarize는 결과를 공통된 주장으로 요약할 지원하는지 알려줍니다.

• response_guidance는 그렇지 않은 경우 결과를 어떻게 자격을 단서로 설명해야 하는지 알립니다.

verify_claim은 후보 호출 경로를 분기 및 return/raise 가드와 결합하여 한 걸음 더 나아갑니다. 그것은 true, false, 또는 uncertain을 반환합니다. 지원되지 않는 수식자와 inference-only 경로는 조용히 확정적인 true가 될 수 없습니다.

도구

발견하고 이해하기

동작을 추적하고 변경을 평가하기

번호지 states 모양의 버그를 재현명

큰 결과 집합은 상한이 있습니다. 결과를 전체라고 간주하기 전에대 각 도구의 filter, kind, path, depth, 또는 페이지네이션 인자를 사용해 답을 좁히세요.

동작 방식

1. 프로젝트를 선택한다. CodeCanvas는 명시적인 Python 프로젝트 루트를 해석하여 기억합니다. 중첩 폴더가 모호한 경우에는 추측하기보다 선택해야 합니다.

2. 구조 산출물을 구축한다. Python AST 분석은 프로젝트 전체의 호출 그래프와 함수 단위 제어 흐름 데이터를 만듭니다. 추출기들은 FastAPI 라이트와 Depends() 체인, 스크립트, 일반 함수 진입점, 라이브러리 exports를 추가합니다.

3. 호환 가능한 분석재활용한다. 호출 그래프와 진입점은 <project>/.codecanvas/에 캐시됩니다. MCP 세션 인라스에서는 인프러 빌더를 재사용합니다.

4. compact answers를 만들어낸다. 각 MCP 도구가 공유된 분석 정보를 검토하고, 출처, 증거, 모호성, 절단 메타데이터와 함께 제한된 결과를 돌려줍니다.

기본 분석 한도는 5,000 Python 파일입니다. 대형 프로젝트의 동작은 아래 매개변수로 조정할 수 있습니다:

안전과 제약점

• CodeCanvas는 Python 소스를 분석하지만 모든 동적 import, monkey patch, 반사(reflection) 경로 또는 런타임 값을 모형화하지는 않습니다.

• 추정/모호한 엣지는 확정적 근거로 승격되지 않고 '자격 부여된 것'으로만 보고됩니다.

• 정적 분석 도구들은 프로젝트 파일을 읽고 로컬 .codecanvas/ 캐시를 씁니다. 원격브 CodeCanvas 서비스는 필요하지 않습니다.

• simulate_state_transition은 다릅니다: 수행은 프로세스에 분리된 프로세스에서 신뢰하는 프로젝트 코드를 불러와 실행합니다. 그것은 집중 재현을 위한 격리 기능이지 보안 모래사장(sandbox)이 아닙니다. 프로젝트 코드가 여전히 파일시스템, 네트워크, 하위 프로세스에 접근할 수 있고, 불러오기 시점의 부작용이 있을 수 있습니다.

• 시뮬레이터는 <project>/.venv 또는 venv를 우선적으로 사용하며 그 다음 상위 프로젝트의 동일한 디렉토리를 사용합니다.python_executable로 분명히 지정하고, import가 실패하면 반환된 worker 메타데이터를 확인하세요.

증거

측정된 로컬 지연 측정 모음은 148–1,650개 Python 파일과 4,468–16,960개의 인덱싱된 함수를 가진 세 pinch 프로젝트를 대상으로 합니다. 콜드 분석, 첫 및 웜-러브 latency, 그리고 8-work 크기 처리율을 보고하며, 원본 결과는 벤치마크 산출물과 함께 저장 본 그대로 커밋되어 있습니다.

모델 기반 평가는 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에 따라 배포되는 오픈소스 소프트웨어입니다.