🧠 Architecture Copilot MCP

Understand your architecture. Build smarter with AI.

Un servidor MCP (Model Context Protocol) open source que analiza la arquitectura de tus proyectos mediante tree-sitter y networkx.

Construye un grafo de dependencias a partir del código existente y permite que asistentes de IA como GitHub Copilot y Cline comprendan la estructura del proyecto antes de generar nuevos módulos.

El objetivo es que la IA no escriba código de forma aislada, sino que respete los patrones, convenciones y decisiones arquitectónicas existentes.

✨ Características principales

• 🌐 Análisis multi-lenguaje: soporte para Python, JavaScript, TypeScript y TSX (React / Next.js).

• 🏗️ Grafo arquitectónico: representa las relaciones y dependencias entre módulos del proyecto.

• 🧹 Filtrado inteligente: ignora automáticamente directorios innecesarios como node_modules, .next, .venv y dist.

• 🤖 Integración MCP: expone herramientas para que los agentes de IA consulten la arquitectura existente.

• 🧩 Generación contextual: sugiere estructuras de archivos y módulos basándose en patrones detectados en el código.

• ⚡ Análisis local: procesa la arquitectura del proyecto sin necesidad de enviar el código a un servicio externo.

Related MCP server: Paparats: Local Semantic Code Search

🛠️ Requisitos previos

Antes de comenzar, asegúrate de tener instaladas las siguientes herramientas.

1. Python y uv

Se utiliza uv como gestor de dependencias y entornos de Python.

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Node.js (opcional)

Necesario únicamente si quieres utilizar el MCP Inspector, una interfaz visual para probar las herramientas del servidor.

Descarga Node.js desde nodejs.org o instálalo mediante:

winget install OpenJS.NodeJS

📦 Instalación

1. Clonar el repositorio

git clone https://github.com/TU-USUARIO/intent-graph-mcp.git

cd intent-graph-mcp

2. Instalar las dependencias

uv sync

3. Construir el grafo arquitectónico

Ejecuta el motor de análisis indicando la ruta del proyecto que quieres inspeccionar.

Windows

uv run python build_graph.py "C:\Ruta\A\Tu\Proyecto"

macOS / Linux

uv run python build_graph.py "./ruta-a-tu-proyecto"

Una vez finalizado el análisis, se generará el archivo:

grafo_proyecto.graphml

Este archivo contiene el grafo arquitectónico del proyecto analizado.

🧪 Probar el servidor MCP

Puedes verificar el funcionamiento del servidor mediante el MCP Inspector.

Ejecuta:

npx @modelcontextprotocol/inspector uv run python server.py

Se abrirá una interfaz web desde la que podrás:

1. Conectar con el servidor MCP.

2. Acceder a la sección Tools.

3. Consultar las herramientas disponibles.

4. Ejecutar suggest_skeleton utilizando intenciones como layout, users o components.

Esto permite comprobar las respuestas del servidor antes de integrarlo con un asistente de IA.

💻 Integración con VS Code

El servidor puede integrarse con asistentes compatibles con MCP, como GitHub Copilot y Cline.

Crea o modifica el archivo:

.vscode/mcp.json

Añade la siguiente configuración:

{
  "servers": {
    "architecture-copilot": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--project",
        "C:/Users/PC/intent-graph-mcp",
        "python",
        "C:/Users/PC/intent-graph-mcp/server.py"
      ]
    }
  }
}

Importante: reemplaza las rutas de ejemplo por la ubicación real del repositorio en tu equipo. Se recomienda utilizar rutas absolutas.

🎯 Cómo utilizarlo con IA

Una vez conectado el servidor MCP:

1. Abre tu proyecto en VS Code.

2. Inicia GitHub Copilot o Cline en modo Agent.

3. Solicita al agente que consulte la arquitectura antes de crear nuevos módulos.

Ejemplo de instrucción:

Utiliza la herramienta suggest_skeleton con la intención
"layout" y crea los archivos correspondientes en una
carpeta llamada "nuevo_componente".

Respeta los patrones arquitectónicos y las convenciones
detectadas en el proyecto existente.

🔄 ¿Qué sucede internamente?

1. El agente de IA invoca la herramienta suggest_skeleton.

2. El servidor consulta el grafo arquitectónico del proyecto.

3. El algoritmo identifica módulos similares y patrones existentes.

4. Se determina la estructura recomendada y las extensiones de archivo.

5. La IA utiliza esa información para generar el nuevo código siguiendo la arquitectura existente.

🧰 Herramientas MCP disponibles

⭐ Herramienta principal: suggest_skeleton

Es el punto central del proyecto. Permite que un agente de IA obtenga contexto arquitectónico antes de generar nuevos componentes o funcionalidades.

En lugar de proponer una estructura genérica, utiliza los patrones encontrados en el proyecto como referencia.

🧱 Tecnologías utilizadas

• Python — Motor de análisis.

• Tree-sitter — Análisis sintáctico del código fuente.

• NetworkX — Construcción y gestión del grafo de dependencias.

• MCP — Comunicación entre el servidor y los agentes de IA.

• uv — Gestión de dependencias y ejecución del proyecto.

• GraphML — Formato de almacenamiento del grafo arquitectónico.

🚀 Objetivo del proyecto

Architecture Copilot MCP busca mejorar la forma en que los agentes de IA interactúan con bases de código existentes.

La idea es incorporar una capa de contexto arquitectónico que permita generar código más coherente, mantener las convenciones del proyecto y reducir inconsistencias estructurales.

La IA no debería limitarse a escribir código. También debería comprender cómo está construido el proyecto.

📄 Licencia

Este proyecto es open source. Consulta el archivo LICENSE para conocer los términos de uso y distribución.