project-graph-mcp ayuda a los agentes de AI a ver la arquitectura del proyecto sin tokens de más

Ha surgido una nueva forma para que los agentes de IA naveguen rápidamente en código desconocido: project-graph-mcp construye un grafo estructural del proyecto y lo devuelve como JSON comprimido. En lugar de leer decenas de archivos en secuencia, un agente recibe un mapa de la arquitectura, ve las dependencias y luego se adentra en las áreas necesarias.

Cómo funciona el servidor

La idea clave detrás de project-graph-mcp es el llamado esqueleto del proyecto. El servidor analiza el código fuente, recopila información sobre archivos, clases, funciones, importaciones y llamadas, y luego devuelve todo esto en una estructura compacta. Según el autor, la compresión alcanza de 10 a 50 veces, lo que permite al modelo entender la arquitectura general sin consumir un contexto enorme. Este enfoque es especialmente útil para IDEs de agentes y orquestadores que necesitan decidir rápidamente qué archivo leer, dónde delegar subtareas y cómo se relacionan los módulos entre sí.

La compresión alcanza de 10 a 50 veces.

Inicialmente, la herramienta solo funcionaba con JavaScript a través del parser AST Acorn, pero en la versión 1.1 ganó soporte para TypeScript, Python y Go. Para los nuevos lenguajes, el autor eligió un enfoque basado en regex: es más simple, más ligero y no requiere descargar bibliotecas externas pesadas solo para la navegación básica del código. Al mismo tiempo, todos los parsers se estandarizan a la misma salida — listas de clases, funciones, importaciones y llamadas — para que el agente trabaje con el mismo modelo de proyecto independientemente de la pila tecnológica.

Qué problemas resuelve

El proyecto no termina con un único grafo. El servidor incluye herramientas de análisis incorporadas que permiten no solo la navegación sino también la identificación rápida de áreas problemáticas. El agente puede entender qué secciones de código están potencialmente muertas, dónde una función ha crecido a un tamaño incómodo y qué cadena de llamadas sigue una solicitud desde el middleware hasta el renderizado o el manejador de API. Esto hace que el servidor sea más que solo un mapa del proyecto: es una herramienta para el diagnóstico técnico inicial.

• `get_dead_code` encuentra funciones y módulos no utilizados
• `get_complexity` evalúa la complejidad ciclomática
• `get_large_files` identifica archivos como candidatos para refactorización
• `get_call_chain` muestra el camino entre funciones relacionadas
• Health Score agrega resultados de verificaciones en una puntuación de 0 a 100

Además, project-graph-mcp incluye listas de verificación de pruebas a través de anotaciones JSDoc `@test` y `@expect`. Un agente puede recibir una lista de verificaciones abiertas, escribir código y luego marcar las pruebas como aprobadas. Esto funciona como un puente entre la navegación del proyecto y el ciclo de desarrollo real: primero el modelo entiende la estructura de la aplicación, luego realiza cambios e inmediatamente verifica contra el comportamiento esperado. Para pilas típicas también hay reglas incorporadas: 11 conjuntos con 86 convenciones para React, Vue, Express, TypeScript y Symbiote.js.

Integración y seguridad

La herramienta está diseñada como parte de un marco de agente más amplio. El autor describe un escenario donde el agente principal en el IDE primero solicita el esqueleto del proyecto y luego delega tareas individuales a workers de fondo a través de agent-pool-mcp. Cada worker ejecuta el mismo servidor localmente e invoca `expand`, `deps` y otros métodos para secciones específicas de código. De esta manera, el orquestrador no tira archivos innecesarios al contexto y puede distribuir el trabajo más rápido entre modelos con diferentes especializaciones.

Desde la perspectiva de la implementación, la barrera de entrada es baja: se requiere Node.js 18+, el servidor se ejecuta a través de `npx`, pesa 132 KB, consta de 47 archivos y no tiene dependencias externas. La versión 1.2.0 ya está disponible en npm. Los autores también abordaron específicamente la seguridad. Todas las rutas se validan a través de `resolve` y `startsWith`, por lo que el agente no puede escapar del directorio de trabajo. Intentar acceder a algo como `../../etc/passwd` devuelve un error. Para herramientas MCP que leen archivos y dependencias, tal protección es crítica.

Qué significa esto

Los agentes de IA están pasando gradualmente de la autocompleción simple a la comprensión de la arquitectura de proyectos completos. project-graph-mcp es interesante porque resuelve un problema práctico de contexto: en lugar de cientos de líneas de código, el modelo obtiene un mapa compacto del sistema y funciona con mayor precisión. Para equipos que construyen sus propios agentes de IA para desarrollo, esto ya no es un experimento sino una capa de infraestructura práctica. Si tales servidores MCP se convierten en estándar, el desarrollo basado en agentes enfrentará menos límites de token y más frecuentemente estará limitado por la calidad de la lógica de ingeniería misma.