mcplens

AIコーディングアシスタント向けのセマンティックコードベース検索 — トークンを70〜85%削減、100%ローカル動作、クラウド依存ゼロ。

Claude Code、Cursor、CodexのようなAIコーディングアシスタントは強力ですが、根本的な問題を抱えています。質問をすると、パスやファイル名のヒューリスティックに基づいて関連しそうなファイルを推測して読み込むのです。中規模のプロジェクトでは、1回のクエリで、関連すらしていない可能性のあるファイルを読み込むだけで10,000〜20,000トークンのコンテキストを消費してしまうことがあります。

claude-context-optimizerは、AIアシスタントにコードベースのセマンティック検索機能を提供することで、この問題を解決します。ファイルを闇雲に読み込む代わりに、search_code("how does payment work?")を呼び出し、最も関連性の高い5つのコードチャンクのみを取得します。これらはローカルで埋め込みを使用してインデックス化され、SQLiteに保存されるため、データがマシンから外部へ出ることはありません。

仕組み

プロジェクトでAIアシスタントを開くと：

1. MCPサーバーが自動的に起動します（アシスタントによってstdio経由で生成されます）

2. ファイルハッシュを前回のインデックスと比較し、変更されたものだけを再インデックス化します（デルタインデックス）

3. ファイルウォッチャーが、コーディングに合わせてインデックスを同期し続けます

4. アシスタントは、生のファイルを読み込む代わりに、3つのセマンティック検索ツールにアクセスできるようになります

You ask: "how does the Asaas webhook work?"

Without cco: With cco:
 Read AsaasWebhookController.php search_code("asaas webhook")
 Read AsaasWebhookService.php → returns 5 relevant chunks
 Read PaymentService.php → ~800 tokens total
 Read BillingModule.php
 Read ...8 more files
 → ~15,000 tokens total

内部構造

• 埋め込み: Ollama と nomic-embed-text (768次元) を使用 — 100%ローカル、無料、APIキー不要

• ベクトルストア: SQLite（プロセス内でコサイン類似度を計算） — 追加のインフラ不要

• チャンク分割: tree-sitterによるAST認識（関数/クラス単位で分割）およびスライディングウィンドウによるフォールバック

• トランスポート: MCP stdio — アシスタントがプロセスを生成し、パイプ経由で通信

• 永続化: インデックスは .claude-context/index.db に保存され、セッション間でも保持されます

Related MCP server: CodeRAG

互換性

claude-context-optimizerは、MCP互換のあらゆるAIコーディングアシスタントで動作します。MCP（Model Context Protocol）はオープン標準であり、同じサーバーが修正なしですべてのクライアントで動作します。

initコマンドは、使用しているアシスタントを検出し、適切な場所にサーバーを自動的に登録します。

トークンの節約

インデックスはローカルに保持されます。アシスタントは関連する情報のみを取得します。数字がその効果を物語っています：

これらはコンテキストトークンであり、ユーザーが制御できる部分です。プロジェクトが大きくなるほど、デフォルトのヒューリスティックなファイル読み込みが頻発するため、節約効果は拡大します。

提供されるツール

アシスタントをガイドするために、プロジェクトの CLAUDE.md（または同等のファイル）に以下を追加してください：

## Context Search

Always use MCP tools before reading files:

- search_code() — for conceptual or natural language queries
- get_symbol() — for exact class/function/method lookups
 Only read full files if both tools return insufficient context.

インストールオプション

オプション A — npm (Ollamaが必要)

オーバーヘッドなし。すでにOllamaがインストールされている開発者に最適です。

npm install -g @vmsfigueredo/mcplens
ollama pull nomic-embed-text:latest
cd your-project && mcplens init

完全なセットアップ手順については INSTALL.md を参照してください。

オプション B — Docker

現在利用できません。 Docker配布（Node + Ollama + モデルのバンドル）は計画中ですが、未実装です。ロードマップで進捗を確認してください。

設定

.claude-context/config.json は init によって自動的に作成されます。編集して動作をカスタマイズできます：

{
 "embeddings": {
 "provider": "ollama",
 "ollamaUrl": "http://localhost:11434",
 "ollamaModel": "nomic-embed-text:latest"
 },
 "search": {
 "topK": 5,
 "minScore": 0.3
 },
 "ignore": [
 "**/tests/fixtures/**"
 ]
}

OpenAIの埋め込みを使用する場合：

{
 "embeddings": {
 "provider": "openai",
 "openaiApiKey": "sk-...",
 "openaiModel": "text-embedding-3-small"
 }
}

インデックス対象

デフォルトで含まれるもの: .ts .tsx .js .jsx .mjs .php .svelte .vue .py .rb .go .rs .css .scss .json .yaml .yml .md .sql

デフォルトで無視されるもの: node_modules, .git, vendor, dist, build, .next, .claude-context

.claude-context/ ディレクトリは自動的に .gitignore に追加されます。

インデックスサイズの目安

ダッシュボード

サーバー実行中、http://localhost:3000 で軽量なWebダッシュボードを利用できます：

• 概要 — インデックスされたファイル数、チャンク数、インデックスサイズ、Ollamaの状態

• アクティビティ — 再インデックスイベントのライブフィード

• 検索 — 手動でクエリをテストし、スコアを確認（minScoreの調整に便利）

• ファイル — インデックスされたファイルの全リストとチャンク数

ダッシュボードはデフォルトでポート 3333 で実行されます。そのポートが既に使用されている場合（例：同時に2つのプロジェクトを開いている場合）、プロジェクト名からポートが自動的に計算されます。開くには：

mcplens dashboard

無効にするには：MCP設定のサーバー引数に --no-dashboard を追加してください。

プライバシー

すべてがあなたのマシン上で実行されます：

• 埋め込みはOllama経由でローカルに生成されます — コードが外部に出ることはありません

• インデックスはプロジェクト内の .claude-context/index.db に保存されます

• テレメトリ、分析、アカウント登録は一切ありません

⚠️ OpenAI埋め込みオプションを使用する場合、チャンクはOpenAIのAPIに送信されます。

なぜ既存のツールを使わないのか？

目標は、最も機能が豊富なツールではなく、JS/TS開発者にとって最も利用しやすい選択肢になることです。Node.jsがインストールされていれば、コマンド一つで利用可能です。

ロードマップ

• [x] tree-sitterによるASTベースのチャンク分割

• [x] ファイルハッシュによるデルタインデックス

• [x] リアルタイムファイルウォッチャー

• [x] ダッシュボード

• [x] マルチクライアント対応のinit (Claude Code, Cursor, Windsurf, Trae)

• [x] ハイブリッド検索 (BM25 + セマンティック)

• [ ] Ollamaバンドル版Dockerオプション

• [ ] コンテキスト検索 (LLM生成によるチャンク要約)

• [ ] Claude Codeフック経由のトークン使用量分析

貢献

プルリクエストを歓迎します。ローカル開発環境のセットアップについては INSTALL.md を参照してください。

開発環境

このプロジェクトはClaude Codeを使用して構築されました。それこそが、このプロジェクトが存在する理由です。

ライセンス

MIT

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers