mcplens

Семантический поиск по кодовой базе для ИИ-ассистентов — сокращение токенов на 70-85%, 100% локально, нулевая зависимость от облака.

ИИ-ассистенты для программирования, такие как Claude Code, Cursor и Codex, очень мощные, но у них есть фундаментальная проблема: когда вы задаете вопрос, они читают файлы, пытаясь угадать, какие из них релевантны, основываясь на эвристиках путей и имен файлов. В проекте среднего размера один запрос может потреблять 10 000–20 000 токенов контекста только на загрузку файлов, которые могут даже не быть релевантными.

claude-context-optimizer решает эту проблему, предоставляя вашему ИИ-ассистенту семантический поиск по вашей кодовой базе. Вместо того чтобы читать файлы вслепую, он вызывает search_code("how does payment work?") и получает обратно только 5 наиболее релевантных фрагментов кода — проиндексированных локально с использованием эмбеддингов, хранящихся в SQLite, без передачи данных с вашего компьютера.

Как это работает

Когда вы открываете ИИ-ассистента в проекте:

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-dim) — 100% локально, бесплатно, без API-ключа

• Векторное хранилище: SQLite с косинусным сходством, вычисляемым внутри процесса — никакой дополнительной инфраструктуры

• Разбиение на фрагменты (Chunking): с учетом AST через tree-sitter (разделение по функциям/классам) с резервным вариантом скользящего окна

• Транспорт: MCP stdio — ассистент запускает процесс и общается через канал (pipe)

• Персистентность: Индекс хранится в .claude-context/index.db и сохраняется между сессиями

Related MCP server: LocalNest MCP

Совместимость

claude-context-optimizer работает с любым MCP-совместимым ИИ-ассистентом для программирования. 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.

Варианты установки

Вариант А — npm (требуется Ollama)

Нулевые накладные расходы. Лучший выбор для разработчиков, у которых уже установлена Ollama.

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

См. INSTALL.md для получения полных инструкций по настройке.

Вариант Б — Docker

Пока недоступно. Дистрибутив Docker (объединяющий Node + Ollama + модель) планируется, но еще не реализован. Следите за прогрессом в Roadmap.

Конфигурация

Файл .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.

Справочник размера индекса

Панель управления (Dashboard)

Легкая веб-панель доступна по адресу http://localhost:3000 во время работы сервера:

• Обзор — проиндексированные файлы, фрагменты, размер индекса, статус Ollama

• Активность — лента событий переиндексации в реальном времени

• Поиск — ручное тестирование запросов и просмотр оценок (полезно для калибровки minScore)

• Файлы — полный список проиндексированных файлов с количеством фрагментов

Панель управления по умолчанию работает на порту 3333. Если этот порт уже занят (например, открыты два проекта одновременно), порт рассчитывается автоматически на основе имени проекта. Чтобы открыть:

mcplens dashboard

Чтобы отключить: добавьте --no-dashboard к аргументам сервера в вашей конфигурации MCP.

Конфиденциальность

Все работает на вашем компьютере:

• Эмбеддинги генерируются локально через Ollama — ваш код никогда не покидает машину

• Индекс хранится в .claude-context/index.db в вашем проекте

• Никакой телеметрии, никакой аналитики, никаких учетных записей

⚠️ Если вы используете опцию эмбеддингов OpenAI, фрагменты кода отправляются в API OpenAI.

Почему не использовать существующие инструменты?

Цель — быть самым доступным вариантом для JS/TS разработчиков, а не самым функциональным. Если у вас уже есть Node.js, вас отделяет всего одна команда.

Дорожная карта

• [x] Разбиение на фрагменты на основе AST через tree-sitter

• [x] Дельта-индексация по хешу файла

• [x] Наблюдатель за файлами в реальном времени

• [x] Панель управления

• [x] Инициализация для нескольких клиентов (Claude Code, Cursor, Windsurf, Trae)

• [x] Гибридный поиск (BM25 + семантический)

• [ ] Docker-вариант с предустановленной Ollama

• [ ] Контекстный поиск (резюме фрагментов, созданные LLM)

• [ ] Аналитика использования токенов через хуки Claude Code

Участие в разработке

PR приветствуются. См. INSTALL.md для настройки локальной среды разработки.

Создано с помощью

Этот проект был создан с помощью Claude Code — именно поэтому он существует.

Лицензия

MIT