project-graph-mcp: grafo para navegación de IA

project-graph-mcp: Gráfico de dependencias para la navegación de agentes de IA en código

Los sistemas de desarrollo multiagente requieren una navegación precisa a través de bases de código. El servidor project-graph-mcp ofrece una interfaz MCP para construir un gráfico de dependencias, comprimido en formato JSON minificado. Esto permite a los agentes comprender la arquitectura del proyecto sin gastar tokens al analizar archivos fuente.

El servidor analiza archivos, extrae clases, métodos e importaciones, y devuelve una estructura con una compresión de 10 a 50 veces. El soporte para JavaScript, TypeScript, Python y Go permite operar sin problemas en proyectos políglotas.

Esqueleto del proyecto en formato comprimido

La función principal es generar un "esqueleto" del proyecto. El parser escanea archivos fuente y produce una salida JSON que incluye leyendas, estadísticas y un grafo de nodos.

Salida de ejemplo:

{
  "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
  "s": { "files": 23, "classes": 10, "functions": 65 },
  "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
  "e": 35, "o": 7, "d": 5, "F": 63
}

• L — leyenda de nombres abreviados
• s — estadísticas (archivos, clases, funciones)
• n — nodos con métodos (m) y propiedades ($)
• e, o, d, F — aristas, objetos, directorios, archivos

Para exploraciones más profundas, usa los métodos expand y deps para ampliar dinámicamente el grafo.

Análisis multiidioma sin AST

Inicialmente desarrollado con Acorn para JavaScript. La versión 1.1 añadió parsers para TypeScript, Python y Go usando expresiones regulares. Este enfoque elimina dependencias externas mientras respeta las particularidades de cada lenguaje.

Una utilidad compartida stripStringsAndComments elimina cadenas y comentarios del código:

// Python
stripStringsAndComments(code, { tripleQuote: true, hashComment: true })

// Go
stripStringsAndComments(code, { backtick: true, templateInterpolation: false })

// TypeScript (por defecto)
stripStringsAndComments(code)

Todos los parsers se unifican bajo ParseResult: clases, funciones, importaciones, llamadas. Los patrones regex se adaptan al estilo del proyecto.

Análisis de código y puntuación de salud

El servidor incluye métricas de calidad:

• get_dead_code — detecta código no utilizado
• get_complexity — mide complejidad ciclomática
• get_large_files — identifica archivos que necesitan reestructuración
• get_call_chain — traza cadenas de llamadas (authMiddleware → validateToken → renderDashboard)

Comandos:

# Verificación de obsolescencia y dependencias
npx project-graph-mcp outdated .

# Análisis de complejidad
npx project-graph-mcp complexity src/

Los resultados se agregan en una Puntuación de Salud (0–100). Las sugerencias de respuesta indican pasos siguientes, como revisar funciones complejas.

Listas de verificación de pruebas mediante JSDoc

Soporte para anotaciones @test y @expect para documentar pruebas:

/**
 * Crear nuevo usuario vía API
 * 
 * @test request: POST /api/users con datos válidos
 * @expect status: 201 Creado
 */
async createUser(data) { ... }

• get_pending_tests — lista pruebas pendientes
• mark_test_passed — marca prueba como completada

Soporta pruebas de API, CLI, integración y navegador.

Personalización para frameworks

Conjuntos de reglas incorporados para React 18/19, Vue 3, Express 5, TypeScript 5, Symbiote.js (11 conjuntos, 86 reglas en total). Detección automática del proyecto mediante get_framework_reference.

Para convenciones personalizadas:

• Añade reglas en rules/
• Usa set_custom_rule desde el agente

Integración con grupos de agentes

En la orquestación fractal, el agente IDE solicita el esqueleto y delega tareas a trabajadores (Gemini, etc.). Cada trabajador ejecuta una instancia local de MCP para navegación usando expand/deps.

Solo ocupa 132 KB y tiene cero dependencias externas. Configuración para VS Code, Cursor, Zed:

{
  "mcpServers": {
    "project-graph": {
      "command": "npx",
      "args": ["-y", "project-graph-mcp"]
    }
  }
}

Seguridad y protección contra recorrido de rutas

La validación de rutas usa resolve + startsWith para restringir el acceso al directorio de trabajo. Métodos como expand, deps y get_skeleton heredan esta protección: una solicitud como ../../etc/passwd devuelve un error.

Destacados clave:

• Grafos de dependencias comprimidos aceleran la navegación de agentes de IA
• Analizadores basados en regex para JS/TS/Python/Go sin bibliotecas externas
• Puntuación de salud y análisis de cadenas de llamadas para refactorización dirigida
• Listas de verificación de JSDoc automatizan la documentación de pruebas
• 86 reglas predefinidas para frameworks populares listas para usar

— Editorial Team