Repo Therapist 🛋️

Ваша кодовая база объясняет сама себя под давлением

Этот MCP-сервер полностью создан с использованием Cursor

Repo Therapist — это MCP-сервер (Model Context Protocol), который превращает любой репозиторий в базу знаний, доступную для запросов и объяснений. Задавайте вопросы о вашей кодовой базе через Cursor и получайте структурированные, глубокие ответы.

Что он делает

Вы спрашиваете Cursor о вещах вроде:

• «Почему этот сервис структурирован именно так?»

• «Что сломается, если я удалю это?»

• «Какие части этого репозитория пугают тебя?»

За кулисами Repo Therapist:

• Читает структуру вашего репозитория и файлы

• Анализирует историю git и паттерны коммитов

• Сопоставляет код с частотой изменений

• Выявляет «горячие точки» сложности и риски

Related MCP server: Code Understanding MCP Server

Доступные инструменты

Источник истины: Снимок (Snapshot)

Когда вы запускаете analyze_repo, Repo Therapist создает статический снимок — авторитетный источник истины о вашем репозитории. Этот снимок включает:

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

Почему это важно: LLM должны ссылаться на данные этого снимка, а не гадать. Когда вы спрашиваете «Какие языки использует этот репозиторий?», ответ берется из снимка, а не из предположений LLM.

Используйте get_snapshot для получения конкретных разделов:

• get_snapshot(section: "files") — Все файлы с метаданными

• get_snapshot(section: "languages") — Статистика языков

• get_snapshot(section: "entryPoints") — Обнаруженные точки входа

• get_snapshot(section: "configs") — Разобранные конфигурационные файлы

• get_snapshot(section: "directories") — Структура директорий

• get_snapshot() — Сводка всего

Git Historian: Временное измерение

Git Historian анализирует историю коммитов, чтобы объяснить, ПОЧЕМУ код выглядит именно так. Здесь это перестает быть просто игрушкой.

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

Это позволяет вам ответить на вопросы:

• «Почему это выглядит странно?» → «Потому что это переписывалось 12 раз за 6 месяцев.»

• «Кто владелец этого файла?» → «Спорно — 4 человека вносили изменения, ни у кого нет >30%.»

• «Чего мне стоит опасаться?» → «Эти 5 файлов хрупкие и подвержены ошибкам.»

Используйте get_history для получения конкретных аспектов:

• get_history(section: "churn") — Частота изменений файлов и волатильность

• get_history(section: "authors") — Статистика участников

• get_history(section: "fragile") — Файлы, которые могут вызвать проблемы

• get_history(section: "hotPaths") — «Горячие» пути против стабильного ядра

• get_history(section: "timeline") — Ключевые события и паттерны коммитов

• get_history(section: "ownership") — Кто чем владеет

• get_history() — Сводка всего

Используйте why_is_this_weird для анализа конкретного файла:

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

Возвращает подробное объяснение с цитатами:

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

Настройка

1. Установка зависимостей

cd repo-therapist
npm install

2. Сборка проекта

npm run build

3. Добавление в Cursor

Откройте настройки Cursor → MCP → Добавить новый MCP-сервер:

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

Важно: Замените /FULL/PATH/TO/ на фактический абсолютный путь к вашей папке repo-therapist.

Пример:

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

4. Перезапуск Cursor

После добавления конфигурации MCP перезапустите Cursor, чтобы изменения вступили в силу.

Часто задаваемые вопросы

Нужно ли мне запускать repo-therapist отдельно?

Нет. Cursor автоматически запускает и управляет MCP-сервером за вас. Когда вы добавляете конфигурацию в настройки MCP Cursor, Cursor будет:

• Запускать процесс node dist/index.js при необходимости

• Держать его запущенным в фоновом режиме

• Общаться с ним через stdio (стандартный ввод/вывод)

Вам нужно только один раз собрать проект (npm run build), добавить конфигурацию и перезапустить Cursor. Это всё.

Где мне задавать вопросы?

В обычном чате Cursor (Cmd+L или панель чата). Разница в том, как вы спрашиваете:

• Без MCP: «Что делает этот репозиторий?» → Cursor использует свои встроенные инструменты

• С Repo Therapist: «Используй analyze_repo для /path/to/repo» → Cursor вызывает инструмент MCP

Вы явно говорите Cursor использовать инструменты repo-therapist. Cursor видит их как дополнительные возможности, которые он может использовать.

В чем разница по сравнению с обычным чатом Cursor?

Ключевое отличие: Repo Therapist выполняет структурированный анализ заранее и сохраняет его, поэтому на вопросы вроде «какие файлы меняются чаще всего?» или «каковы риски?» можно ответить на основе предварительно вычисленных данных, а не заставлять Cursor каждый раз разбираться в этом заново.

Думайте об этом так: Cursor умный, но реактивный. Repo Therapist дает ему «брифинг-документ» о вашей кодовой базе, на который он может ссылаться.

Использование

После настройки вы можете использовать Repo Therapist в чате Cursor:

Шаг 1: Анализ репозитория

Сначала проанализируйте репозиторий, который хотите изучить:

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

Шаг 2: Задавайте вопросы

Теперь вы можете задавать вопросы:

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

Шаг 3: Получение отчетов

Получить сводку:

Use repo_summary to show me an overview

Получить оценку рисков:

Use risk_report to identify potential issues

Примеры вопросов

• «Что делает этот репозиторий?»

• «Как структурирован код?»

• «Какой технологический стек используется?»

• «Покажи мне зависимости»

• «Какие файлы самые большие?»

• «Какие файлы меняются чаще всего?»

• «Кто является участниками?»

• «Каковы последние коммиты?»

• «Какие части пугают тебя?»

• «Что сломается, если я изменю X?»

Разработка

Запуск в режиме разработки

npm run dev

Сборка для продакшена

npm run build

Запуск тестов

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

Руководство по тестированию

Примечание: Всегда добавляйте модульные тесты при реализации новых функций.

Тесты находятся в tests/ и используют Vitest. Структура тестов повторяет структуру исходного кода:

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

При добавлении новой функции:

1. Создайте тесты в соответствующей поддиректории tests/

2. Используйте createTestRepo() из fixtures/setup.ts для тестов, связанных с git

3. Очищайте тестовые репозитории с помощью cleanupTestRepo() в afterAll

4. Запустите npm test, чтобы убедиться, что все тесты проходят перед коммитом

Структура проекта

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

Технологический стек

• TypeScript — Типобезопасная кодовая база

• @modelcontextprotocol/sdk — Реализация MCP-сервера

• simple-git — Анализ истории Git

• ts-morph — Парсинг AST TypeScript/JavaScript (планируется)

• glob — Сопоставление шаблонов файлов

Дорожная карта

• [ ] Анализ кода на основе AST с помощью ts-morph

• [ ] Сохранение анализа в JSON/SQLite

• [ ] Визуализация графа зависимостей

• [ ] Обнаружение уязвимостей безопасности

• [ ] Анализ покрытия тестами

• [ ] Пользовательские обработчики вопросов

Лицензия

MIT