myopic

myopic

レジストリで最も皮肉の効いた名前を持つコードレビューツール用 MCP です。 名前とは裏腹に、目が近視というわけではありません。目の前の差分だけでなく、コードベース全体を対象にマージリクエストをレビューします。

公開しながら開発中です。 GitLab のマージリクエストと GitHub のプルリクエストをレビューします。どちらの URL も渡せます。変更を読み込み、コードベース全体を照らし合わせてレビューし、インラインコメントとしてレビューを投稿できます。Issue や PR も歓迎します。

---

理由

重要なバグは、差分の中にあることはほとんどありません。差分に表示されていない部分に潜んでいます。たとえば、3ファイル離れた場所にある、変更によって壊れる呼び出し元。このファイルだけがひそかに外れている、同じ役割を持つ他のファイルがすべて従っている規約。あるいは、すでに存在するヘルパーと重複する新しいヘルパーです。パッチだけを読むレビューツールは視野が狭いのです。

myopic はオープンソースのMCPサーバーです。すでに利用している AI クライアント（Claude、Cursor、…）に、コードベースを把握している人のようにレビューするための構造化されたコンテキストを提供します。お使いのマシン上で動作するため、コードが外部に送信されることはなく、PR ごとの料金もかかりません。レビューは、ご自身の基準を適用したご自身のエージェント内で行われます。

• 変更を正確に読み取ります — 差分を行番号付きのハンク、または関数／クラスごとにまとめて確認できます。あらゆるサイズの MR でトークン量を安全に扱えます（10,000 行の差分でもコンテキストウィンドウを超えません）。
• コードベース全体と照らし合わせてレビューします — 変更されたコードの呼び出し元（影響範囲）、呼び出し元／呼び出し先のグラフ、および必要に応じて意味的に類似したコードを確認できるため、規約の破綻や重複を見つけられます。

SQL データベースについて AI に永続的なメモリを提供する MCP サーバー、amnesicと併用できます。

---

ツール

計画中と明記されていないものは、以下のすべてが現在利用できます。

マージリクエストを読み取る（設計上、トークンを安全に扱います）：

ツール	機能
mr_review_status	MR のメタデータ、すべてのディスカッションスレッド、解決済み／未解決の状態を 1 回の呼び出しで取得します
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	唯一の書き込み機能 — 指数バックオフを使い、キューから 1 件ずつインラインコメントを投稿します（下書きや一括公開はありません）。これにより、部分的な進捗が保持され、レート制限も守られます

今後の予定については、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 を渡すだけです。環境変数、または config.toml の [github] セクションに、GITHUB_TOKEN（PR の読み取りアクセス権を持つ PAT）を設定してください。GitHub Enterprise の場合は、[github].url にホストを設定してください。

AI クライアントに追加する

Claude Code — 設定ファイルを編集せず、コマンドを 1 つ実行するだけです。

/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 では mr_diff_sections、それ以外では mr_diff_lines で変更内容を読み取り → ローカルクローンをチェックアウトした状態で、リスクのある変更済みシンボルに対して dependency_impact / trace_call_chain（または mr_review_context）を実行し、それらに依存するすべてのコードと照らし合わせてレビューします。

グラフツールは root でチェックアウトされている内容を分析するため、先に MR のブランチをチェックアウトしてください。そうしないとターゲットブランチをレビューすることになり、MR の新しいコードは含まれません。myopic worktree <mr-url> <repo> を実行すると、使い捨てワークツリーで MR のヘッドをチェックアウトします（メインのチェックアウトには影響しません）。さらに、root に指定するパスを表示します。mr_review_context は、root に MR のヘッドがない場合にも警告します。

フォークの PR にも対応しています。フォークのブランチはリモートに存在しないため、GitHub PR のヘッドは refs/pull/N/head 経由で取得されます。PR がブランチから作成された場合もフォークから作成された場合も、ベースリポジトリから取得できます。

---

セマンティック検索（組み込み — 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 で無効化できます。グラフ処理にはインデックスは不要で、常に実行されます）。明示的な実行や cron での利用には、引き続き index_repo / myopic index を使えます。

インデックス作成は差分ベースで、鮮度を考慮します。 最初の index_repo は全体を構築します。その後は内容が変わったファイルだけを再埋め込みするため、更新は低コストです。index_status(root) は、インデックスが最新か、stale（main から遅れているコミット数を含む）か、別のモデルで構築されたものかを報告します。鮮度は現在のチェックアウトではなく、リポジトリのメインラインを基準に測定されるため、フィーチャーブランチをレビューしてもインデックスが古いとは判定されません。古くなるのは main 自体が進んだ場合だけです。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

引き続き使う2つ目のクローンのインデックスは保持されます。削除されるのは到達不能なものだけです。

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 を指定します（デフォルトでは無効）

セキュリティ

• 明示的な書き込みは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