Repo Therapist 🛋️

Deine Codebasis erklärt sich selbst unter Druck

Dieser MCP-Server wurde vollständig mit Cursor erstellt

Repo Therapist ist ein MCP-Server (Model Context Protocol), der jedes Repository in abfragbares, erklärbares Wissen verwandelt. Stelle Fragen zu deiner Codebasis über Cursor und erhalte strukturierte, aufschlussreiche Antworten.

Was er tut

Du fragst Cursor Dinge wie:

• "Warum ist dieser Dienst so strukturiert?"

• "Was geht kaputt, wenn ich das entferne?"

• "Welche Teile dieses Repos machen dir Sorgen?"

Hinter den Kulissen:

• Liest Repo-Therapist deine Repo-Struktur und Dateien

• Analysiert die Git-Historie und Commit-Muster

• Korreliert Code mit der Änderungshäufigkeit

• Identifiziert Komplexitäts-Hotspots und Risiken

Related MCP server: Code Understanding MCP Server

Verfügbare Tools

Ground Truth: Der Snapshot

Wenn du analyze_repo ausführst, erstellt Repo Therapist einen statischen Snapshot - die maßgebliche Quelle der Wahrheit über dein Repository. Dieser Snapshot enthält:

{
  "files": [...],           // Every file with path, language, line count
  "languages": {...},       // Language breakdown with percentages
  "entryPoints": [...],     // Detected entry points with confidence levels
  "configs": {...},         // Parsed package.json, tsconfig, Dockerfile, CI configs
  "directories": [...]      // Directory structure with inferred purposes
}

Warum das wichtig ist: LLMs müssen diese Snapshot-Daten zitieren, nicht raten. Wenn du fragst "Welche Sprachen verwendet dieses Repo?", kommt die Antwort aus dem Snapshot - nicht dadurch, dass das LLM Annahmen trifft.

Verwende get_snapshot, um bestimmte Abschnitte abzurufen:

• get_snapshot(section: "files") - Alle Dateien mit Metadaten

• get_snapshot(section: "languages") - Sprachstatistiken

• get_snapshot(section: "entryPoints") - Erkannte Einstiegspunkte

• get_snapshot(section: "configs") - Geparste Konfigurationsdateien

• get_snapshot(section: "directories") - Verzeichnisstruktur

• get_snapshot() - Zusammenfassung von allem

Git Historian: Die Zeitdimension

Der Git Historian analysiert die Commit-Historie, um zu erklären, WARUM Code so ist, wie er ist. Hier hört es auf, nur Spielerei zu sein.

{
  "fileChurn": { "auth.ts": { "totalCommits": 47, "churnScore": 85 } },
  "authors": { "auth.ts": ["alice", "bob", "charlie"] },
  "fragileFiles": [{ "path": "auth.ts", "reasons": ["high-churn", "many-authors"] }],
  "hotPaths": [...],
  "stableCore": [...]
}

Dies ermöglicht es dir, Folgendes zu beantworten:

• "Warum ist das seltsam?" → "Weil es in 6 Monaten 12 Mal umgeschrieben wurde."

• "Wem gehört diese Datei?" → "Umstritten - 4 Personen haben sie geändert, keine mit >30%."

• "Worauf sollte ich achten?" → "Diese 5 Dateien sind fragil und fehleranfällig."

Verwende get_history, um bestimmte Aspekte abzurufen:

• get_history(section: "churn") - Änderungshäufigkeit und Volatilität von Dateien

• get_history(section: "authors") - Statistiken zu Mitwirkenden

• get_history(section: "fragile") - Dateien, die wahrscheinlich Probleme verursachen

• get_history(section: "hotPaths") - Häufig genutzte Pfade vs. stabiler Kern

• get_history(section: "timeline") - Wichtige Ereignisse und Commit-Muster

• get_history(section: "ownership") - Wer besitzt was

• get_history() - Zusammenfassung von allem

Verwende why_is_this_weird für eine spezifische Dateianalyse:

Use why_is_this_weird on "src/auth/login.ts"

Liefert eine detaillierte Erklärung mit Zitaten:

# Why is "src/auth/login.ts" the way it is?

## Change History
- Total commits: 47
- Authors: 5 (alice, bob, charlie, dave, eve)
- Churn score: 85 ⚠️ HIGH

## 🔍 Why It's Unusual
**Heavily modified:** This file has been changed 47 times...
**Many hands:** 5 different people have modified this file...

Einrichtung

1. Abhängigkeiten installieren

cd repo-therapist
npm install

2. Das Projekt bauen

npm run build

3. Zu Cursor hinzufügen

Öffne Cursor-Einstellungen → MCP → Neuen MCP-Server hinzufügen:

{
  "mcpServers": {
    "repo-therapist": {
      "command": "node",
      "args": ["/FULL/PATH/TO/repo-therapist/dist/index.js"]
    }
  }
}

Wichtig: Ersetze /FULL/PATH/TO/ durch den tatsächlichen absoluten Pfad zu deinem repo-therapist-Ordner.

Beispiel:

{
  "mcpServers": {
    "repo-therapist": {
      "command": "node",
      "args": ["/Users/saar/Projects/private/repo-therapist/dist/index.js"]
    }
  }
}

4. Cursor neu starten

Starte nach dem Hinzufügen der MCP-Konfiguration Cursor neu, damit die Änderungen wirksam werden.

FAQ

Muss ich repo-therapist separat ausführen?

Nein. Cursor startet und verwaltet den MCP-Server automatisch für dich. Wenn du die Konfiguration zu Cursors MCP-Einstellungen hinzufügst, wird Cursor:

• Den node dist/index.js Prozess bei Bedarf starten

• Ihn im Hintergrund laufen lassen

• Über stdio (Standard-Ein-/Ausgabe) mit ihm kommunizieren

Du musst nur einmal bauen (npm run build), die Konfiguration hinzufügen und Cursor neu starten. Das ist alles.

Wo stelle ich Fragen?

Im normalen Cursor-Chat (Cmd+L oder das Chat-Panel). Der Unterschied liegt darin, wie du fragst:

• Ohne MCP: "Was macht dieses Repo?" → Cursor verwendet seine eingebauten Tools

• Mit Repo Therapist: "Verwende analyze_repo auf /path/to/repo" → Cursor ruft das MCP-Tool auf

Du weist Cursor explizit an, die Repo-Therapist-Tools zu verwenden. Cursor sieht sie als zusätzliche Fähigkeiten, die es nutzen kann.

Was ist der Unterschied zum normalen Cursor-Chat?

Der Hauptunterschied: Repo Therapist führt vorab eine strukturierte Analyse durch und speichert diese, sodass Fragen wie "Welche Dateien ändern sich am häufigsten?" oder "Was sind die Risiken?" aus vorab berechneten Daten beantwortet werden können, anstatt dass Cursor es jedes Mal selbst herausfinden muss.

Stell es dir so vor: Cursor ist intelligent, aber reaktiv. Repo Therapist gibt ihm ein "Briefing-Dokument" über deine Codebasis, auf das es sich beziehen kann.

Verwendung

Sobald konfiguriert, kannst du Repo Therapist im Cursor-Chat verwenden:

Schritt 1: Ein Repo analysieren

Analysiere zuerst das Repository, das du erkunden möchtest:

Use analyze_repo to analyze /path/to/some/repo

Schritt 2: Fragen stellen

Jetzt kannst du Fragen stellen:

Use ask_repo to answer: "What does this repo do?"

Use ask_repo to answer: "Which parts of this repo scare you?"

Use ask_repo to answer: "What will break if I remove the auth module?"

Schritt 3: Berichte erhalten

Erhalte eine Zusammenfassung:

Use repo_summary to show me an overview

Erhalte eine Risikobewertung:

Use risk_report to identify potential issues

Beispiel-Fragen

• "Was macht dieses Repo?"

• "Wie ist der Code strukturiert?"

• "Welcher Tech-Stack wird verwendet?"

• "Zeig mir die Abhängigkeiten"

• "Welche Dateien sind am größten?"

• "Welche Dateien ändern sich am häufigsten?"

• "Wer sind die Mitwirkenden?"

• "Was sind die letzten Commits?"

• "Welche Teile machen dir Sorgen?"

• "Was geht kaputt, wenn ich X ändere?"

Entwicklung

Im Entwicklungsmodus ausführen

npm run dev

Für die Produktion bauen

npm run build

Tests ausführen

npm test              # Run all tests
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

Test-Richtlinien

Hinweis: Füge bei der Implementierung neuer Funktionen immer Unit-Tests hinzu.

Tests befinden sich in tests/ und verwenden Vitest. Die Teststruktur spiegelt die Quelle wider:

tests/
├── fixtures/           # Test utilities and mock repos
│   └── setup.ts        # Helper functions for creating test repos
├── scanner/            # Scanner module tests
├── historian/          # Historian module tests
├── tools/              # Tool tests
└── cache.test.ts       # Cache tests

Beim Hinzufügen einer neuen Funktion:

1. Erstelle Tests im entsprechenden tests/-Unterverzeichnis

2. Verwende createTestRepo() aus fixtures/setup.ts für Git-bezogene Tests

3. Bereinige Test-Repos mit cleanupTestRepo() in afterAll

4. Führe npm test aus, um zu überprüfen, ob alle Tests bestehen, bevor du committest

Projektstruktur

repo-therapist/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cache.ts              # In-memory repo cache
│   ├── types.ts              # TypeScript interfaces
│   ├── scanner/              # Static snapshot engine (Step 2)
│   │   ├── index.ts          # Scanner exports
│   │   ├── types.ts          # Snapshot type definitions
│   │   └── scan-repo.ts      # Repository scanner
│   ├── historian/            # Git history analyzer (Step 3)
│   │   ├── index.ts          # Historian exports
│   │   ├── types.ts          # History type definitions
│   │   └── analyze-history.ts # Git history analysis
│   └── tools/
│       ├── analyze-repo.ts   # Repository analyzer (orchestrates all)
│       ├── get-snapshot.ts   # Snapshot retrieval (ground truth)
│       ├── get-history.ts    # History retrieval (time dimension)
│       ├── ask-repo.ts       # Question answering
│       ├── repo-summary.ts   # Summary generator
│       └── risk-report.ts    # Risk assessment
├── tests/                    # Unit tests
│   ├── fixtures/             # Test utilities
│   ├── scanner/              # Scanner tests
│   ├── historian/            # Historian tests
│   └── tools/                # Tool tests
├── package.json
├── tsconfig.json
├── vitest.config.ts          # Test configuration
└── README.md

Tech-Stack

• TypeScript - Typsichere Codebasis

• @modelcontextprotocol/sdk - MCP-Server-Implementierung

• simple-git - Analyse der Git-Historie

• ts-morph - TypeScript/JavaScript AST-Parsing (geplant)

• glob - Dateimuster-Abgleich

Roadmap

• [ ] AST-basierte Code-Analyse mit ts-morph

• [ ] Analyse in JSON/SQLite persistieren

• [ ] Visualisierung des Abhängigkeitsgraphen

• [ ] Erkennung von Sicherheitslücken

• [ ] Analyse der Testabdeckung

• [ ] Benutzerdefinierte Frage-Handler

Lizenz

MIT