mcp-deepcontext

MCP-сервер, обеспечивающий семантический поиск с учетом символов в Claude Code

мотивация

Большинство инструментов поиска по коду рассматривают код как текст, игнорируя семантическую структуру, которая делает код осмысленным. Когда вы работаете с большой кодовой базой, вы хотите не просто найти, где встречается строка. Вы хотите найти, где вызывается функция, где реализован тип или какие модули зависят от конкретного символа.

Этот MCP-сервер устраняет этот разрыв, предоставляя Claude возможности семантического анализа кода. Вместо поиска текста через grep, Claude может задавать вопросы вроде «где реализован этот интерфейс?» или «кто вызывает эту функцию?» и получать точные результаты с учетом символов. Это позволяет вести действительно полезные обсуждения о незнакомых кодовых базах.

архитектура

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[mcp-deepcontext Server]
    B -->|Parse & Index| C[Symbol Database]
    B -->|AST Analysis| D[TypeScript Compiler API]
    B -->|Semantic Search| E[Vector Embeddings]
    
    C -->|Symbol Locations| B
    D -->|Type Information| B
    E -->|Similarity Scores| B
    
    F[Your Codebase] -->|Watch & Reindex| B

начало работы

установка

npm install -g mcp-deepcontext

быстрый старт

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "deepcontext": {
      "command": "mcp-deepcontext",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

Затем перезапустите Claude Desktop. Сервер проиндексирует вашу кодовую базу при запуске.

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

Сервер использует API компилятора TypeScript для построения полного графа символов вашей кодовой базы. Это включает определения типов, сигнатуры функций, иерархии классов и отношения импорта. Когда Claude запрашивает информацию, сервер может ответить, предоставив точные местоположения и контекст.

Для семантического поиска сервер генерирует эмбеддинги для символов кода и их окружающего контекста. Это позволяет выполнять нечеткий поиск по смыслу, а не по точному совпадению текста. База данных символов синхронизируется с изменениями файлов с помощью файлового наблюдателя, который запускает инкрементальную переиндексацию.

Протокол MCP предоставляет это через такие инструменты, как search_symbols, find_references, get_definition и find_implementations. Claude может объединять их для ответа на сложные вопросы о структуре кода и связях.

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

Сервер принимает следующие аргументы командной строки:

• --workspace <path>: Корневой каталог проекта для индексации (обязательно)

• --languages <list>: Список языков для индексации через запятую (по умолчанию: typescript,javascript)

• --exclude <patterns>: Glob-шаблоны для исключения (по умолчанию: node_modules,dist,build,.git)

• --max-file-size <bytes>: Пропускать файлы больше этого размера (по умолчанию: 1 МБ)

• --embedding-model <name>: Модель для использования в эмбеддингах (по умолчанию: text-embedding-3-small)

Переменные окружения:

• OPENAI_API_KEY: Требуется для генерации эмбеддингов

• DEEPCONTEXT_LOG_LEVEL: Установите debug для подробного логирования

часто задаваемые вопросы

В: Какие языки поддерживаются?

В настоящее время TypeScript и JavaScript с полной поддержкой типов. Планируется поддержка Python и Go.

В: Работает ли это с большими кодовыми базами?

Да, индексация инкрементальная, а база данных символов использует эффективную структуру графа. Протестировано на кодовых базах до 500 тыс. строк без проблем.

В: Сколько стоит генерация эмбеддингов?

Для типичной кодовой базы в 100 тыс. строк начальная индексация генерирует около 10 тыс. эмбеддингов, что стоит примерно $0.02 с использованием text-embedding-3-small. Инкрементальные обновления обходятся гораздо дешевле.

В: Можно ли использовать это без эмбеддингов?

Да, передайте --no-embeddings, чтобы отключить семантический поиск. Вы по-прежнему получите все инструменты с учетом символов, такие как поиск ссылок и переход к определению.

В: Отправляет ли это мой код во внешние сервисы?

Только извлеченные имена символов и их непосредственный контекст отправляются в OpenAI для генерации эмбеддингов. Вы можете отключить это с помощью --no-embeddings для полностью локальной работы.

лицензия

MIT