MCP Intelligence Context

Ein Repository-Intelligence-MCP-Server, der die Dateien, Symbole, Importe und den Abhängigkeitsgraphen einer Codebasis indexiert und Copilot/Agenten ein kleines, fokussiertes Kontextpaket bereitstellt, anstatt sie das gesamte Repository durchsuchen zu lassen.

Warum

Wenn ein Agent eine mehrdeutige Frage zu einem großen Repo erhält, muss er oft wiederholt Verzeichnisse auflisten, irrelevante Dateien öffnen und die Struktur neu ableiten, bevor er den relevanten Code findet – das verbrennt Tokens und Zeit. Dieses Projekt baut einen persistenten, inkrementell aktualisierten Index des Repos (Dateien, Symbole, Importe, reverse Abhängigkeiten) auf und stellt MCP-Tools bereit, die nur den für eine Abfrage relevanten Kontext mit einem ungefähren Token-Budget zurückgeben.

Related MCP server: lens

So funktioniert es

1. index_repository durchläuft das Repo (unter Beachtung von .gitignore), parst Python-Dateien (über ast) und JS/TS-Dateien (über leichte Regex-Heuristiken) auf Funktionen/Klassen/Methoden/Importe/Exporte und baut einen Graphen der reverse Abhängigkeiten auf. Der Index wird unter .mcp_intel_cache/index.json zwischengespeichert und inkrementell aktualisiert (nur geänderte Dateien werden neu geparst, basierend auf mtime/Größe).

2. search_code / get_relevant_context bewerten Dateien nach Symbolname, Dateiname, Docstring/Zusammenfassung und Import-Treffern (lexikalische/Symbolsuche – keine Embeddings in diesem MVP) und geben ein token-budgetiertes Kontextpaket zurück: Symboltabellen + kleine Code-Auszüge, nicht ganze Dateien. get_relevant_context meldet außerdem einen token_savings-Vergleich gegenüber einer naiven Voll-Repo-Scan-Baseline, sodass die Einsparungen in der eigenen Antwort des Tools sichtbar sind.

3. get_file_summary / get_dependencies ermöglichen einem Agenten, in die Symbole einer bestimmten Datei oder deren Auswirkungsbereich (Importeure/Importe) einzutauchen, ohne die gesamte Datei zu lesen.

4. Tools melden eine Veraltungswarnung, wenn der zwischengespeicherte Index älter als 5 Minuten ist und kein Live-Watcher aktiv ist. In der Praxis startet der erste Tool-Aufruf für ein Repo einen Hintergrund-Datei-Watcher (über watchdog), der Erstellungs-/Änderungs-/Lösch-Ereignisse sofort auf den In-Memory-Index anwendet, sodass der Index kontinuierlich aktuell bleibt, während sich der Code ändert – kein manuelles Reindexieren während einer Sitzung erforderlich. Der On-Disk-Cache wird mit einem Debounce (~2s) geleert, sodass schnelles Speichern nicht zu einem Schreibvorgang pro Tastendruck führt.

Repository-Struktur

src/mcp_intelligence_context/   Python MCP server package
  walker.py                     gitignore-aware file walker
  parsers/                      Python (ast) and JS/TS (regex) symbol extraction
  indexer.py                    builds/caches the RepoIndex, resolves imports
  watcher.py                    background file watcher that keeps the index live
  search.py                     lexical/symbol search + reverse-dep lookups
  context_builder.py            token-budgeted context package assembly
  server.py                     MCP tool definitions (stdio server)
vscode-extension/                VS Code extension wrapper (setup/reindex/status commands)
scripts/                         one-command bootstrap for new users

Schnellstart (Neue Benutzer)

Wenn Sie neu bei MCP sind und dies schnell in VS Code zum Laufen bringen möchten:

git clone https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git
cd MCP-INTELLIGENCE-CONTEXT
bash scripts/setup_mcp_workspace.sh

Was dieses Skript tut:

1. Installiert (oder aktualisiert) mcp-intelligence-context mit pipx.

2. Schreibt .vscode/mcp.json für diesen Workspace.

3. Beschränkt die Indexierung auf den aktuellen Workspace-Ordner, indem MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder} gesetzt wird.

Dann in VS Code:

1. Befehlspalette -> MCP: List Servers.

2. Starten/Neustarten von mcp-intelligence-context.

3. Im Copilot-Chat-Tool-Auswähler mcp-intelligence-context aktivieren.

Wenn das Skript meldet, dass pipx fehlt, installieren Sie es einmal:

brew install pipx
pipx ensurepath

Den MCP-Server eigenständig ausführen

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context        # or: python -m mcp_intelligence_context.server

Weisen Sie das zu indexierende Repo zu, indem Sie MCP_INTEL_REPO_ROOT setzen, oder übergeben Sie repo_root explizit an einen beliebigen Tool-Aufruf (Standard ist das aktuelle Arbeitsverzeichnis des Servers).

Installation ohne Klonen dieses Repos

Andere Benutzer benötigen keinen lokalen Checkout – installieren Sie direkt aus dem Git-Repository (oder von PyPI, sobald es dort veröffentlicht ist):

python3 -m venv .venv
.venv/bin/pip install "git+https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git"
# once published: .venv/bin/pip install mcp-intelligence-context

Das Konsolenskript mcp-intelligence-context und die Umgebungsvariable MCP_INTEL_REPO_ROOT funktionieren in beiden Fällen genau gleich – nur die Quelle für pip install unterscheidet sich.

Bei einem MCP-Client registrieren (z. B. VS Code)

Fügen Sie im Ziel-Workspace zu .vscode/mcp.json hinzu:

{
  "servers": {
    "mcp-intelligence-context": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_intelligence_context.server"],
      "env": { "MCP_INTEL_REPO_ROOT": "${workspaceFolder}" }
    }
  }
}

VS-Code-Erweiterung

vscode-extension/ bündelt einen dünnen Wrapper mit drei Befehlen:

• MCP Intelligence: Setup Server – erstellt eine venv und installiert das Python-Paket, schreibt dann den obigen .vscode/mcp.json-Eintrag.

• MCP Intelligence: Reindex Repository – erzwingt eine Neu-Indexierung des geöffneten Workspace.

• MCP Intelligence: Show Status – gibt die Dateianzahl, den Git-Commit und das Alter des zwischengespeicherten Index aus.

Standardmäßig installiert "Setup Server" das Paket aus dem Git-Repository dieses Projekts in eine venv unter dem privaten Speicher der Erweiterung – kein lokaler Klon erforderlich. Zwei Einstellungen steuern dies:

• mcpIntelligenceContext.serverPath – auf einen lokalen bearbeitbaren Checkout zeigen (für die Entwicklung an diesem Monorepo); andernfalls leer lassen.

• mcpIntelligenceContext.pythonPackageSource – das pip-Installationsziel überschreiben (z. B. ein PyPI-Paketname), wenn serverPath leer ist.

Zum Erstellen:

cd vscode-extension
npm install
npm run compile

Dann drücken Sie F5 in VS Code (mit geöffnetem vscode-extension/), um einen Extension Development Host zu starten.

Verfügbare MCP-Tools

Bewerten, ob dies tatsächlich hilft

eval/ enthält einen kleinen, ehrlichen Benchmark gegen den eigenen Code dieses Repos (keine LLM-Aufrufe, keine erfundenen Zahlen): 10 handgeschriebene Abfragen mit bekannten Ground-Truth-Dateien, die unser indexiertes Tool mit einer naiven Baseline vergleichen (Baum auflisten, grep, passende ganze Dateien lesen).

.venv/bin/python eval/run_eval.py

Es berichtet hit@1/hit@3 (zeigt das Top-Ergebnis auf die richtige Datei), durchschnittliche Token-Reduktion und Latenz. Dies misst nur die Abruf-/Token-Mechanik – es misst nicht, ob eine echte Copilot-Antwort tatsächlich besser ist, da dafür Live-Modellaufrufe erforderlich sind.

Aktuelle Einschränkungen (MVP)

• JS/TS-Parsing basiert auf Regex (kein vollständiger AST), daher kann ungewöhnliche Syntax übersehen werden. Python-Parsing verwendet das Standardmodul ast und ist exakt.

• Die Suche ist nur lexikalisch/symbolbasiert (mit Stoppwort-Filterung und akkumulierter Multi-Signal-Bewertung); noch keine Embeddings/semantische Suche.

• Der Datei-Watcher wendet Änderungen pro Datei an, durchläuft aber .gitignore-Änderungen selbst nicht zur Laufzeit erneut – wenn .gitignore bearbeitet wird, führen Sie index_repository einmal mit refresh=true aus, um die neuen Regeln zu übernehmen.

Sicherheitsüberlegungen vor breiterer/Produktionsnutzung

Bereits behoben:

• Shell-Injection – die VS-Code-Erweiterung interpolierte zuvor Workspace-Einstellungen in Shell-Befehlszeichenfolgen; sie verwendet jetzt execFile mit Argument-Arrays (keine Shell) und weigert sich, "Setup Server" in nicht vertrauenswürdigen Workspaces auszuführen.

• Symlink-Escape – der Walker überspringt Symlinks, die außerhalb der Repo-Wurzel auflösen (blockiert einen platzierten Symlink, der Dateien wie /etc/passwd offenlegt).

• Geheimnis-Leckage – Dateinamen, die gängigen Anmeldeinformationsmustern entsprechen (.env, *.pem, id_rsa, credentials.json usw., siehe SENSITIVE_FILENAME_PATTERNS in config.py), werden übersprungen, auch wenn sie nicht gitignored sind, sodass ihre Inhalte nicht in Tool-Ausgaben gelangen können.

• Absturz durch beschädigten Cache – eine fehlerhafte/manipulierte .mcp_intel_cache/index.json löst jetzt einen sauberen Neuaufbau aus, anstatt den Server beim Start zum Absturz zu bringen.

• ReDoS – der JS/TS-Regex-Parser überspringt pathologisch lange einzelne Zeilen (minifizierte Dateien), um katastrophales Backtracking-DoS zu vermeiden.

• Uneingeschränktes repo_root – setzen Sie MCP_INTEL_ALLOWED_ROOTS (eine :-getrennte Liste absoluter Pfade), um einzuschränken, welche Verzeichnisse der Server indexieren darf; standardmäßig nicht gesetzt, um das heutige flexible Einzelbenutzerverhalten zu erhalten.

Noch architektonisch, nicht vollständig gelöst – vor der Bereitstellung über einen einzelnen lokalen Benutzer hinaus lesen:

• Nicht sicher als gemeinsamer/Multi-Tenant-Netzwerkdienst. Dies ist als lokaler, ein-Prozess-pro-Benutzer- stdio-Server konzipiert. Die In-Memory-Index-/Watcher-Caches haben keine Benutzerisolierung oder Authentifizierung. Setzen Sie dies nicht als gemeinsamen HTTP/SSE-Endpunkt aus, ohne pro Aufrufer Sandboxing und Authentifizierung hinzuzufügen.

• Abhängigkeiten sind nicht gepinnt (nur >=) – pinnen Sie exakte Versionen oder verwenden Sie eine Lock-Datei für reproduzierbare, geprüfte Produktionsinstallationen (das hat uns bereits einmal mit einer brechenden API-Änderung von mcp 1.x → 2.0 gebissen).

• Noch keine automatisierten Regressionstests für diese Codebasis selbst – Änderungen werden derzeit über das manuelle eval/-Harness und Ad-hoc-Läufe verifiziert, nicht über eine CI-gesteuerte Testsuite.