lens-mcp

lens-mcp

コードと Markdown の両方を対象に、決定論的なナビゲーションマップを作成します — AI エージェント向けです。 1 つの MCP サーバーに 2 つのレンズを搭載しています。ソースコードには tree-sitter（TypeScript / JavaScript / Python）、ドキュメントには Markdown レンズを使用します。「X はどこにあり、このプロジェクトは どのような構成か？」という問いに、1 回の低コストな呼び出しで答えます。これにより、エージェントはファイルの閲覧ではなく、思考にコンテキストを使えます。

Model Context Protocol に対応しており、Claude Code、Cursor、Codex、独自のエージェントなど、あらゆる MCP クライアントで動作します。

理由

見慣れないリポジトリを把握するため、エージェントは通常、ls で一覧を確認したり、 grep で検索したり、目的の関数や適切なドキュメントを探すためにファイル全体を読んだりしてトークンを消費します。lens は領域そのものではなく、そのマップを返します。

• function_body は 1 つの関数を読み取ります — 多くの場合、その関数を含むファイルを読むよりコンテキストを約 99% 削減できます。
• heading は 1 つのドキュメントセクションを読み取ります — 対象の見出しとその下位セクションのみを取得し、それ以外は含みません。
• map はプロジェクト全体の概要を返します — すべてのコードファイルの構造とすべてのドキュメントのアウトラインを、1 回の呼び出しで取得できます。

すべての出力は決定論的で（モデルによる要約ではなく、実際に解析します）、正確なtruncatedフラグを付けて上限を設け、1 つの契約に基づいて提供されます。

lens はナビゲーションマップです。これを使って 場所を特定 したら、評価や変更を行う前に、実際の ソースやセクションを Read してください。シグネチャは関数本体ではなく、アウトラインはセクションそのものではありません。

ツール（13 種類）

全体把握

ツール	機能
map	1 回の呼び出しでツリー全体の概要を取得します。コードファイルごとの構造と、ドキュメントごとのタイトル＋アウトラインを、両方まとめて 1 つの応答で返します。
info	バージョン、サンドボックスのルート、対応言語／拡張子、ツール一覧、すべての出力上限、および lens の契約を返します。
lens_system	インストール状況、セルフアップデート（内部でupdate.shを実行）、最新の AGENTS.md の取得を行います。lens の自己保守ツールです。

コード（tree-sitter — .ts .tsx .mts .cts .js .jsx .mjs .cjs .py）＋ Prisma（.prisma）

ツール	機能
overview	1 つのファイルについて、インポート、エクスポート、クラス（およびメソッド）、トップレベル関数と行範囲を返します。
functions	ネストされたものも含むすべての関数について、シグネチャ、パラメーター／型、parentスコープ、種類を返します。
function_body	1 つの関数のソースをそのまま返します — 対象を絞った読み取りに使います。
comments	コメントとTODO/FIXME/BUG/HACK/…マーカーを返します（負債一覧にはmarkersOnlyを指定します）。
find	ディレクトリ全体から名前を指定して定義を検索します — 関数、クラスに加え、const／type／enum／エクスポートも検索できます。
references	逆引き検索です。シンボルを使用している箇所（呼び出し箇所、インポート、型参照）を、tree-sitter による正確な解析で特定し、grep の誤検出を避けます。

ドキュメント（Markdown — .md .markdown .mdx）

ツール	機能
outline	行番号付きで見出し階層全体（目次）を返します。
heading	見出しテキスト／スラッグ／行番号を指定して、1 つのセクションを読み取ります。
links	インラインリンク／画像リンク／Wiki リンク／自動リンク／参照リンクを抽出します。
search	ドキュメント全体を対象に、大文字と小文字を区別しない全文検索を行います（見出しの一致を優先して表示します）。

overview／find／map は、Prisma スキーマ（schema.prisma → モデル、列挙型、フィールド、リレーション）にも対応しています。JSON の設定／i18n は構造化してマッピングされません。lens はその点を明示し、grep の使用を案内します。

.mdにコード用ツール（または.tsにドキュメント用ツール）を呼び出すと、適切なツールを案内するメッセージとともに失敗します。原因が分からないまま処理されることはありません。

設計段階から誠実に

• データを黙って失うことはありません — 構文エラーのあるファイルではhasErrorsと parseErrorsを返し、可能な範囲で解析を続けます。map／findでは解析できないファイルもインラインのerror付きで表示され、消えることはありません。
• あらゆる場所に上限を設けています — すべてのリストに上限があり（info.limitsを参照）、各上限について実際の合計件数を報告します。出力が無制限のコンテキスト節約ツールは、自己矛盾しています。
• パスをサンドボックスで制限します — 読み取り可能なのはサーバーの作業ディレクトリ配下のファイルのみで、外部へ抜けるシンボリックリンクは拒否されます。ルートはinfoで報告します。
• エラーには修正方法が示されます — {error, path, hint}を返し、isErrorを設定します。

インストール

次の1行でクローン、インストールを行い、このインストール先の絶対パスを含む、すぐに貼り付けられる MCP 設定を作成します。

git clone https://github.com/segentic-lab/lens-mcp && cd lens-mcp && ./install.sh

システムパッケージもネイティブビルドも不要です。tree-sitter は WebAssembly として実行されるため、Node 18+ が動作する環境であればどこでも使えます（Linux、macOS、Windows の WSL／Git Bash）。インストーラーは Node を確認し、npm ci を実行してビルド（tsc → dist/）し、全テスト（143件）でセルフテストを行い、mcp-config.json を生成します。

クライアントに登録する — 生成される mcp-config.json は次のようになります。

{
  "mcpServers": {
    "lens": { "command": "node", "args": ["/abs/path/lens-mcp/dist/index.js"] }
  }
}

• Claude Code： claude mcp add lens -- node /abs/path/lens-mcp/dist/index.js（または mcp-config.json をプロジェクトに .mcp.json としてコピーします）
• Cursor / Windsurf： mcp-config.json を ~/.cursor/mcp.json にマージします
• Codex CLI： 同じコマンド／引数を指定して、[mcp_servers.lens] を ~/.codex/config.toml に追加します

lens が読み取るのは、作業ディレクトリ（クライアントが起動するプロジェクト）内のファイルです。プロジェクトを指定して map(".") を呼び出してください。作業ディレクトリ外は読み取れません。

後でその場で更新するには、次を実行します。

./update.sh          # git pull --ff-only + reinstall + self-test

_{手動で行う場合は、npm install && npm run build && npm test を実行してから、node dist/index.js を実行してください。}

系譜

lens-mcp は、従来の分割サーバー codelens-mcp（コード）と docslens-mcp（ドキュメント）を継承しています。エンジンはそのままに、1つのサーバー、1つのパイプラインに統合しています。periscope-mcp（Web アプリの QA）と姉妹プロジェクトであり、同じ基準に基づいて開発されています。エラーを正直に伝えること、あらゆる箇所で上限と切り詰めフラグを設けること、ドキュメントと動作を一致させること、リリース前にテストすることを徹底しています。

Segentic Lab が開発しました。AGPL-3.0。