Repo Therapist

Repo治疗师🛋️

你的代码库在压力下自我解释

此MCP服务器完全使用Cursor构建

Repo治疗师是一个MCP（模型上下文协议）服务器，它将任何存储库转化为可查询、可解释的知识。通过Cursor询问有关代码库的问题，并获得结构化、有见地的答案。

它做什么

您可以向Cursor询问以下问题：

• “为什么这项服务的结构是这样的？”
• “如果我删除这个，会有什么问题？”
• “这个回购的哪些部分让你害怕？”

幕后，Repo治疗师：

• 读取您的仓库结构和文件
• 分析git历史和提交模式
• 将代码与更改频率相关联
• 识别复杂性热点和风险

可用工具

地面真相：快照

当你奔跑时 analyze_repo，Repo治疗师创建了一个 静态快照 -关于您的存储库的权威信息来源。此快照包括：

{
  "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历史学家：时间维度

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": [...]
}

这可以让你回答：

• “为什么这很奇怪？”→ “因为它在6个月内被重写了12次。”
• “谁拥有这个文件？”→ “有争议-有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.添加到光标

打开光标设置→ MCP → 添加新的MCP服务器：

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

重要提示： 替换 /FULL/PATH/TO/ 带有您的repo治疗师文件夹的实际绝对路径。

例子：

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

4.重新启动游标

添加MCP配置后，重新启动Cursor以使更改生效。

常见问题

我需要单独运行回购治疗师吗？

号码 Cursor会自动为您启动和管理MCP服务器。当您将配置添加到Cursor的MCP设置中时，Cursor将：

• 启动 node dist/index.js 需要时处理
• 让它在后台运行
• 通过stdio（标准输入/输出）与它通信

你只需要建造一次(npm run build)，添加配置，然后重新启动Cursor。就这样

我该在哪里提问？

在正常的Cursor聊天中 （Cmd+L或聊天面板）。区别在于 *怎么* 你问：

• 没有MCP： “这个回购是做什么的？”→ Cursor使用其内置工具
• 与Repo治疗师合作： “使用 analyze_repo 上 /path/to/repo" → Cursor调用MCP工具

您明确地告诉Cursor使用repo治疗师工具。Cursor将它们视为它可以使用的附加功能。

与正常的Cursor聊天有什么区别？

关键区别： Repo治疗师做 *结构化分析* 因此，诸如“哪些文件最常更改？”或“有什么风险？”之类的问题可以从预先计算的数据中得到答案，而不是Cursor每次都必须弄清楚。

把它想象成：Cursor很聪明，但反应灵敏。Repo治疗师为其提供了一份关于代码库的“简报文件”，供其参考。

用法

配置后，您可以在Cursor聊天中使用Repo治疗师：

步骤1：分析回购

首先，分析您要探索的存储库：

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

第二步：提问

现在您可以提问：

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/ 和使用 维测试测试结构反映了源：

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 -类型安全代码库
• @模型上下文协议/sdk -MCP服务器实现
• 简单git -Git历史分析
• ts变形 -Types/JavaScript AST解析（计划中）
• 通配符 -文件模式匹配

路线图

• \[\]基于AST的ts变体代码分析
• \[\]将分析持久化为JSON/SQLite
• \[\]依赖关系图可视化
• \[\]安全漏洞检测
• \[\]测试覆盖率分析
• \[\]自定义问题处理程序

许可证

麻省理工学院