Repo Therapist 🛋️

Tu base de código se explica a sí misma bajo presión

Este servidor MCP está construido completamente usando Cursor

Repo Therapist es un servidor MCP (Model Context Protocol) que convierte cualquier repositorio en conocimiento consultable y explicable. Haz preguntas sobre tu base de código a través de Cursor y obtén respuestas estructuradas y perspicaces.

Qué hace

Le preguntas a Cursor cosas como:

• "¿Por qué este servicio está estructurado así?"

• "¿Qué se romperá si elimino esto?"

• "¿Qué partes de este repositorio te dan miedo?"

Detrás de escena, Repo Therapist:

• Lee la estructura y los archivos de tu repositorio

• Analiza el historial de git y los patrones de confirmación (commits)

• Correlaciona el código con la frecuencia de cambios

• Identifica puntos críticos de complejidad y riesgos

Related MCP server: Code Understanding MCP Server

Herramientas disponibles

Fuente de verdad: La instantánea

Cuando ejecutas analyze_repo, Repo Therapist crea una instantánea estática: la fuente de verdad autorizada sobre tu repositorio. Esta instantánea incluye:

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

Por qué esto es importante: Los LLM deben citar estos datos de la instantánea, no adivinar. Cuando preguntas "¿Qué lenguajes usa este repositorio?", la respuesta proviene de la instantánea, no de suposiciones del LLM.

Usa get_snapshot para recuperar secciones específicas:

• get_snapshot(section: "files") - Todos los archivos con metadatos

• get_snapshot(section: "languages") - Estadísticas de lenguaje

• get_snapshot(section: "entryPoints") - Puntos de entrada detectados

• get_snapshot(section: "configs") - Archivos de configuración analizados

• get_snapshot(section: "directories") - Estructura de directorios

• get_snapshot() - Resumen de todo

Historiador de Git: La dimensión temporal

El Historiador de Git analiza el historial de confirmaciones para explicar POR QUÉ el código es como es. Aquí es donde deja de ser algo superficial.

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

Esto te permite responder:

• "¿Por qué esto es raro?" → "Porque ha sido reescrito 12 veces en 6 meses."

• "¿Quién es dueño de este archivo?" → "Disputado: 4 personas lo han modificado, ninguna con >30%."

• "¿Con qué debo tener cuidado?" → "Estos 5 archivos son frágiles y propensos a errores."

Usa get_history para recuperar aspectos específicos:

• get_history(section: "churn") - Frecuencia de cambio de archivos y volatilidad

• get_history(section: "authors") - Estadísticas de colaboradores

• get_history(section: "fragile") - Archivos con probabilidad de causar problemas

• get_history(section: "hotPaths") - Rutas críticas frente al núcleo estable

• get_history(section: "timeline") - Eventos clave y patrones de confirmación

• get_history(section: "ownership") - Quién es dueño de qué

• get_history() - Resumen de todo

Usa why_is_this_weird para un análisis de archivo específico:

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

Devuelve una explicación detallada con citas:

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

Configuración

1. Instalar dependencias

cd repo-therapist
npm install

2. Construir el proyecto

npm run build

3. Añadir a Cursor

Abre la configuración de Cursor → MCP → Añadir nuevo servidor MCP:

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

Importante: Reemplaza /FULL/PATH/TO/ con la ruta absoluta real a tu carpeta repo-therapist.

Ejemplo:

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

4. Reiniciar Cursor

Después de añadir la configuración de MCP, reinicia Cursor para que los cambios surtan efecto.

Preguntas frecuentes

¿Necesito ejecutar repo-therapist por separado?

No. Cursor inicia y gestiona automáticamente el servidor MCP por ti. Cuando añades la configuración a los ajustes de MCP de Cursor, Cursor:

• Inicia el proceso node dist/index.js cuando es necesario

• Lo mantiene ejecutándose en segundo plano

• Se comunica con él a través de stdio (entrada/salida estándar)

Solo necesitas construir una vez (npm run build), añadir la configuración y reiniciar Cursor. Eso es todo.

¿Dónde hago las preguntas?

En el chat normal de Cursor (Cmd+L o el panel de chat). La diferencia es cómo preguntas:

• Sin MCP: "¿Qué hace este repositorio?" → Cursor usa sus herramientas integradas

• Con Repo Therapist: "Usa analyze_repo en /path/to/repo" → Cursor llama a la herramienta MCP

Le dices explícitamente a Cursor que use las herramientas de repo-therapist. Cursor las ve como capacidades adicionales que puede usar.

¿Cuál es la diferencia con el chat normal de Cursor?

La diferencia clave: Repo Therapist realiza un análisis estructurado por adelantado y lo almacena, por lo que preguntas como "¿qué archivos cambian más a menudo?" o "¿cuáles son los riesgos?" pueden responderse a partir de datos precalculados en lugar de que Cursor tenga que resolverlo cada vez.

Piénsalo así: Cursor es inteligente pero reactivo. Repo Therapist le da un "documento informativo" sobre tu base de código que puede consultar.

Uso

Una vez configurado, puedes usar Repo Therapist en el chat de Cursor:

Paso 1: Analizar un repositorio

Primero, analiza el repositorio que quieres explorar:

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

Paso 2: Hacer preguntas

Ahora puedes hacer preguntas:

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

Paso 3: Obtener informes

Obtén un resumen:

Use repo_summary to show me an overview

Obtén una evaluación de riesgos:

Use risk_report to identify potential issues

Ejemplos de preguntas

• "¿Qué hace este repositorio?"

• "¿Cómo está estructurado el código?"

• "¿Qué stack tecnológico se está utilizando?"

• "Muéstrame las dependencias"

• "¿Qué archivos son los más grandes?"

• "¿Qué archivos cambian más a menudo?"

• "¿Quiénes son los colaboradores?"

• "¿Cuáles son las confirmaciones recientes?"

• "¿Qué partes te asustan?"

• "¿Qué se romperá si cambio X?"

Desarrollo

Ejecutar en modo desarrollo

npm run dev

Construir para producción

npm run build

Ejecutar pruebas

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

Pautas de prueba

Nota: Añade siempre pruebas unitarias al implementar nuevas funciones.

Las pruebas se encuentran en tests/ y usan Vitest. La estructura de pruebas refleja la fuente:

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

Al añadir una nueva función:

1. Crea pruebas en el subdirectorio tests/ apropiado

2. Usa createTestRepo() de fixtures/setup.ts para pruebas relacionadas con git

3. Limpia los repositorios de prueba con cleanupTestRepo() en afterAll

4. Ejecuta npm test para verificar que todas las pruebas pasen antes de confirmar (commit)

Estructura del proyecto

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

Stack tecnológico

• TypeScript - Base de código con tipado seguro

• @modelcontextprotocol/sdk - Implementación del servidor MCP

• simple-git - Análisis del historial de Git

• ts-morph - Análisis AST de TypeScript/JavaScript (planificado)

• glob - Coincidencia de patrones de archivos

Hoja de ruta

• [ ] Análisis de código basado en AST con ts-morph

• [ ] Persistir el análisis en JSON/SQLite

• [ ] Visualización del grafo de dependencias

• [ ] Detección de vulnerabilidades de seguridad

• [ ] Análisis de cobertura de pruebas

• [ ] Manejadores de preguntas personalizados

Licencia

MIT