Corpus

Corpus agrega la documentación de todos los repositorios de tu organización, construye un mapa del sistema en vivo utilizando las entidades de catálogo de Spotify Backstage, y lo pone todo detrás de un potente servidor Model Context Protocol (MCP).

Dale a tus agentes de IA (Claude, Copilot, etc.) el contexto holístico que necesitan para comprender tu arquitectura, la propiedad de los servicios, la documentación y el código, ¡todo en un solo lugar!

✨ Características

• 🗺️ Grafo de entidades generado automáticamente: Analiza completamente las entidades de Backstage catalog-info.yaml (Components, APIs, Systems, Users) y genera un grafo de relaciones bidireccional utilizando relaciones bien conocidas (p. ej., ownerOf/ownedBy, providesApi/apiProvidedBy).

• 📖 Búsqueda centralizada de documentación: Búsqueda léxica rápida en README.md, docs/**/*.md, adr/**/*.md y habilidades de IA en toda tu organización.

• 🔍 Búsqueda global de código: Búsqueda por palabras clave en todos los repositorios de la organización a través de la API de búsqueda de código de GitHub.

• 💬 Contexto de issues y PRs: Actúa como proxy de la API de búsqueda de GitHub para encontrar discusiones, PRs e issues en toda la organización (search_issues_and_prs).

• 📄 Lectura de archivos: Acceso directo al contenido exacto de archivos desde cualquier rama o commit de un repositorio.

• ⚙️ Agregación de esquemas de API: Indexa automáticamente los archivos openapi y swagger para que los agentes puedan obtener contratos de endpoints al instante (list_api_schemas).

• 🚀 Inicio sin configuración: Ejecuta automáticamente las compilaciones pendientes al iniciar. Si tienes credenciales, solo ejecuta npm start y el servidor obtiene e indexa todo.

• 🐞 Informe de brechas: Capacidad opcional de crear un issue de GitHub cuando la documentación no responde a la pregunta de un agente.

Related MCP server: repovine

🛠️ Inicio rápido

1. Requisitos previos

• Node.js v22+

• GitHub PAT (Personal Access Token):

  • Classic Token: Necesita repo (para leer repositorios privados) y read:org (si se consulta una organización).

  • Fine-Grained Token: Necesita Contents: Read-only y Metadata: Read-only para todos los repositorios. Si habilitas ENABLE_GAP_REPORTING, también necesitas Issues: Read & Write en el repositorio de destino.

2. Configurar el entorno

Crea un archivo .env en el directorio raíz:

GIT_ORG=your-github-org-or-username
GIT_PAT=your-github-personal-access-token

# Optional
ENABLE_GAP_REPORTING=false
GITHUB_PROJECT=your-github-org/doc-gaps-repo

3. Compilar y ejecutar

Ejecución local:

npm install
npm run build
npm start

Nota: npm start inicia automáticamente los scripts de generación del corpus y del mapa del sistema si aún no se han ejecutado.

Ejecución con Docker:

docker build -t corpus-mcp .
docker run -i -e GIT_ORG=your-github-org -e GIT_PAT=your-github-pat corpus-mcp

🤖 Registro con clientes de IA

Antigravity

Antigravity es compatible con MCP de forma nativa. Configura el servidor globalmente añadiéndolo a ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "DOTENV_CONFIG_PATH": "/absolute/path/to/code-context-mcp/.env",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Desktop

Añade esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "corpus": {
      "command": "node",
      "args": ["/absolute/path/to/code-context-mcp/dist/src/index.js"],
      "env": {
        "GIT_ORG": "your-github-org",
        "GIT_PAT": "your-github-pat",
        "CORPUS_DIR": "/absolute/path/to/code-context-mcp/corpus"
      }
    }
  }
}

Claude Code

Ejecuta lo siguiente en la raíz del proyecto:

claude mcp add corpus "node $(pwd)/dist/src/index.js"

🏗️ Arquitectura y comandos

• npm run build:corpus: Rastrea la organización de GitHub y descarga la documentación y los datos del catálogo en corpus/manifest.json.

• npm run build:map: Transforma el manifiesto en un grafo de dependencias activo guardado en corpus/system-map.yaml.

• npm run build: Ejecuta el pipeline completo y compila TypeScript.

• npm run test: Ejecuta pruebas unitarias utilizando el ejecutor de pruebas nativo de Node.js.

🧩 Mapa del sistema y catalog-info.yaml

Corpus genera automáticamente un grafo de dependencias global de los servicios de tu organización. Para participar en el mapa del sistema, cada repositorio debe contener un archivo catalog-info.yaml en su raíz, conforme al formato de descriptor de Backstage.

Debido a que Corpus actúa como un procesador de catálogo de Backstage, extrae cualquier tipo de entidad (Component, API, System, Group) y conecta automáticamente las relaciones bidireccionales. Si tu Component define owner: group:auth-team y providesApis: [api:auth-api], Corpus genera automáticamente las aristas ownedBy/ownerOf y providesApi/apiProvidedBy para que los agentes de IA puedan recorrer de forma nativa todo el grafo de servicios de tu organización.

Ejemplo de catalog-info.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-auth-service
  description: Handles user authentication and token generation
spec:
  type: service
  lifecycle: production
  owner: group:auth-team
  providesApis:
    - api:auth-api
  dependsOn:
    - component:user-database
    - component:email-service

💡 Buenas prácticas y filosofía

Para sacar el máximo partido a Corpus y a tus agentes de IA, recomendamos las siguientes prácticas de ecosistema:

1. Mantén la documentación cerca del código: La documentación debe vivir en el repositorio junto al código. El mejor lugar para documentar cómo funciona un sistema es directamente junto al propio sistema. Corpus recoge automáticamente docs/**/*.md y adr/**/*.md de todos tus repositorios.

2. Repositorio Wiki central: Si tienes decisiones arquitectónicas a nivel de empresa, RFCs o estándares de calidad de código que abarcan múltiples sistemas, mantenlos en un repositorio "Wiki" central como archivos markdown. Corpus los agregará perfectamente.

3. Sinergia con Spotify Backstage: Si usas Backstage, Corpus es el compañero perfecto.

   • Backstage es un Portal Interno para Desarrolladores (IDP) construido para humanos, que proporciona una interfaz web enriquecida.

   • Corpus es un IDP construido para agentes de IA, que expone exactamente el mismo contexto a través de MCP. Debido a que Corpus analiza de forma nativa los archivos estándar catalog-info.yaml, no hay trabajo duplicado. Si tus equipos ya están definiendo etiquetas dependsOn, lifecycle y owner para Backstage, Corpus las recoge automáticamente y las traduce en un grafo activo que los agentes de IA pueden recorrer.

4. Actualizaciones automáticas frecuentes: El Corpus está pensado para ser una instantánea viva y dinámica de tu organización. Ejecutar los scripts de compilación (npm run build) vuelve a obtener y reconstruye el corpus localmente. Debido a que es un simple script de scraping de API, consume cero tokens de LLM para construirse. Idealmente, Corpus debería desplegarse de forma centralizada dentro de tu empresa, utilizando un cron job (como una GitHub Action) para reconstruir el manifest.json cada noche y distribuirlo a tus desarrolladores.

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta nuestras Guías de contribución para obtener detalles sobre cómo empezar, configurar tu entorno de desarrollo y enviar Pull Requests.

Este proyecto aplica Conventional Commits. Un hook de pre-commit formatea automáticamente tu código con Prettier y lo verifica con ESLint.

Consulta la Guía de habilidades de configuración para más detalles.

📄 Licencia

Corpus es de uso gratuito. Toda la propiedad intelectual pertenece a Sayam Hussain.

Este proyecto está licenciado bajo la Licencia MIT.