MCP Server Codebase Analyzer

Ein produktionsreifer MCP-Server (Model Context Protocol), der TypeScript-Codebasen analysiert, Probleme mit der Code-Integrität erkennt, Systemvorfälle abruft und umsetzbare Sanierungspläne erstellt. Unterstützt dualen Transport (STDIO für lokale Entwicklung, SSE für Cloud-Bereitstellung). Erstellt mit ts-morph, Express und Zod-Validierung.

🚀 Funktionen

Drei Kern-Tools:

1. analyze_codebase_health — Scannt TypeScript-Repositories auf:

   • Große Dateien (potenzielle Kandidaten für Refactoring)

   • Fehlende explizite Funktionstypen (schwache Typisierung)

   • Zirkuläre Abhängigkeiten (architektonische Probleme)

   • Verwendet ts-morph für die Analyse auf AST-Ebene

2. fetch_system_incidents — Gibt strukturierte Vorfalldaten zurück:

   • Mock-Vorfalldaten (perfekt für Tests/Demos)

   • Konfigurierbare Verzögerungen und Fehlermodi

   • LLM-freundliche JSON-Antworten

3. generate_remediation_plan — Erstellt umsetzbare Korrekturpläne:

   • Ursachenanalyse anhand von Stack-Traces

   • Schritt-für-Schritt-Sanierungsschritte

   • Code-Vorschläge und Best Practices

   • Risikobewertung

Alle Tools geben strukturierte Erfolgs-/Fehler-Umschläge zurück, die für die LLM-Verarbeitung konzipiert sind.

Architekturübersicht

flowchart LR
    Client[McpClient] --> Runtime[RuntimeSelector]
    Runtime -->|stdio| Stdio[StdioTransportAdapter]
    Runtime -->|sse| Sse[SseTransportAdapter]
    Stdio --> Server[McpServer]
    Sse --> Server
    Server --> Registry[ToolRegistry]
    Registry --> ToolA[analyze_codebase_health]
    Registry --> ToolB[fetch_system_incidents]
    Registry --> ToolC[generate_remediation_plan]

Lokaler Betrieb (STDIO)

1. Abhängigkeiten installieren:

   • npm install

2. Server starten:

   • npm run dev:stdio

3. Der Server startet über stdin/stdout und ist bereit für lokale MCP-Clients.

Betrieb mit SSE (Express)

1. Umgebung festlegen:

   • TRANSPORT=sse

   • optional: AUTH_TOKEN=your-secret-token

2. Server starten:

   • npm run dev:sse

3. Endpunkte:

   • GET /events für SSE-Stream

   • POST /messages?sessionId=... für MCP JSON-RPC-Nachrichten

Verbindung von Cursor

Für die lokale Nutzung registrieren Sie Nexus-Core als stdio MCP-Server:

• Befehl: node

• Argumente: dist/index.js (nach dem Build) oder tsx src/index.ts (dev)

• Umgebung: TRANSPORT=stdio

Für die gehostete Nutzung konfigurieren Sie Ihren MCP-Client für die Verwendung des SSE-Endpunkts:

• Stream-URL: https://<host>/events

• Nachrichten-URL: https://<host>/messages?sessionId=<session-id>

• Fügen Sie Authorization: Bearer <AUTH_TOKEN> hinzu, falls Token-Authentifizierung aktiviert ist.

Beispiel-Prompts

• "Analysiere mein Repo"

• "Rufe Vorfälle ab"

• "Behebe diesen Fehler"

Umgebungsvariablen

Siehe .env.example für alle unterstützten Einstellungen. Wichtige Kontrollen:

• TRANSPORT: stdio oder sse

• TOOL_TIMEOUT_MS: Hard-Timeout für jeden Tool-Aufruf

• TS_MORPH_MAX_FILES, TS_MORPH_MAX_DEPTH: Analyse-Leitplanken

• INCIDENT_API_TIMEOUT_MS, INCIDENT_API_RETRIES: Kontrollen für externe Abhängigkeiten

• SSE_HEARTBEAT_MS, SSE_SESSION_TTL_MS: SSE-Sitzungslebenszyklus

Produktionsbereitstellung

Docker

• Image bauen: docker build -t nexus-core .

• Container ausführen:

  • docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core

Cloud Run

Verwenden Sie deploy.sh:

PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh

Dieses Skript:

1. Baut das Container-Image

2. Pusht es zu GCR

3. Stellt es auf Cloud Run bereit

Zuverlässigkeit und Fehlermodell

• Alle Tool-Anfragen werden mit Zod validiert.

• Keine Tool-Ausführung gibt unbehandelte Ausnahmen zurück.

• Fehler verwenden einen Standard-Umschlag mit:

  • code

  • message

  • retryable

  • suggestedAction

  • meta (requestId, toolName, Timing)