Corpus

Corpus bündelt die Dokumentation aller Repositorys deiner Organisation, erstellt eine Live-Systemkarte mithilfe der Katalog-Entitäten von Spotify Backstage und stellt alles hinter einen leistungsstarken Model Context Protocol (MCP)-Server.

Gib deinen KI-Agenten (Claude, Copilot usw.) den ganzheitlichen Kontext, den sie brauchen, um deine Architektur, Service-Verantwortlichkeiten, Doku und Code zu verstehen – alles an einem Ort!

✨ Funktionen

• 🗺️ Automatisch generierter Entitätsgraph: Parst vollständig Entitäten aus Backstage-catalog-info.yaml (Components, APIs, Systems, Users) und erzeugt einen bidirektionalen Beziehungsgraphen mithilfe bekannter Beziehungen (z. B. ownerOf/ownedBy, providesApi/apiProvidedBy).

• 📖 Zentrale Dokumentsuche: Schnelle lexikalische Suche über README.md, docs/**/*.md, adr/**/*.md und KI-Skills in deiner gesamten Organisation.

• 🔍 Globale Codesuche: Stichwortsuche über alle Repositorys der Organisation über die GitHub Code Search API.

• 💬 Issue- & PR-Kontext: Leitet an die GitHub-Such-API weiter, um Diskussionen, PRs und Issues in der gesamten Organisation zu finden (search_issues_and_prs).

• 📄 Dateilesen: Direkter Zugriff auf exakte Dateiinhalte aus jedem Repository-Zweig oder Commit.

• ⚙️ API-Schema-Aggregation: Indiziert automatisch openapi- und swagger-Dateien, sodass Agenten Endpunktverträge sofort abrufen können (list_api_schemas).

• 🚀 Start ohne Konfiguration: Führt fehlende Builds beim Start automatisch aus. Wenn du Anmeldedaten hast, starte einfach npm start und der Server ruft alles ab und indiziert es.

• 🐞 Lückenmeldung: Optionale Möglichkeit, ein GitHub-Issue anzulegen, wenn die Doku die Frage eines Agenten nicht beantworten kann.

Related MCP server: repovine

🛠️ Schnellstart

1. Voraussetzungen

• Node.js v22+

• GitHub PAT (Persönliches Zugriffstoken):

  • Classic Token: Benötigt repo (zum Lesen privater Repositorys) und read:org (beim Abfragen einer Organisation).

  • Fine-Grained Token: Benötigt Contents: Read-only und Metadata: Read-only für alle Repositorys. Wenn du ENABLE_GAP_REPORTING aktivierst, benötigst du außerdem Issues: Read & Write auf dem Ziel-Repository.

2. Umgebung konfigurieren

Erstelle eine .env-Datei im Stammverzeichnis:

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. Erstellen & Ausführen

Lokale Ausführung:

npm install
npm run build
npm start

Hinweis: npm start startet automatisch die Skripte zur Corpus- und Systemkarten-Generierung, falls sie noch nicht ausgeführt wurden.

Docker-Ausführung:

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

🤖 Registrierung bei KI-Clients

Antigravity

Antigravity unterstützt MCP nativ. Konfiguriere den Server global, indem du ihn zu ~/.gemini/config/mcp_config.json hinzufügst:

{
  "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

Füge dies zu deiner claude_desktop_config.json hinzu:

{
  "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

Führe Folgendes im Projektstamm aus:

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

🏗️ Architektur & Befehle

• npm run build:corpus: Durchsucht die GitHub-Organisation und lädt Doku + Katalogdaten in corpus/manifest.json herunter.

• npm run build:map: Wandelt das Manifest in einen aktiven Abhängigkeitsgraphen um, der in corpus/system-map.yaml gespeichert wird.

• npm run build: Führt die vollständige Pipeline aus und kompiliert TypeScript.

• npm run test: Führt Unit-Tests mit dem nativen Node.js-Testrunner aus.

🧩 Systemkarte & catalog-info.yaml

Corpus erzeugt automatisch einen globalen Abhängigkeitsgraphen der Dienste deiner Organisation. Um an der Systemkarte teilzunehmen, sollte jedes Repository eine catalog-info.yaml-Datei im Stammverzeichnis enthalten, die dem Backstage-Deskriptorformat entspricht.

Da Corpus wie ein Backstage-Katalogprozessor fungiert, extrahiert es jeden Entitätstyp (Component, API, System, Group) und verdrahtet automatisch bidirektionale Beziehungen. Wenn deine Component owner: group:auth-team und providesApis: [api:auth-api] definiert, erzeugt Corpus automatisch die Kanten ownedBy/ownerOf und providesApi/apiProvidedBy, sodass KI-Agenten den gesamten Servicegraphen deiner Organisation nativ durchlaufen können.

Beispiel 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

💡 Bewährte Praktiken & Philosophie

Um das absolute Maximum aus Corpus und deinen KI-Agenten herauszuholen, empfehlen wir die folgenden Praktiken im Ökosystem:

1. Halte die Doku nah am Code: Die Dokumentation sollte im Repository direkt neben dem Code liegen. Der beste Ort, um zu dokumentieren, wie ein System funktioniert, ist direkt neben dem System selbst. Corpus erfasst automatisch docs/**/*.md und adr/**/*.md in allen deinen Repositorys.

2. Zentrales Wiki-Repository: Wenn du unternehmensweite Architekturentscheidungen, RFCs oder Codequalitätsstandards hast, die mehrere Systeme betreffen, bewahre sie in einem zentralen „Wiki“-Repository als Markdown-Dateien auf. Corpus wird sie perfekt aggregieren.

3. Synergie mit Spotify Backstage: Wenn du Backstage verwendest, ist Corpus der perfekte Begleiter.

   • Backstage ist ein internes Entwicklerportal (IDP), das für Menschen gebaut wurde und eine umfangreiche Weboberfläche bietet.

   • Corpus ist ein IDP, das für KI-Agenten gebaut wurde und denselben Kontext über MCP bereitstellt. Da Corpus standardmäßige catalog-info.yaml-Dateien nativ parst, gibt es keine doppelte Arbeit. Wenn deine Teams bereits dependsOn-, lifecycle- und owner-Tags für Backstage definieren, sammelt Corpus sie automatisch ein und übersetzt sie in einen aktiven Graphen, den KI-Agenten durchlaufen können.

4. Häufige automatisierte Aktualisierungen: Das Corpus soll eine lebendige, atmende Momentaufnahme deiner Organisation sein. Durch Ausführen der Build-Skripte (npm run build) wird das Corpus lokal neu abgerufen und neu erstellt. Da es sich um ein einfaches API-Scraping-Skript handelt, verbraucht es null LLM-Tokens zum Erstellen. Idealerweise sollte Corpus zentral in deinem Unternehmen bereitgestellt werden, wobei ein Cron-Job (wie eine GitHub Action) das manifest.json jede Nacht neu erstellt und es an deine Entwickler verteilt.

🤝 Mitwirken

Wir freuen uns über Beiträge! Weitere Informationen zum Einstieg, zur Einrichtung deiner Entwicklungsumgebung und zum Einreichen von Pull Requests findest du in unseren Beitragsrichtlinien.

Dieses Projekt setzt Conventional Commits durch. Ein Pre-Commit-Hook formatiert deinen Code automatisch mit Prettier und prüft ihn mit ESLint.

Weitere Details findest du im Setup-Skill-Guide.

📄 Lizenz

Corpus ist kostenlos nutzbar. Das gesamte geistige Eigentum liegt bei Sayam Hussain.

Dieses Projekt ist unter der MIT-Lizenz lizenziert.