Centro de Arquitectura Multi-Repositorio (oss-mcp)

Un enrutador de arquitectura multi-repositorio extensible y servidor de Model Context Protocol (MCP) escrito en Node.js (ESM). Diseñado para el descubrimiento de dependencias entre repositorios, el enrutamiento topológico y la integración de indexación AST por lotes con codebase-memory-mcp.

⚡ Inicio Rápido (Configuración en 3 Minutos)

1. Requisitos Previos

Asegúrate de tener Node.js (>= 18) y codebase-memory-mcp instalados globalmente:

# Install codebase-memory-mcp globally
npm install -g codebase-memory-mcp@latest

2. Clonar e Instalar Dependencias

git clone https://github.com/Abbilville/oss-mcp oss-mcp
cd oss-mcp
npm install

3. Inicializar Cualquier Espacio de Trabajo Multi-Repositorio

Apunta oss-mcp a tu directorio de microservicios. Escaneará los repositorios, generará registry.yaml e indexará automáticamente el código en grafos de conocimiento AST por lotes:

npx oss-mcp setup /path/to/your/microservices-workspace

Related MCP server: Codebase Contextifier 9000

🚀 Capacidades Clave

1. Descubrimiento Dinámico Multi-Proyecto: Resuelve manifiestos de repositorios (registry.yaml) dinámicamente a partir de parámetros de CLI, catálogos centrales (data/projects.yaml), variables de entorno o la jerarquía del espacio de trabajo.

2. Escáner Automatizado de Estructura y Dependencias: Inspecciona recursivamente árboles de directorios en múltiples stacks tecnológicos (Node.js, Express, React, Python, FastAPI, Java, Go), detectando puntos de entrada, puertos y relaciones HTTP/eventos entre servicios.

3. Indexación AST por Lotes Automatizada: Orquesta la indexación de grafos AST de codebase-memory-mcp en todos los servicios de un manifiesto de proyecto con un solo comando.

4. Interfaz MCP Estructurada: Expone herramientas estandarizadas para que los agentes de IA consulten arquitecturas entre servicios, rastreen ciclos de vida de solicitudes de extremo a extremo y naveguen por los límites entre múltiples servicios.

📁 Trabajando con el Directorio data/

El directorio data/ proporciona gestión centralizada de proyectos para entornos que alojan múltiples proyectos o sistemas de microservicios distintos.

data/
├── projects.yaml         # Central multi-project catalog (routes project IDs to manifests)
├── registry.yaml         # Default / sample repository manifest and service relationships
├── projects.yaml.example # Reference template for projects catalog
└── registry.yaml.example # Reference template for repository manifests

1. Catálogo Central de Proyectos (data/projects.yaml)

Si gestionas múltiples proyectos en tu máquina, regístralos en data/projects.yaml (o ~/.config/oss-mcp/projects.yaml). Esto te permite apuntar a cualquier proyecto por ID (p. ej. npx oss-mcp index --project ecommerce):

# data/projects.yaml
projects:
  ecommerce:
    name: "E-Commerce Microservices"
    description: "Frontend SPA, API Gateway, Auth Service, and Order Service"
    registry_path: "./data/ecommerce_registry.yaml"
    root_path: "/path/to/ecommerce/workspace"

  analytics:
    name: "Analytics Platform"
    description: "Event streaming and reporting backend"
    registry_path: "/path/to/analytics/registry.yaml"
    root_path: "/path/to/analytics/workspace"

2. Manifiesto de Repositorio (registry.yaml)

Cada proyecto tiene un registry.yaml que define sus servicios individuales, metadatos, puntos de entrada, puertos y relaciones.

# registry.yaml
repos:
  - name: backend-service
    owner: backend-team
    local_path: ./services/backend-service
    description: "REST API server handling auth, database persistence, and business logic"
    tech_stack:
      - Node.js
      - Express
      - PostgreSQL
      - Redis
      - JWT
    entry_point: src/server.js
    port: 4000

  - name: web-frontend
    owner: frontend-team
    local_path: ./services/web-frontend
    description: "Customer SPA built with React and TypeScript"
    tech_stack:
      - React
      - TypeScript
      - Axios
    entry_point: src/index.tsx
    port: 3000

relationships:
  - source: web-frontend
    target: backend-service
    type: api_call
    description: "Frontend makes REST API calls to backend endpoints for data and authentication."

  - source: web-frontend
    target: backend-service
    type: depends_on
    description: "Frontend depends on backend JWT session management and RBAC permissions."

Tipos de Relación Soportados

• api_call: Invocación HTTP / REST / GraphQL desde el origen al destino.

• depends_on: Dependencia arquitectónica o de ciclo de vida (p. ej., sesión compartida, dependencia de contrato).

• event_stream: Mensajería asíncrona (Kafka, RabbitMQ, Redis Pub/Sub, AWS EventBridge).

• shared_resource: Esquema de base de datos compartido, instancia de caché o bucket de almacenamiento.

• submodule: Submódulo Git o referencia de paquete de monorepo.

🎯 Jerarquía de Resolución de Manifiestos

Al ejecutar herramientas o comandos de CLI, oss-mcp determina qué registro cargar mediante una alternativa de 4 niveles:

1. Explicit Flag / Parameter   (--project "ecommerce" or --registry "/path/to/registry.yaml")
   └── 2. Central Projects Catalog (data/projects.yaml or ~/.config/oss-mcp/projects.yaml)
       └── 3. Environment Variable   (export MCP_REGISTRY_PATH="/path/to/registry.yaml")
           └── 4. Workspace Traversal (searching current directory & parent folders for registry.yaml)

💻 Referencia de CLI

🤖 Integración con Asistentes de IA e IDE

oss-mcp proporciona un puente arquitectónico que funciona en conjunto con codebase-memory-mcp.

┌─────────────────────────────────────────────────────────────┐
│                       AI Agent Layer                        │
│   (Antigravity / Claude Code / Cursor / Codex / Roo Code)   │
└──────────────────────────────┬──────────────────────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
 ┌───────────────────────────┐   ┌───────────────────────────┐
 │          oss-mcp          │   │    codebase-memory-mcp    │
 │                           │   │                           │
 │ • Multi-repo discovery    │   │ • Deep AST function index │
 │ • Service topology & port │   │ • Class & symbol search   │
 │ • Cross-repo relationships│   │ • Call graph path tracing │
 │ • Batch index management  │   │ • Source code snippets    │
 └───────────────────────────┘   └───────────────────────────┘

1. 🪐 Google Antigravity (AGY)

A. Configurar el Servidor MCP

Añade oss-mcp al .agents/mcp_config.json de tu proyecto o globalmente en ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Instalar Habilidades y Reglas del Espacio de Trabajo

1. Copia o crea un enlace simbólico del directorio .agents/skills/ en el .agents/skills/ de tu proyecto activo (o globalmente en ~/.gemini/config/skills/).

2. Incluye la regla de enrutamiento multi-repositorio en .agents/AGENTS.md:

   # Multi-Repo Routing
   For any question spanning multiple services or repositories, use the `oss-mcp` MCP server to discover topology with `get_architecture_overview()`, then query `codebase-memory-mcp` scoped to relevant repositories.

C. Comandos Slash y Uso de Antigravity

Escribe estos comandos directamente en el chat de Antigravity:

• /oss setup /path/to/microservices — Escaneo automático del espacio de trabajo, inferencia de stacks y puertos, generación de registry.yaml e indexación por lotes en grafos AST.

• /oss status — Ver tabla de servicios registrados, puertos y recuentos de nodos/bordes del grafo.

• /oss trace checkout flow from UI to backend — Traza ciclos de vida entre servicios de extremo a extremo con diagramas de secuencia.

• /oss remove <project_id> — Anula el registro del proyecto de forma segura y purga los grafos de conocimiento.

2. ⚡ Claude Code (CLI) y Claude Desktop

A. Configuración de Claude Code CLI

Añade el servidor MCP directamente usando el comando claude mcp add:

# Add oss-mcp MCP server
claude mcp add oss-mcp node /absolute/path/to/oss-mcp/src/server.js

O añádelo al .claude.json / settings.json de tu proyecto:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"]
    }
  }
}

B. Configuración de Claude Desktop

Abre tu archivo de configuración de Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Añade la definición del servidor:

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["C:/Telkom/oss-mcp/src/server.js"]
    }
  }
}

C. Instrucción de Flujo de Trabajo de Claude (CLAUDE.md)

Añade esta directriz al CLAUDE.md de tu proyecto para enseñar a Claude cómo enrutar consultas multi-repositorio:

## Multi-Repo Architecture Navigation
When answering questions about cross-service interactions, microservices, or APIs:
1. Call `oss-mcp` tool `get_architecture_overview()` to locate caller/callee services and port contracts.
2. Query `codebase-memory-mcp` (`search_graph`, `trace_path`, `get_code_snippet`) scoped by repository name.
3. Synthesize the end-to-end flow with a Mermaid sequence diagram.

D. Ejemplos de Prompts de Chat en Claude

• "Escanea la carpeta ../services e inicializa el registro multi-repositorio."

• "Muestra todos los microservicios registrados y comprueba si sus grafos AST están indexados."

• "Traza el flujo de autenticación JWT desde el inicio de sesión del frontend hasta la verificación del token en el backend."

3. 🎯 IDE Cursor

A. Añadir Servidor MCP en Cursor

1. Ve a Configuración de Cursor $\rightarrow$ Funciones $\rightarrow$ MCP.

2. Haz clic en + Añadir Nuevo Servidor MCP.

3. Rellena:

   • Nombre: oss-mcp

   • Tipo: command

   • Comando: node /absolute/path/to/oss-mcp/src/server.js

4. Haz clic en Guardar y verifica el punto de estado verde.

B. Reglas de Cursor (.cursorrules o .cursor/rules/multi-repo.mdc)

Crea un archivo de reglas en tu espacio de trabajo:

---
description: Multi-repository architecture navigation rules
globs: *
---
You have access to the `oss-mcp` MCP server.
When the user asks about multi-service architecture or cross-repo communication:
1. Call `get_architecture_overview` to understand service topologies and ports.
2. Trace API calls and dependencies between services.
3. Provide Mermaid sequence diagrams for all cross-service workflows.

C. Ejemplos de Prompts de Chat en Cursor

• @oss-mcp ¿Qué servicios se comunican con el backend de pagos?

• @oss-mcp Escanea este espacio de trabajo multi-repositorio y genera registry.yaml

• ¿Cómo obtiene el cliente frontend los productos de la API de catálogo? Traza la ruta y el manejador.

4. 🧩 Roo Code / Cline / Codex (Extensiones de VS Code)

A. Configurar Ajustes de MCP

Abre cline_mcp_settings.json (o roo_cline_mcp_settings.json):

{
  "mcpServers": {
    "oss-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/oss-mcp/src/server.js"],
      "disabled": false,
      "autoApprove": [
        "get_architecture_overview",
        "get_repo_details",
        "get_related_repos",
        "list_projects"
      ]
    }
  }
}

B. Instrucciones Personalizadas

Añade a tus Instrucciones Personalizadas en la configuración de Cline / Roo Code:

When working across multiple repositories, use the `oss-mcp` MCP tools to inspect service dependencies and ports before making code modifications or answering architectural questions.

🛠️ Análisis Profundo de las Habilidades del Espacio de Trabajo

Las habilidades en .agents/skills/ encapsulan flujos de trabajo completos de extremo a extremo para múltiples repositorios:

🔌 Referencia de Herramientas MCP

Licencia

Distribuido bajo la Licencia MIT.