myopic

myopic

这是注册表中名字最讽刺的代码审查 MCP。 它可一点也不近视——它会对照整个代码库审查你的合并请求，而不只是眼前的差异。

公开开发中。 支持审查 GitLab 合并请求和 GitHub 拉取请求——传入任一链接即可。它会读取变更，对照整个代码库进行审查，还可以将审查结果作为行内评论发布回去。欢迎提交问题和 PR。

---

为什么

真正重要的 Bug 很少出现在差异本身，而是藏在它没有展示的地方：远在三个文件之外、如今会出错的调用方；所有同类文件都遵循、唯独这个文件悄悄抛弃的约定；以及已经存在、导致这个新实现成为重复项的辅助函数。只读取补丁的审查器就是近视。

myopic 是一个开源的 MCP 服务，为你正在使用的 AI 客户端（Claude、Cursor 等）提供结构化上下文，让它像了解代码库的人一样进行审查。它在你的计算机上运行——你的代码不会离开本机，没有按 PR 计费，你可以在自己的 Agent 中按照自己的标准进行审查：

• 精确读取变更——将差异作为带行号的代码块读取，或按函数/类分组，对任何大小的 MR 都能安全处理令牌（10,000 行的差异也不会超出上下文窗口）。
• 对照整个代码库进行审查——查看谁调用了变更代码（影响范围）、调用方/被调用方关系图，以及——可选地——语义相似的代码，从而发现被破坏的约定和重复实现。

它与 amnesic 搭配使用；这是我的另一个 MCP 服务，可为 AI 提供 SQL 数据库的持久记忆。

---

工具

以下所有内容目前均可使用，除非标记为计划中。

读取合并请求（从设计上确保令牌安全）：

工具	功能
mr_review_status	一次调用即可获取 MR 元数据、所有讨论线程及其已解决/未解决状态
mr_changed_files	不含内容的变更文件清单（路径、统计数据、噪声标记）——不含差异内容，因此即使 MR 很大也能保持精简
mr_diff_sections	按函数/类分组的差异（支持 AST 感知），并限制预算
mr_diff_lines	带行号的差异代码块——提供行内评论的精确位置，并限制预算

对于大型 MR，差异工具会返回有限页面，并在 omitted_files / truncated 中列出其余内容，而不是报错；锁文件、生成代码和二进制文件会列出，但不会展开。使用 files_filter 获取其余内容。

结合整个代码库进行审查（指向本地克隆）：

工具	功能
dependency_impact	查找变更符号在何处被使用——评估影响范围（ripgrep + tree-sitter）
trace_call_chain	符号的调用方/被调用方关系图
mr_review_context	核心功能——针对每个变更符号：提供其影响范围（始终提供），并在启用可选层时提供语义相似代码

语义层（内置——需要 Ollama）——index_repo、code_search，以及 mr_review_context 的语义部分。详见下文。

形成闭环——验证，并按需发表评论：

工具	功能
mr_verify_review	针对每个已有审查线程，查看被评论行附近的差异变更——后续提交是否解决了该问题？（只读）
mr_post_comments	唯一的写入操作——从队列中逐条发布行内评论，并使用指数退避（不保存草稿、不批量发布），以保留部分进度并遵守速率限制

后续计划请参阅 ROADMAP.md。

---

安装

pipx 会将 myopic 安装在隔离环境中，并将其添加到 PATH：

pipx install myopic

更喜欢使用普通的 venv？运行 python3 -m venv ~/.venvs/myopic && ~/.venvs/myopic/bin/pip install myopic，然后在示例中使用 myopic 的位置改用该二进制文件。

设置

myopic 需要一个具有 api（或 read_api）权限范围的个人访问令牌。设置向导会引导你完成操作：

myopic init     # prompts for URL + token, verifies, saves both
myopic test     # ✓ Authenticated to https://gitlab.com as <you>
myopic doctor   # health-check config + (if enabled) the semantic layer

令牌会保存到 ~/.config/myopic/.env（chmod 600），并在 TOML 中通过 ${GITLAB_TOKEN} 引用——绝不会保存在配置文件本身中。使用 myopic set-secret 轮换令牌，或通过 myopic init --template 手动编辑。

**GitHub PR：**只需传入 PR URL。在环境变量中设置 GITHUB_TOKEN（具有拉取请求读取权限的 PAT），或在 config.toml 中添加 [github] 部分。对于 GitHub Enterprise，将 [github].url 设置为你的主机。

添加到 AI 客户端

Claude Code——只需一条命令，无需编辑配置：

/plugin marketplace add https://github.com/SurajKGoyal/myopic-marketplace
/plugin install myopic@myopic

其他 MCP 客户端（Cursor、Claude Desktop 等）——将其指向 myopic 命令：

{
  "mcpServers": {
    "myopic": {
      "command": "myopic"
    }
  }
}

如果客户端无法在 PATH 中找到它，请使用绝对路径（pipx 会将其安装到 ~/.local/bin/myopic）。

不使用 myopic init，改为内联配置

将令牌放入 env 块并跳过配置文件——myopic 会从环境变量中读取 GITLAB_TOKEN / GITHUB_TOKEN：

{
  "mcpServers": {
    "myopic": {
      "command": "myopic",
      "env": { "GITLAB_TOKEN": "glpat-…", "MYOPIC_AUTO_PULL": "1" }
    }
  }
}

MYOPIC_AUTO_PULL=1（可选）会在首次使用时拉取缺失的嵌入模型，而不是报错。

使用

让你的 AI 处理一个合并请求：

“审查这个 MR：https://gitlab.com/group/project/-/merge_requests/42”

客户端可以遵循这样的流程：先用 mr_changed_files 查看整体情况 → 用 mr_diff_sections（大型 MR）或 mr_diff_lines 阅读变更 → 然后在本地检出仓库后，对风险较高的变更符号使用 dependency_impact / trace_call_chain（或 mr_review_context），结合所有依赖这些符号的内容进行审查。

图谱工具会分析 root 中当前检出的内容，因此请先检出 MR 分支——否则你审查的就是目标分支，其中没有 MR 的新代码。myopic worktree <mr-url> <repo> 会在临时工作树中检出 MR 的头部提交（不会改动主工作区），并打印可用作 root 的路径。若 root 中没有 MR 的头部提交，mr_review_context 也会发出警告。

Fork PR 也适用：Fork 的分支在你的远程仓库上不存在，因此 GitHub PR 的头部提交会通过 refs/pull/N/head 获取；无论 PR 来自分支还是 Fork，基础仓库都会提供该引用。

---

语义搜索（内置——需要 Ollama）

对于“这是否符合代码库其余部分的做法？”这类问题——例如重复代码、规范偏差和相似模式——语义层都能应对。它已包含在基础安装中（lancedb + httpx）；唯一的外部要求是 Ollama 正在运行。

嵌入向量由你运行的本地 Ollama 服务生成——你的代码绝不会离开你的机器。myopic 通过 HTTP 与 Ollama 通信；它不会捆绑或启动 Ollama。一次性先决条件：

1. Ollama 正在运行（默认地址为 localhost:11434，或设置 MYOPIC_OLLAMA_URL）。
2. 已拉取嵌入模型：ollama pull unclemusclez/jina-embeddings-v2-base-code。

myopic doctor 会检查这两项，并可为你拉取模型。

嵌入向量存储在内嵌式 LanceDB 索引中，支持混合（向量 + 全文）搜索；mr_review_context 会为每个变更符号补充语义相似的代码。无需手动运行 index_repo——它会在首次审查时自动为仓库建立索引，并在索引过期时自动刷新（可通过 MYOPIC_AUTO_INDEX=0 禁用；图谱处理无需索引，始终会运行）。index_repo / myopic index 仍可用于显式调用或定时任务。

索引采用增量更新，并会感知新鲜度。 首次运行 index_repo 时会完整构建索引；此后只会重新嵌入内容发生变化的文件，因此刷新成本很低。index_status(root) 会报告索引是否为最新、是否已 stale（并显示落后主分支的提交数），或是否基于不同模型构建——新鲜度是相对于仓库的主线衡量的，而不是当前检出内容，因此审查功能分支不会导致索引被标记为过期；只有主线实际发生变更才会如此。code_search 和 mr_review_context 会附带此状态，确保过期索引不会悄无声息地降低审查质量；如果索引已过期，AI 会收到提示，建议刷新索引。

索引是按仓库而非按检出内容划分的——MR 头部的 myopic worktree 会与其克隆共享索引，因此审查新分支不会重新构建索引；只有该分支更改的文件会重新嵌入。

同一仓库的单独克隆也会拥有自己的索引，而删除仓库后，其索引仍会保留。索引过程会自动清理这些失效副本；如要自行检查并回收它们：

myopic prune            # dry-run: what's stale, and how much it's costing
myopic prune --apply    # delete them

仍在使用的第二个克隆会保留其索引——只有无法访问的索引才会被移除。

myopic 是 stdio 服务（没有后台进程），因此没有内置调度器——但 myopic index /path/to/repo 可用作调度入口。配置 cron 或 launchd 调用该命令，即可在后台定期保持索引为最新：

# refresh hourly (incremental — usually seconds)
0 * * * * myopic index /path/to/repo

使用 MYOPIC_EMBED_MODEL / MYOPIC_OLLAMA_URL 覆盖模型或端点。

---

配置参考

来源	键	备注
config.toml	[gitlab].url	GitLab 基础 URL（默认值为 https://gitlab.com）
config.toml	[gitlab].token	使用 ${GITLAB_TOKEN}——不要硬编码
.env（与配置文件同目录）	GITLAB_TOKEN	实际的令牌值（chmod 600）
环境变量	MYOPIC_GITLAB_URL / GITLAB_URL	无 TOML 配置时的回退值
环境变量	MYOPIC_GITLAB_TOKEN / GITLAB_TOKEN	无 TOML 配置时的回退值
环境变量	MYOPIC_CONFIG / MYOPIC_HOME	覆盖配置文件 / 目录
环境变量	MYOPIC_EMBED_MODEL / MYOPIC_OLLAMA_URL	语义层模型 + 端点
环境变量	MYOPIC_AUTO_INDEX	设为 0 可在评审期间禁用自动索引（默认开启）
环境变量	MYOPIC_AUTO_PULL	设为 1 可在首次使用时自动拉取缺失的嵌入模型（默认关闭）

安全性

• 只有一项明确的写入操作，其他操作均为只读。 只有 mr_post_comments 会修改评审内容，而且仅在你要求时才会执行——其他工具都只读取 MR 和仓库数据。写入绝不会擅自执行。
• 令牌始终保留在本地。 它存储在你的 .env / 环境中，只会发送到你配置的 GitLab 实例——绝不会发送给任何第三方。
• 身份验证错误会经过清理，确保令牌不会泄露到错误消息中。
• 语义层完全在本地运行（使用你的 Ollama 和磁盘上的 索引）——你的代码绝不会发送给任何第三方。

开发

pip install -e ".[dev]"
pytest                           # hermetic — no network, Ollama, or lancedb needed

许可证

MIT © Suraj Goyal

mcp-name: io.github.SurajKGoyal/myopic