内容
# RepoRamp MCP
RepoRamp 是一个确定性的、本地的代码仓库 onboarding 助手，适用于 Codex。它清点一个陌生的代码仓库，查找其结构和操作命令的证据，并生成可审查的概述、设置计划、开放问题和 Mermaid 图表。
RepoRamp 支持 Python、Node.js 和通用回退。它不会执行在代码仓库中找到的命令、调用模型或联系远程服务。代码仓库文本始终被视为不受信任的数据。
完整的产品原理在
[产品需求文档](docs/RepoRamp_MCP_Product_Requirements_Document.docx)。
## 生成内容
显式导出的扫描结果包含：
```text
REPO_OVERVIEW.md
SETUP_PLAN.md
OPEN_QUESTIONS.md
evidence.json
diagrams/
workflow.mmd
dependencies.mmd
```
材料声明携带稳定的证据 ID。发现结果包括源路径和行或清单字段引用、置信度、冲突和命令风险标志。RepoRamp 故意不在 P0 中生成或运行 `setup.sh`。
一个冻结的、经过测试验证的 Orbit Tasks 包可在
[`examples/sample-output`](examples/sample-output) 中找到，无需运行扫描即可审查。
## 要求
- Python 3.11 或更高版本
- Node.js 20 或更高版本，npm 仅用于可选的 Mermaid 语法检查
- 仅当将 RepoRamp 用作 MCP 服务器时，才需要 Codex CLI
## 安装
从干净的 checkout 开始：
```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
```
对于开发，请安装测试额外内容：
```bash
python -m pip install -e '.[test]'
```
确认入口点可用：
```bash
reporamp --help
```
## CLI 使用
扫描代码仓库。在交互式终端上，RepoRamp 显示带有阶段进度、排名文件、命令和终端原生工作流和依赖项预览的彩色 onboarding 地图：
```bash
reporamp scan ./orbit_tasks_sample_repo
```
当 stdout 被重定向时，相同的命令会自动发出现有的确定性 Markdown。这保持管道和保存的报告干净。输出也可以显式选择：
```bash
# 精致的终端视图，即使在自动检测不可用时
reporamp scan ./orbit_tasks_sample_repo --format terminal
# 终端预览加上规范的 Mermaid 源
reporamp scan ./orbit_tasks_sample_repo --format terminal --diagrams both
# ASCII 结构，无颜色或动态效果
reporamp scan ./orbit_tasks_sample_repo --plain
# 稳定的 Markdown，用于文件或其他程序
reporamp scan ./orbit_tasks_sample_repo --format markdown
```
进度动画仅写入交互式 stderr，可以使用 `--no-motion` 禁用。`NO_COLOR`、`TERM=dumb`、`CI` 和 `REPORAMP_REDUCE_MOTION=1` 受到尊重；`--color always|never` 提供显式覆盖。
普通终端无法直接渲染 Mermaid 图形。因此，RepoRamp 为人员提供终端原生预览，并为工具保留 Mermaid 源规范。`diagram` 子命令公开任一形式：
```bash
reporamp diagram ./orbit_tasks_sample_repo --view workflow --format terminal
reporamp diagram ./orbit_tasks_sample_repo --view dependencies --format mermaid
```
打印完整的结构化扫描结果为 JSON：
```bash
reporamp scan ./orbit_tasks_sample_repo --format json
```
添加可重复的 gitignore 样式排除项：
```bash
reporamp scan ./orbit_tasks_sample_repo \
--exclude 'data/' \
--exclude '*.generated.py'
```
除非存在 `--output`，否则不会写入任何文件。相对输出目录从扫描的代码仓库根目录解析，解析后的目标必须位于该代码仓库内：
```bash
reporamp scan ./orbit_tasks_sample_repo \
--output reporamp-output
```
导出命令打印 JSON 清单。如果已存在托管工件，则该命令失败；传递 `--overwrite` 以替换 RepoRamp 管理的文件，同时保留无关文件：
```bash
reporamp scan ./orbit_tasks_sample_repo \
--output reporamp-output \
--overwrite
```
诊断信息会以 Markdown、JSON 和导出模式写入 stderr，并在终端视图的扫描注释部分显示。完整和部分扫描均以 `0` 退出，路径和策略错误以 `2` 退出，意外失败以 `1` 退出。
## 将本地 MCP 服务器注册到 Codex
RepoRamp 通过 STDIO 使用官方 MCP Python SDK。将虚拟环境可执行文件注册到 Codex 启动相同的安装程序：
```bash
codex mcp add reporamp -- \
"$PWD/.venv/bin/reporamp" mcp \
--allowed-root "$PWD"
```
`--allowed-root` 是代码仓库扫描和工件导出的边界。将其设置为包含要分析的代码仓库的最窄目录。如果在直接启动服务器时省略，则默认为服务器的工作目录。
验证注册：
```bash
codex mcp list
```
然后询问 Codex，例如：
> 使用 RepoRamp 扫描 `orbit_tasks_sample_repo`。向我展示概述、设置计划和两个图表。解释冲突和风险命令，但不执行任何代码仓库命令。在我批准目标之前，不要导出文件。
要更改允许的根目录，请删除并重新添加注册：
```bash
codex mcp remove reporamp
codex mcp add reporamp -- \
"/absolute/path/to/reporamp/.venv/bin/reporamp" mcp \
--allowed-root "/absolute/path/to/repositories"
```
### MCP 接口
服务器保留最近完成的 8 次扫描结果的内存。使用 `scan_repository` 开始；将 `scan_id` 传递给其余工具：
- `scan_repository(repo_path, exclude=[])`
- `get_repository_overview(scan_id)`
- `get_setup_plan(scan_id)`
- `get_diagrams(scan_id, views=["workflow", "dependencies"])`
- `get_evidence(scan_id, claim_id=None, kind=None, cursor=None, limit=50)`
- `export_artifacts(scan_id, output_dir, overwrite=False)`
相同的结果作为 MCP 资源公开：
```text
repo://scan/{scan_id}/overview
repo://scan/{scan_id}/setup
repo://scan/{scan_id}/evidence
repo://scan/{scan_id}/unknowns
repo://scan/{scan_id}/diagram/{view}
```
被逐出的或未知的扫描 ID 返回 `SCAN_NOT_FOUND`；再次运行 `scan_repository`。服务器状态从不隐式持久化。
## 验证生成的 Mermaid
Python 包不需要 Node.js。维护人员可以使用官方 Mermaid 解析器验证导出的 `.mmd` 文件或 `reporamp diagram --format mermaid` 生成的源代码：
```bash
npm ci
npm run validate:mermaid -- \
./examples/sample-output/diagrams/workflow.mmd \
./examples/sample-output/diagrams/dependencies.mmd
```
验证工具链提供 Mermaid 所需的 DOM API，使用本地 JSDOM 实例；它不会启动浏览器或渲染代码仓库 HTML。
已提交的锁定文件使此维护人员专属工具链在本地和 CI 安装中可复制。
参见 [TESTING.md](TESTING.md) 以获取完整的验证工作流和 [DEMO.md](DEMO.md) 以获取 5 分钟的演练。
## 安全性和分析边界
RepoRamp 在合成之前应用以下规则：
- 规范化批准的根目录并拒绝路径逃逸；
- 永远不要跟随符号链接，并报告解析到根目录外部的链接；
- 遵守 `.gitignore`、用户排除和内置依赖项/构建/缓存排除；
- 跳过二进制内容和机密文件，例如 `.env`；
- 编辑类似机密的值并保持摘录有界；
- 强制执行文件计数、文件大小、总文本、深度、关系和图表限制；
- 在不导入或执行代码仓库代码的情况下解析清单和源代码；
- 标记特权、破坏性、部署、迁移、凭证、管道到 shell 和网络依赖命令；以及
- 将冲突命令保留为未解决的证据，而不是静默选择一个。
部分扫描结果是有用的，但不完整。在依赖它之前，请咨询其覆盖范围和诊断信息。
## 实现架构
下图映射当前 Python 模块，而不是未来的产品概念。两个接口调用相同的分析器，因此 CLI 和 MCP 扫描使用相同的库存规则、检测器、证据模型和渲染器。
```mermaid
flowchart LR
REPO["目标代码仓库<br/>不受信任， 只读输入"]
USER["终端用户"]
CODEX["Codex"]
subgraph PROCESS["本地 RepoRamp 进程 - 无模型调用或代码仓库命令执行"]
subgraph INTERFACES["接口"]
CLI["CLI<br/>cli.py"]
MCP["STDIO MCP 服务器<br/>mcp_server.py"]
end
subgraph CORE["共享分析核心"]
ANALYZER["分析器编排<br/>analyzer.py"]
POLICY["路径和机密策略<br/>policy.py"]
INVENTORY["有界文件库存<br/>inventory.py"]
DETECTORS["通用、Python 和 Node 检测器<br/>detectors.py"]
RESULT["类型化 ScanResult<br/>models.py"]
end
STORE["MCP 扫描存储<br/>8 结果内存 LRU"]
RENDERERS["Markdown、JSON 和 Mermaid 渲染器<br/>renderers.py"]
EXPORTER["原子显式导出器<br/>exporter.py"]
end
RESPONSES["CLI 输出或 MCP 工具/资源"]
BUNDLE["六文件工件包"]
USER --> CLI
CODEX --> MCP
CLI --> ANALYZER
MCP --> ANALYZER
ANALYZER --> POLICY
POLICY --> INVENTORY
REPO --> INVENTORY
INVENTORY --> DETECTORS
DETECTORS --> ANALYZER
ANALYZER --> RESULT
RESULT -->|"CLI 路径"| RENDERERS
RESULT -->|"MCP 路径"| STORE
STORE -->|"后续 scan_id"| RENDERERS
RENDERERS --> RESPONSES
RESULT -->|"CLI --output"| EXPORTER
STORE -->|"MCP export_artifacts"| EXPORTER
EXPORTER --> RENDERERS
EXPORTER --> BUNDLE
```
MCP 存储仅用于后续调用的便利。它保存最近使用的 8 个 `ScanResult` 对象在内存中，不会创建隐藏的数据库或隐式文件。CLI 直接使用相同的结果，通常会打印出来而不会保留状态。
## 扫描和导出流程
此序列显示了扫描期间发生的情况，以及为什么获取信息与写入文件是分开的。导出块仅在 CLI 接收 `--output` 或 MCP 客户端显式调用 `export_artifacts` 时运行。
```mermaid
sequenceDiagram
actor U as 用户或 Codex
participant I as CLI 或 MCP 接口
participant A as 分析器
participant P as 路径策略
participant V as 库存
participant D as 检测器
participant S as MCP 扫描存储
participant R as 渲染器
participant E as 导出器
U->>I: 请求扫描，路径和排除项
I->>A: 扫描（...）
A->>P: 规范化路径并强制执行 MCP 允许的根目录
P-->>A: 现有批准的目录
A->>V: 库存限定文件，限制范围内
V-->>A: 文件、目录、覆盖范围、诊断信息
A->>D: 运行通用、Python 和 Node 检测
D-->>A: 发现结果、关系、诊断信息
A->>A: 合并发现结果、标记冲突、协调边缘、计算 scan_id
alt MCP 请求
A-->>I: ScanResult
I->>S: 按 scan_id 存储结果
I-->>U: 返回 ScanSummary 和 scan_id
U->>I: 请求概述、设置、图表或证据
I->>S: 按 scan_id 加载结果
S-->>I: ScanResult
else CLI 请求
A-->>I: ScanResult
end
I->>R: 渲染请求的 Markdown、JSON 或 Mermaid
R-->>I: 渲染内容
I-->>U: 显示结果供人工审查
opt 显式导出请求
I->>E: export_artifacts(结果，输出目录)
E->>P: 验证子路径和符号链接边界
E->>R: 渲染六个托管工件
E-->>I: 导出清单，包含路径和 SHA-256 哈希值
I-->>U: 报告写入的文件
end
```
两个控制点是故意的：策略检查发生在读取代码仓库内容之前，导出路径检查发生在写入工件之前。代码仓库指令在整个流程中保持为数据；RepoRamp 解析它们但从不执行它们。
这是 PRD 中描述的基于证据的混合方法：RepoRamp 执行可预测的本地分析，而现有的 Codex 会话可以组织和解释返回的证据。RepoRamp 本身不需要 API 密钥或单独的登录。
## 开发
运行 Python 套件：
```bash
pytest
```
运行较慢的生成代码仓库基准测试：
```bash
pytest -m performance
```
代码仓库固定装置涵盖 Orbit Tasks Python 示例、综合 Node 工作区和具有冲突指令、损坏配置、类似机密数据、二进制文件和路径转义符号链接的对抗性代码仓库。
开发和测试详情见 [TESTING.md](TESTING.md)。AI 辅助的作用和限制记录在 [AI_USAGE.md](AI_USAGE.md)。
## 成功标准
P0 成功时，所有三个固定装置都会生成完整的六个文件工件包；每个渲染的材料声明都解析为证据；预期的入口点和命令被检测到；机密值和代码仓库根目录外部的文件从未出现；不会执行代码仓库命令；CLI 和 MCP 结果一致；两个 Mermaid 图表都能成功解析。
