Multi-Repo Architecture Hub (oss-mcp)

Ein erweiterbarer Multi-Repo-Architektur-Router und Model Context Protocol (MCP)-Server, geschrieben in Node.js (ESM). Entwickelt für die abteilungsübergreifende Abhängigkeitserkennung, topologisches Routing und die Batch-AST-Indexierung in Verbindung mit codebase-memory-mcp.

⚡ Schnellstart (3-Minuten-Setup)

1. Voraussetzungen

Stellen Sie sicher, dass Node.js (>= 18) und codebase-memory-mcp global installiert sind:

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

2. Klonen und Abhängigkeiten installieren

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

3. Beliebigen Multi-Repo-Arbeitsbereich initialisieren

Weisen Sie oss-mcp auf Ihr Microservices-Verzeichnis. Es scannt die Repositories, generiert registry.yaml und indexiert den Code automatisch in AST-Wissensgraphen:

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

Related MCP server: Codebase Contextifier 9000

🚀 Hauptfunktionen

1. Multi-Projekt-Dynamische Erkennung: Löst Repository-Manifeste (registry.yaml) dynamisch aus CLI-Parametern, zentralen Katalogen (data/projects.yaml), Umgebungsvariablen oder der Arbeitsbereichshierarchie auf.

2. Automatisierter Struktur- und Abhängigkeitsscanner: Durchsucht rekursiv Verzeichnisbäume über mehrere Technologie-Stacks (Node.js, Express, React, Python, FastAPI, Java, Go) und erkennt Einstiegspunkte, Ports und HTTP-/Event-Beziehungen zwischen Diensten.

3. Automatisierte Batch-AST-Indexierung: Orchestriert die codebase-memory-mcp-AST-Graph-Indexierung über alle Dienste in einem Projektmanifest mit einem einzigen Befehl.

4. Strukturierte MCP-Schnittstelle: Stellt standardisierte Tools für KI-Agenten bereit, um abteilungsübergreifende Architekturen abzufragen, End-to-End-Anfragelebenszyklen zu verfolgen und Multi-Service-Grenzen zu navigieren.

📁 Arbeiten mit dem data/-Verzeichnis

Das data/-Verzeichnis bietet eine zentrale Projektverwaltung für Umgebungen, die mehrere unterschiedliche Microservice-Projekte oder -Systeme hosten.

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. Zentraler Projektkatalog (data/projects.yaml)

Wenn Sie mehrere Projekte auf Ihrem Rechner verwalten, registrieren Sie sie in data/projects.yaml (oder ~/.config/oss-mcp/projects.yaml). So können Sie jedes Projekt per ID ansprechen (z. B. 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. Repository-Manifest (registry.yaml)

Jedes Projekt hat eine registry.yaml, die seine einzelnen Dienste, Metadaten, Einstiegspunkte, Ports und Beziehungen definiert.

# 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."

Unterstützte Beziehungstypen

• api_call: HTTP / REST / GraphQL-Aufruf von Quelle zu Ziel.

• depends_on: Architektonische oder Lebenszyklus-Abhängigkeit (z. B. gemeinsame Sitzung, Vertragsabhängigkeit).

• event_stream: Asynchrone Nachrichtenübermittlung (Kafka, RabbitMQ, Redis Pub/Sub, AWS EventBridge).

• shared_resource: Gemeinsames Datenbankschema, Cache-Instanz oder Speicher-Bucket.

• submodule: Git-Submodul oder Monorepo-Paketreferenz.

🎯 Manifest-Auflösungshierarchie

Bei der Ausführung von Tools oder CLI-Befehlen bestimmt oss-mcp, welches Registry geladen werden soll, über eine 4-stufige Fallback-Logik:

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)

💻 CLI-Referenz

🤖 KI-Assistenten- und IDE-Integration

oss-mcp bietet eine architektonische Brücke, die in Verbindung mit codebase-memory-mcp funktioniert.

┌─────────────────────────────────────────────────────────────┐
│                       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. MCP-Server konfigurieren

Fügen Sie oss-mcp zur .agents/mcp_config.json Ihres Projekts oder global zu ~/.gemini/config/mcp_config.json hinzu:

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

B. Arbeitsbereichs-Skills und Regeln installieren

1. Kopieren oder verlinken Sie das .agents/skills/-Verzeichnis in das .agents/skills/-Verzeichnis Ihres aktiven Projekts (oder global zu ~/.gemini/config/skills/).

2. Fügen Sie die Multi-Repo-Routing-Regel in .agents/AGENTS.md ein:

   # 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. Antigravity-Slash-Befehle und Verwendung

Geben Sie diese Befehle direkt im Antigravity-Chat ein:

• /oss setup /path/to/microservices — Arbeitsbereich automatisch scannen, Stacks & Ports ableiten, registry.yaml generieren und in AST-Graphen batch-indexieren.

• /oss status — Tabelle der registrierten Dienste, Ports und Graph-Knoten-/Kantenanzahl anzeigen.

• /oss trace checkout flow from UI to backend — End-to-End-Lebenszyklen über Dienste hinweg mit Sequenzdiagrammen verfolgen.

• /oss remove <project_id> — Projekt sicher abmelden und Wissensgraphen bereinigen.

2. ⚡ Claude Code (CLI) & Claude Desktop

A. Claude Code CLI-Setup

Fügen Sie den MCP-Server direkt mit dem Befehl claude mcp add hinzu:

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

Oder fügen Sie ihn zur .claude.json / settings.json Ihres Projekts hinzu:

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

B. Claude Desktop-Setup

Öffnen Sie Ihre Claude-Desktop-Konfigurationsdatei:

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

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

Fügen Sie die Serverdefinition hinzu:

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

C. Claude-Workflow-Anweisung (CLAUDE.md)

Fügen Sie diese Richtlinie zur CLAUDE.md Ihres Projekts hinzu, um Claude beizubringen, wie Multi-Repo-Abfragen geroutet werden:

## 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. Beispiel-Chat-Prompts in Claude

• "Scanne den Ordner ../services und initialisiere das Multi-Repo-Registry."

• "Zeige alle registrierten Microservices und prüfe, ob ihre AST-Graphen indexiert sind."

• "Verfolge den JWT-Authentifizierungsfluss vom Frontend-Login bis zur Token-Verifizierung im Backend."

3. 🎯 Cursor IDE

A. MCP-Server in Cursor hinzufügen

1. Gehen Sie zu Cursor-Einstellungen $\rightarrow$ Features $\rightarrow$ MCP.

2. Klicken Sie auf + Neuen MCP-Server hinzufügen.

3. Füllen Sie aus:

   • Name: oss-mcp

   • Typ: command

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

4. Klicken Sie auf Speichern und überprüfen Sie den grünen Statuspunkt.

B. Cursor-Regeln (.cursorrules oder .cursor/rules/multi-repo.mdc)

Erstellen Sie eine Regeldatei in Ihrem Arbeitsbereich:

---
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. Beispiel-Chat-Prompts in Cursor

• @oss-mcp Welche Dienste kommunizieren mit dem Zahlungs-Backend?

• @oss-mcp Scanne diesen Multi-Repo-Arbeitsbereich und generiere registry.yaml

• Wie ruft der Frontend-Client Produkte von der Katalog-API ab? Verfolge die Route und den Handler.

4. 🧩 Roo Code / Cline / Codex (VS-Code-Erweiterungen)

A. MCP-Einstellungen konfigurieren

Öffnen Sie cline_mcp_settings.json (oder 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. Benutzerdefinierte Anweisungen

Fügen Sie Ihren benutzerdefinierten Anweisungen in den Cline-/Roo-Code-Einstellungen hinzu:

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.

🛠️ Arbeitsbereichs-Skills im Detail

Skills im .agents/skills/-Verzeichnis kapseln vollständige End-to-End-Multi-Repo-Workflows:

🔌 MCP-Tools-Referenz

Lizenz

Verteilt unter der MIT-Lizenz.