Locus

Locus

Locus は、AI コーディングエージェントにコードベースの地図を提供します。自分でコードを書く場合も、Cursor、Codex、Claude Code を通じて作業する場合も、Locus は MCP（Model Context Protocol）を通じて、IDE が利用する定義への移動や参照検索の機能をエージェントに提供します。MCP は AI ツール向けの標準的なプラグインレイヤーです。一度設定すれば、エージェントは6つの小さなツールを使ってシンボルを検索し、呼び出し元をたどり、型を読み取り、テスト実行前にエラーを検出できます。

こんな場合に役立ちます

• 本当の定義を見つける — 名前がテキストとして現れる場所を検索するだけでなく、再エクスポートやオーバーロードがある場合や、大きなファイルの奥にある場合でも、エージェントは UserService.authenticate を特定できます。
• 呼び出し関係を確認する — リファクタリングの前に、関数やクラスへのすべての参照を一覧表示して、気づかないうちに何かが壊れるのを防ぎます。
• 型やドキュメントを読む — 変数名から推測することなく、変数やパラメーターが実際には何なのかを尋ねられます。
• エラーを早期に検出する — テスト一式の実行を待つ代わりに、編集直後にコンパイラーやリンターの問題を確認できます。

対象ユーザー

Locus はAI ファーストの開発者、つまりエージェントを通じて作業し、文字列検索だけでなくコード構造も理解させたい開発者、インディーハッカー、PM 向けです。

エージェントがすでにファイルをうまく編集できており（Cursor の Edit ツール、Claude Code、Codex）、MCP 内に2つ目の IDE を作り込むことなく、その上にセマンティックなナビゲーション機能を加えたい場合に適しています。

MCP 内でシンボリック編集、エージェントのメモリー、包括的なリファクタリングツールキットを求める人向けではありません。そのような用途には、プロトコル内でより多くの機能を提供する、より幅広い選択肢の Serena をご覧ください。Locus は意図的に小さく保たれており、ツールは6つ、インストールは npx で行い、ホストを補完します。

5分で始める

1. 言語サーバーをインストールする（まだインストールしていない場合） — TypeScript/JavaScript の場合：npm install -g typescript-language-server typescript。Python、Go、Rust については言語サーバーのインストールをご覧ください。
2. プロジェクトフォルダーで初回セットアップを実行する：

   npx @paladini/locus-mcp init
   npx @paladini/locus-mcp check
   

3. エージェントの MCP 設定に Locus を追加する — MCP は、AI ホストが Locus のようなヘルパーツールを呼び出す仕組みです。以下のコピーして貼り付ける設定からブロックをコピーし、cwd をプロジェクトの絶対パスに設定します。
4. MCP を再読み込みする — Cursor を再起動するか、Codex を再読み込みするか、Claude Code を再度開いて、新しいサーバーが表示されるようにします。
5. プロンプトを試す — エージェントに次のように尋ねます：「Locus を使って UserService の定義場所を見つけ、すべての参照を一覧表示してください。」 locate ツールと refs ツールが呼び出されれば、準備完了です。

要件： Node.js 22 以降。使用する言語の言語サーバーが PATH 上にあること。

コピーして貼り付ける設定

通常の使用時、エージェントホストが Locus を自動的に起動するため、手動で serve を実行する必要はありません。

Cursor

プロジェクト内の .cursor/mcp.json（または Cursor のグローバル MCP 設定）を作成または編集します：

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Codex

~/.codex/config.toml（グローバル）または .codex/config.toml（プロジェクト）に追加します：

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp", "serve"]
cwd = "/absolute/path/to/your/project"

プロジェクト単位の設定では、代わりに cwd = "." を使用できます。

Claude Code

Claude Code の MCP 設定に追加します：

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

詳細（ローカル開発、トラブルシューティング）：docs/usage.md

試してみるプロンプト

Locus の設定後、これらをエージェントに貼り付けてください。

• "UserService が定義されている場所を見つけてください。grep ではなく、Locus の locate を使ってください。"
• "parseConfig の名前を変更する前に、Locus を使って、それを呼び出しているファイルをすべて一覧表示してください。"
• "src/api/handler.ts の response.data の型は何ですか？ Locus の hover を使ってください。"
• "編集後、変更したファイルに対して Locus の diagnostics を実行し、エラーがあれば修正してください。"
• "Locus の status を確認してください。言語サーバーの準備はできていますか？"

Locus が行わないこと

• コードの編集 — エージェントの Edit/Write ツールが引き続き変更を適用します。Locus はコードの構造と診断結果を読み取るだけです。
• grep の置き換え — ログ行、設定キー、コメント、プレーンテキストの検索には、引き続き grep が最適です。
• セッション間で情報を記憶すること — エージェント用のメモリーストアはありません。セッションは毎回新しく始まります。
• リファクタリングの実行 — rename は変更の影響をプレビューします。実際の編集はエージェントが適用します。
• すべての LSP 機能の公開 — IDE プロトコルを全面的に中継するのではなく、用途を絞った 6 つのツールのみを提供します。
• 大型ツールキットとの競合 — シンボルの本文置換、メモリー、40 以上の言語を 1 つの MCP スタックで利用する必要がある場合は、代わりに Serena をご検討ください。

ツール一覧

ツール	機能
locate	名前でシンボルを検索、またはファイル内のシンボルを一覧表示
refs	指定位置にあるすべての参照または実装
hover	型情報とドキュメント
diagnostics	ファイルまたはワークスペースのエラーと警告
status	言語サーバーの準備状況と不足しているバイナリ
rename	名前変更をプレビュー（ドライラン。適用はエージェントが実行）

詳細情報

ガイド	説明
使用ガイド	セットアップ、ワークフロー、トラブルシューティングを順を追って説明します
はじめに	初回セットアップ — LSP の知識は不要です
よくある質問	プログラマーである必要はありますか？ MCP とは何ですか？
Locus の対象ユーザー	適合性、対象範囲、代替手段を選ぶべき場合
比較	Locus と Serena、ブリッジ、grep の比較
ツールリファレンス	6 つの MCP ツールすべてを例とともに紹介します
設定	locus.toml、locus.json、言語サーバー
ウェブサイト	簡潔な位置づけと概要

ライセンス

MIT