CodeCanvas MCP

Entiende un sistema Python desconocido antes de gastar miles de tokens leyéndolo archivo por archivo.

CodeCanvas es un servidor local de análisis estático del Model Context Protocol para Python. Convierte las rutas de llamada y el flujo de control de todo el proyecto en respuestas compactas y listas para citar sobre ramificaciones, llamadores, funciones llamadas, efectos secundarios e impacto de los cambios.

El banco de pruebas abarca ahora revisiones fijadas de Google ADK, LangGraph y FastAPI. En un Apple M4 Pro, el análisis en frío medido osciló entre 4,38 s y 61,62 s, y la latencia media en caliente de find_symbols osciló entre 48,264 ms y 293,778 ms en esos repositorios. En una suite de agentes controlada de 54 sesiones, ambas condiciones conservaron las mismas herramientas de búsqueda de código integradas; el tratamiento añadió únicamente logic_flow. Esa única incorporación utilizó una mediana del 22,95 % menos de tokens totales en tres repeticiones emparejadas, lo que demuestra un valor incremental significativo sobre la exploración de código ordinaria. Los tokens no almacenados en caché aumentaron un 0,78 %, y las respuestas aún no se han evaluado a ciegas. Consulta la metodología, las tablas completas y las limitaciones.

Úsalo para responder preguntas como:

• ¿Quién llama a esta función, directa o transitivamente?

• ¿Qué puede alcanzar esta función y dónde se producen los efectos secundarios?

• ¿Bajo qué guardas puede ocurrir este retorno o excepción?

• ¿Llega realmente este origen a ese destino en el modo solicitado?

• ¿Qué rutas de API, scripts o exportaciones públicas se ven afectadas por un diff?

CodeCanvas es exclusivo de Python y requiere Python 3.10 o superior.

Ver la diferencia

Haz una pregunta:

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

Fragmento de la respuesta real en la muestra de FastAPI incluida:

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

Esa única respuesta expone el retorno temprano, la ruta de éxito, el trabajo posterior con la base de datos, las ubicaciones exactas del código y con cuánta cautela puede el agente resumir el resultado.

Related MCP server: python-mcp-server

Inicio rápido

Instala uv si uvx no está ya disponible. El repositorio incluye un paquete de plugin compartido con manifiestos nativos para Claude Code y Codex. Instálalo desde el marketplace de 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

Ambos plugins inician uvx codecanvas-mcp y exponen el catálogo completo de herramientas. Consulta el paquete de plugins para las pruebas locales de checkout y los comandos de validación.

Si tu cliente no admite plugins, registra el servidor directamente. Para Claude Code:

claude mcp add codecanvas -- uvx codecanvas-mcp

Ese comando expone el catálogo completo de herramientas. Mantén el catálogo completo habilitado cuando tu cliente MCP admita el descubrimiento o la búsqueda de herramientas bajo demanda: el cliente puede cargar solo los esquemas relevantes cuando los necesita, por lo que el resto de herramientas de CodeCanvas sigue disponible sin pagar su coste de esquema en cada solicitud del modelo.

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

Si tu cliente inyecta con avidez el esquema de cada herramienta habilitada en cada solicitud del modelo, usa en su lugar este perfil de compatibilidad:

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

La lista de permitidos de tres herramientas es un recurso limitado para clientes con esquemas "eager", no una recomendando descartar el resto de CodeCanvas. Para otro cliente MCP, usa la configuración stdio equivalente:

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

Pasa un project_path absoluto en la primera llamada a la herramienta. CodeCanvas recuerda el último proyecto seleccionado explícitamente durante el resto de la sesión del servidor.

Con el catálogo completo habilitado, project_status informa de las posibles raíces de análisis para proyectos Python anidados. Los usuarios del perfil compacto deben especificar explícitamente la raíz anidada prevista.

Enseña a tu agente cuándo utilizarlo

Añadir herramientas no garantiza que un agente las utilice en el momento adecuado. En un complemento breve como este en AGENTS.md, CLAUDE.md o el archivo correspondiente que utilice tu agente de programación:

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

Después pregunta a tu agente con naturalidad:

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?

Con el catálogo completo habilitado, CodeCanvas también puede responder:

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.

¿Por qué no usar simplemente grep o un LSP?

CodeCanvas complementa a ambos. Es para preguntas de tipo comportamental que, de otro modo, requieren buscar de nuevo manualmente y reconstruir el resultado.

Qué hace fiables las respuestas

El análisis estático no es la verdad en tiempo de ejecución, por lo que CodeCanvas visibiliza la incertidumbre en vez de ocultarla.

Cada respuesta MCP con éxito identifica la voz analysis_root seleccionada e incluye metadatos que ayudan al agente a decidir con cuánta rotundidad puede formular el resultado:

• evidence_grade describe la fuerza de la evidencia resuelta.

• inferred_edge_count y ambiguous_calls exponen los nodos de llamada inciertos.

• truncated indica si la respuesta acotada omitió resultados.

• safe_to_summarize muestra si la salida sostiene una afirmación incondicional.

• response_guidance explica si se debe calificar un resultado cuando no la sostiene.

verify_claim da un paso más al combinar las posibles rutas de llamada con bloques y con los guardias de retorno/elevación. Devuelve true, false o uncertain; los calificadores no verificados y las rutas solo inferidas no se convierten silenciosamente en un true definitivo.

Herramientas

Descubrir y comprender

Rastrear el comportamiento y valorar los cambios

===

Reproduice bug por estado

Los parámetros de resultados grands están límitados. Usa los argumentos filter, kind, path, depth o de paginacion de cada herramienta para acotar la resposta ones de tratarla como completa.

Cómo et l

1. Selecciona y recuerda. CodeCanvas restaurar y recuerda la raíz explícita de un proyecto Python. Las raíces anidadas ambiguas deben seleccionarse, no adivinarse.

2. Crea índices estructurales. El análisis AST de Python genera un grafo de llamadas a nivel de proyecto y el flujo de control por cada función. Los extractores de explotación aaden rutas de FastAPI y cadenas Depends().

3. Reutiliza el análisis. El grafo de llamadas y los puntos de entrada se guardan en <project>/.patología de codecanvas/.

4. Gobierna la respuesta. Cada herramienta MCIP consulta el análisis compartido y devuelve resultados acotados, con una extensión, y una nota de "origen, calidad, ambigüedad y truncado".

El límite predeterminado de análisis es de 5.000 archivos Python. Para grandes proyectos ajusta estos parámetros:

Seguridad y limitaciones

• CodeCanvas analiza el código fuente de Python; no proporciona una seguridades de todos los imports dinámicos, monkey patches, caminos de reflexión ni valores en runtime.

• Los arcos inferidos y ambiguos se reportan como aclaraciones, no son ascendidos a evidencia definitiva.

• Las herramientas de análisis estático leen los archivos del proyecto y escriben la caché local .codecanvas/; no se require una CodeCanvas remota.

• simulate_state_transition is distinct: it imports and executes the project code in a separate process. It is an added "aIsolamento para reproducción enfocada", but no es una sandbox de seguridad. El código del proyecto puede acceder al sistema de archivos, red o subprocess y puede tener efectos pintores en tiempo de import.

• The simulator prefers <project>/.venv or venv, then the same directories in the parent. Use python_executable to select one explicitly and check the worker metadata if the imports fail.

Mediciones

The article spans three pinned projects with 148–1,650 Python files and 4,468–16,960 quantified functions. It reports cold analysis, first and warm latency, and eight-worker throughput; the raw article is in with the test artifacts.

La evaluación basada en modelos cubre tareas fijas y rúbricas ocultas para Google ADK, LangGraph y FastAPI. Compara la exploración de código integrada más logic_flow frente a la misma exploración integrada por sí sola. En 54 sesiones aisladas, tres repeticiones emparejadas produjeron una mediana general de un 22,95 % menos de tokens totales informados por el servidor. Las 27 sesiones de tratamiento completaron la llamada a la herramienta requerida, proporcionando evidencia directa de que una herramienta de CodeCanvas añade valor significativo sin reemplazar las herramientas de búsqueda existentes del agente. La entrada y la salida sin caché aumentaron en una mediana del 0,78 %, y las respuestas aún no se han evaluado a ciegas, por lo que esto aún no es una afirmación de eficiencia a igual calidad ni de coste de facturación.

Consulta la metodología completa, las tablas de resultados, los comandos de reproducción y los artefactos de auditoría.

Desarrollo

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

El código fuente del paquete se encuentra en core/. La configuración de pruebas raíz ejecuta tanto las pruebas del producto en tests/ como las pruebas a nivel de paquete en core/tests/.

Los problemas y los casos de reproducción específicos son bienvenidos: https://github.com/donggy01255112/codecanvas/issues.

Licencia

CodeCanvas MCP es software de código abierto con licencia MIT License.