Repiscope

Repiscope

仓库的潜望镜——尽览全貌，绝不触碰。

Repiscope 是一个只读 MCP 服务，让你的编码 Agent（Claude Code、 Cursor 或任何 MCP 客户端）了解它正在处理的仓库旁边的同级仓库， 但绝不会允许它们修改这些仓库。

为什么要做

我构建了一个个人助手，帮我决定该把时间花在哪里：为此， 它需要了解每个项目的真实状态——有哪些变化、哪些停滞了、 下一步该做什么。因此，它必须看见我的所有仓库。但告诉 Agent“什么都别碰”只是请求，不是保证。Repiscope 让这成为保证：服务不提供任何写入工具，因此 Agent 在结构上无法修改你的仓库。同一个潜望镜也能帮助任何 在项目 A 中工作的编码 Agent 了解项目 B 的某个部分如何运作。

沙盒只会让情况更糟，而不是更好：我的沙盒（理应如此）会阻止 Agent 读取它启动时所在仓库以外的内容，除非先征求许可。放宽沙盒限制也会授予写入权限。Repiscope 提供第三种方式—— Agent 通过一个 MCP 服务，就能以结构化、只读的方式查看所有同级仓库，同时沙盒仍保持严格限制。

看看实际效果

你正在 project-a 中工作，需要从另一个项目的 API 获取数据。与其由你翻查那个代码库，不如让 Agent 直接询问 Repiscope：

You:    Use Repiscope to find out what kind of data I can retrieve
        from billing-api through its API.

Agent:  (calls list_projects → sees "billing-api")
        (calls project_overview "billing-api" → spots src/routes/)
        (calls search "route" project="billing-api")
        (calls read_file "billing-api" "src/routes/invoices.py")

        billing-api exposes three endpoints: /invoices (list, filterable
        by customer and date), /invoices/{id} (full invoice with line
        items), and /customers/{id}/balance (current balance). All
        responses are JSON; auth is a bearer token.

Agent 探索了一个它完全无法写入的仓库。无需复制粘贴， 无需提醒“请不要编辑任何内容”，也没有风险。

工具

工具	输入	返回内容
list_projects()	—	每个同级仓库及一行描述
project_overview(project)	仓库名称	完整概览：用途、技术栈、结构、近期提交
search(query, project?)	文本，可选仓库	与查询匹配的文件和行
read_file(project, path)	仓库和文件路径	完整文件内容（大小有限制）
store_summary(project, summary)	仓库和你的文本	缓存由 Agent 编写的摘要（见下文）

如何保持内容最新

概览以 markdown 格式缓存，并在需要时刷新：每次调用时，Repiscope 都会将仓库当前的 git 提交哈希与构建概览时记录的哈希进行比较。哈希相同 → 提供缓存内容。不同 → 只重建该仓库的概览。无需 cron，也无需守护进程。

借用智能

Repiscope 没有自己的大模型——无需 API 密钥，不调用模型，成本为零。但 它整天都在与大模型对话，因此会借用它们：如果概览中没有新鲜的 Agent 编写摘要，结尾就会附上一条说明，请求调用方 Agent 编写摘要，并通过 store_summary 提交。之后，这条摘要会出现在该项目未来的每份概览开头——由一个 Agent 编写，供之后所有 Agent 阅读——直到仓库的下一次提交使其过时，循环重新开始。

以架构保障安全

Repiscope 的设计确保安全行为不是一种承诺，而是唯一可能的行为：

• 没有任何写入仓库的工具。 服务不会暴露任何能在你的仓库中创建、编辑或删除内容的工具。唯一接受数据的工具 store_summary 只能将内容写入 Repiscope 自己在 ~/.cache/repiscope 中的缓存。不存在的能力，Agent 无法滥用。
• 秘密不可见。 每个工具都会执行同一个过滤器（privacy.py）：私钥、证书（.pem、.pfx、.p12 等）、.env* 文件、密钥库，以及任何名称看起来像凭据的内容，都不会出现在概览、目录树、搜索结果或文件读取结果中。 坦诚说明限制： 过滤器会隐藏敏感文件，但不会清除例如粘贴在普通文本文件中的密码。
• 符号链接无法暗中泄露内容。 克隆的仓库是不可信内容——其中可能包含类似 notes.txt → ~/.ssh/id_rsa 的符号链接。真实位置在项目目录之外的任何内容都对所有工具不可见；秘密过滤器也会检查链接的真实目标，并拒绝路径遍历（../）。
• 由你划定边界。 Repiscope 只能看到你明确传入的文件夹（--root）；--exclude 会让选定的仓库完全不可见，甚至无法通过名称解析。
• 不会留下痕迹。 概览缓存保存在 ~/.cache/repiscope，绝不会放在你的仓库中。

上述每项承诺都由 tests/ 中的测试套件保障——克隆仓库并运行 pytest，即可自行验证。

快速开始

pip install repiscope
claude mcp add repiscope --scope user -- repiscope --root ~/your/projects/folder

就这么简单——将 --root 指向包含仓库的文件夹（而不是仓库本身）。也可以使用 --exclude repo-a --exclude repo-b 隐藏仓库。支持任何 MCP 客户端；Claude Desktop 还可使用一键安装的 .mcpb 捆绑包（使用 mcpb/build.sh 构建）。

也可以从源代码运行：

git clone https://github.com/3xpr1ment/repiscope.git
cd repiscope
python -m venv .venv && .venv/bin/pip install -e .[dev]
.venv/bin/pytest   # the security claims, as executable proof

限制

坦诚说明 Repiscope 刻意不做什么：

• 秘密过滤器以文件为单位工作。 敏感文件不可见，但粘贴在普通 notes.md 中的密码不会被清除。边界由你划定：只将你愿意展示给 Agent 的文件夹传给 --root——工具能看到什么，你的 LLM 提供商也能看到什么。
• 搜索刻意保持简单。 不区分大小写的子字符串匹配，结果数量有限制，没有索引，也不支持正则表达式。调用它的大模型负责搜索前后的智能处理；如需深入搜索代码，请使用真正的代码搜索工具。
• 概览是机械生成的。 如果没有 Agent 编写的摘要，概览就只有 README 摘录、语言统计和 git 日志——有用，但谈不上洞见。只有 Agent 开始留下摘要后，才能获得洞见。
• 只读有利也有弊。 没有可调用的刷新工具：缓存会在下次提交时惰性刷新；在 Agent 写入新摘要之前，过期摘要会继续提供，并标记为过期。
• Python ≥ 3.11，在 macOS 上开发和测试；Linux 上的行为应当完全相同，Windows 的符号链接语义尚未测试。

状态

v0.2.2——已可用，并且每天都在实际使用。包含 4 个只读工具、借用 LLM 生成的摘要、惰性缓存刷新、敏感文件过滤，以及用于验证安全承诺的测试套件（路径遍历、符号链接逃逸、秘密过滤——见 tests/）。API 仍可能变更。

构建过程

关于作者身份，我想完全坦诚：我不是工程师。Repiscope 中的每项架构决策——它做什么、拒绝做什么、安全防护措施位于何处——都由我决定；但代码本身由 Claude（Anthropic 的 Fable 模型）编写。我们合作的原则是：凡是我不理解的内容，一概不合入。提交历史逐个提交公开记录了双方的共同创作。

许可证

MIT

---

mcp-name: io.github.3xpr1ment/repiscope