de en es ja ko ru zh

semantic-code-intelligence

Name: semantic-code-intelligence
Author: saitarrun

by saitarrun

Overview Schema Source Related Servers Discussions Admin

Python

Local

Semantic Code Intelligence

Локальный семантический поиск и цитируемые обзоры кода для программных репозиториев.

Semantic Code Intelligence разбирает репозиторий на чанки с учётом символов, индексирует эти чанки с помощью FAISS и BM25, объединяет оба набора результатов и ранжирует наиболее сильных кандидатов с помощью кросс-энкодера. Результаты содержат точные пути к файлам и диапазоны строк. Всё работает локально; ключ облачного API не требуется.

Что предоставляет

Гибридный семантический и лексический поиск по коду
Повышение значимости точных символов, путей и контекстных терминов
Метки надёжности поиска на основе согласованности результатов выдачи
Python AST разбор и структурный разбор для распространённых языков программирования
Точные цитаты, например src/auth.py:L42-L67
Веб-дашборд и REST API
Интерфейсы CLI, MCP и LSP
Локальные обзоры кода на базе Ollama с детерминированным запасным вариантом на основе фактов
Постоянное хранение индексов FAISS, BM25 и SQLite
Инкрементальное отслеживание файловой системы
Графы символов и зависимостей
Воспроизводимые бенчмарки индексации и поиска

Related MCP server: codebase-analyser

Требования

macOS или Linux
Python 3.10 или новее
Git
Примерно 2–4 ГБ свободного места на диске для зависимостей Python и локальных кэшей моделей
Необязательно: uv для более быстрого управления окружением
Необязательно: Ollama для генерируемых обзоров кода

Первые операции индексации и повторного ранжирования требуют доступа в интернет для загрузки весов моделей Hugging Face. После кэширования моделей поиск работает офлайн.

Быстрый старт на чистой машине

1. Клонируйте репозиторий

git clone https://github.com/saitarrun/Semantic-code-intelligence.git
cd semantic-code-intelligence

2. Создайте окружение и установите приложение

С помощью uv:

uv venv
source .venv/bin/activate
uv pip install -e .

С помощью стандартных инструментов Python:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Windows в настоящее время не является протестированной целевой платформой, но эквивалентная команда активации — .venv\Scripts\activate.

3. Загрузите модели поиска и создайте индекс

Загрузка моделей по умолчанию намеренно отключена, чтобы обычные запросы приложения никогда не вызывали неожиданный сетевой трафик. Явно разрешите загрузку при первой индексации и поиске:

export CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1

code-intel index .
code-intel query "Where is HybridRetrievalPipeline implemented?" --citations-only

unset CODE_INTEL_ALLOW_MODEL_DOWNLOADS

Это подготовит:

sentence-transformers/all-MiniLM-L6-v2 для плотных эмбеддингов
cross-encoder/ms-marco-MiniLM-L-6-v2 для повторного ранжирования

Индекс репозитория хранится в .code_intel_index/. Каталог содержит индекс FAISS, данные BM25 и метаданные SQLite; его не следует коммитить.

4. Запустите веб-приложение

code-intel serve --host 127.0.0.1 --port 8000

Откройте http://127.0.0.1:8000.

Дашборд включает:

Семантический поиск
Обзор кода
Карта зависимостей
Инструменты Diff и LSP
Управление выбором репозитория и переиндексацией
Индикаторы задержки по этапам и надёжности поиска

Индексация другого репозитория

Данные индекса по умолчанию хранятся внутри целевого репозитория:

code-intel index /absolute/path/to/project

Выполните поиск по этому репозиторию:

code-intel query \
  "How are access tokens validated?" \
  --dir /absolute/path/to/project

Используйте отдельный каталог индекса, если исходный репозиторий должен оставаться нетронутым:

code-intel index /absolute/path/to/project \
  --index-dir /absolute/path/to/index-storage

code-intel query \
  "Where is the database connection pool created?" \
  --dir /absolute/path/to/project \
  --index-dir /absolute/path/to/index-storage

Принудительно выполните чистую пересборку после изменения поведения парсера или эмбеддингов:

code-intel index /absolute/path/to/project --force

Семантический поиск

Рекомендуется гибридный режим. Он сочетает сходство по естественному языку с точным сопоставлением идентификаторов:

code-intel query "How does the application serve the web UI?"

Точный поиск символа:

code-intel query "Where is serve_ui implemented?"

Вернуть больше результатов:

code-intel query "authentication middleware" --top-k 10

Показать цитаты без вывода кода:

code-intel query "database transaction rollback" --citations-only

Выберите отдельную стратегию поиска для диагностики:

code-intel query "PaymentProcessor" --mode sparse
code-intel query "logic responsible for charging a customer" --mode dense
code-intel query "charge customer payment" --mode hybrid

Отключите повторное ранжирование кросс-энкодером, когда низкая задержка важнее точности:

code-intel query "configuration loader" --no-rerank

Как работает ранжирование

Конвейер гибридного поиска по умолчанию выполняет следующие этапы:

Расширяет типичные намерения разработчика детерминированными терминами предметной области кода.
Извлекает до 50 плотных кандидатов FAISS.
Извлекает до 50 лексических кандидатов BM25.
Объединяет до 60 уникальных кандидатов с помощью Reciprocal Rank Fusion.
Повторно ранжирует до 40 кандидатов локальным кросс-энкодером.
Повышает значимость точных символов, путей и совпадений контекстных терминов.
Удаляет дублирующиеся цитаты и ограничивает повторяющиеся результаты из одного файла.
Возвращает метку надёжности с подтверждающими её данными.

Надёжность — это не оценка уверенности LLM. Она отражает наблюдаемые сигналы поиска, такие как согласованность плотного/лексического поиска, точные совпадения символов, пересечение путей и семантическое сходство.

Обзоры кода

Режим детерминированных фактов

Этот режим не требует Ollama. Он возвращает найденные символы, области видимости, зависимости, фрагменты исходного кода и цитаты, не выдумывая поведение:

code-intel ask \
  "How does the indexing pipeline persist metadata?" \
  --provider extractive

Генерируемые локальные обзоры с Ollama

Установите и запустите Ollama, затем загрузите модель по умолчанию:

ollama pull qwen2.5-coder:7b

Запустите обзор с цитатами:

code-intel ask "Explain the hybrid retrieval control flow"

Используйте другую локальную модель или сервер Ollama:

export CODE_INTEL_OLLAMA_MODEL=deepseek-coder-v2:lite
export OLLAMA_BASE_URL=http://127.0.0.1:11434

Если Ollama недоступен, приложение явно помечает ответ как extractive-fallback и возвращает детерминированные данные из исходного кода.

Интерактивный CLI

Запустите непрерывную сессию поиска:

code-intel interactive --dir /absolute/path/to/project

Просмотрите статистику индекса:

code-intel stats --dir /absolute/path/to/project

Покажите все команды:

code-intel --help
code-intel query --help

REST API

Запустите сервер:

code-intel serve --host 127.0.0.1 --port 8000

Проверка состояния:

curl http://127.0.0.1:8000/api/health

Индексируйте репозиторий:

curl -X POST http://127.0.0.1:8000/api/index \
  -H 'Content-Type: application/json' \
  -d '{
    "target_dir": "/absolute/path/to/project",
    "force": false
  }'

Выполните гибридный поиск:

curl -X POST http://127.0.0.1:8000/api/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Where is token validation implemented?",
    "repo_path": "/absolute/path/to/project",
    "top_k": 5,
    "mode": "hybrid",
    "rerank": true
  }'

Сгенерируйте обзор:

curl -X POST http://127.0.0.1:8000/api/synthesize \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Explain token validation failure paths",
    "repo_path": "/absolute/path/to/project",
    "top_k": 8,
    "provider": "extractive"
  }'

Важные конечные точки:

Method	Endpoint	Purpose
`GET`	`/api/health`	Состояние сервиса и индекса
`GET`	`/api/stats`	Файлы, строки, чанки и манифест индекса
`GET`	`/api/index/stream`	SSE-прогресс индексации
`POST`	`/api/index`	Синхронная индексация репозитория
`POST`	`/api/search`	Плотный, разреженный или гибридный поиск
`POST`	`/api/synthesize`	Ответ по коду с цитатами
`POST`	`/api/synthesize/stream`	Потоковый ответ с цитатами
`GET`	`/api/graph`	Граф символов и зависимостей
`POST`	`/api/watcher/toggle`	Запуск или остановка инкрементального отслеживания
`GET`	`/api/lsp/inspect`	Определения, ссылки и данные при наведении
`POST`	`/api/patch/generate`	Создание предлагаемого unified diff
`POST`	`/api/patch/apply`	Применение unified diff к выбранному репозиторию

Привязывайте сервер к 127.0.0.1, если удалённый доступ не требуется намеренно. Конечные точки патчей и открытия файлов работают с локальной файловой системой и не должны быть доступны из недоверенных сетей.

Интеграция MCP

MCP-сервер позволяет VS Code, Cursor, Claude Code и другим совместимым агентам кодинга искать по проиндексированной кодовой базе и получать точные диапазоны исходного кода. Сначала установите проект и создайте индекс:

git clone https://github.com/saitarrun/Semantic-code-intelligence.git
cd Semantic-code-intelligence
python -m venv .venv
source .venv/bin/activate
pip install -e .
code-intel index --dir /absolute/path/to/your/project

В приведённых ниже примерах используйте абсолютный путь к исполняемому файлу, выводимый командой which code-intel.

VS Code

Создайте .vscode/mcp.json в проекте, который должен искать агент:

{
  "servers": {
    "semanticCodeIntelligence": {
      "type": "stdio",
      "command": "/absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel",
      "args": ["mcp", "--dir", "${workspaceFolder}"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Выполните MCP: List Servers из палитры команд, запустите semanticCodeIntelligence и одобрите его инструменты. Если старый список инструментов закэширован, выполните MCP: Reset Cached Tools.

Cursor

Создайте .cursor/mcp.json в целевом проекте:

{
  "mcpServers": {
    "semantic-code-intelligence": {
      "command": "/absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel",
      "args": ["mcp", "--dir", "${workspaceFolder}"]
    }
  }
}

Claude Code

Зарегистрируйте локальный stdio-сервер из проекта, по которому хотите выполнять поиск:

claude mcp add --transport stdio --scope project semantic-code-intelligence -- \
  /absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel mcp --dir /absolute/path/to/your/project
claude mcp get semantic-code-intelligence

Для другого MCP-совместимого агента настройте тот же исполняемый файл как локальный stdio-сервер с аргументами mcp --dir /absolute/path/to/your/project. Сервер пишет в stdout только JSON-RPC сообщения, как требуется для stdio-клиентов.

Доступные MCP-инструменты:

code_intel_search: гибридный, плотный или разреженный поиск с точными строками и метаданными надёжности
code_intel_symbol_graph: данные о зависимостях и графе вызовов для репозитория или символа
code_intel_index: создание или обновление индекса из агента кодинга
code_intel_read_file: безопасное чтение до 400 строк в пределах настроенного репозитория

Целевой проект должен быть проиндексирован до поисковых запросов. По умолчанию его индекс хранится в <project>/.code_intel_index; передайте --index-dir /path/to/index в MCP-команду, если используется отдельный каталог индекса. Загрузка моделей остаётся добровольной: установите CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1, если модель эмбеддингов или повторного ранжирования ещё не закэширована.

LSP и наблюдатель файловой системы

Запустите stdio LSP-мост:

code-intel lsp --dir /absolute/path/to/project

Запустите инкрементальный наблюдатель:

code-intel watch --dir /absolute/path/to/project

Наблюдатель отслеживает поддерживаемые исходные файлы и обновляет состояние индекса после изменений. Используйте Ctrl+C, чтобы остановить любой из процессов.

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

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

Variable	Default	Description
`CODE_INTEL_ALLOW_MODEL_DOWNLOADS`	`0`	Установите `1`, чтобы разрешить загрузку моделей Hugging Face
`CODE_INTEL_OLLAMA_MODEL`	`qwen2.5-coder:7b`	Модель Ollama, используемая для генерируемых обзоров
`OLLAMA_BASE_URL`	`http://127.0.0.1:11434`	Базовый URL API Ollama
`CODE_INTEL_CORS_ORIGINS`	Localhost origins	Разрешённые API источники браузера через запятую
`CODE_INTEL_PIPELINE_CACHE_SIZE`	`4`	Максимальное количество конвейеров репозиториев, кэшируемых API

Программная конфигурация:

from pathlib import Path

from semantic_code_intel.config import CodeIntelConfig
from semantic_code_intel.indexing.engine import HybridIndexer
from semantic_code_intel.retrieval.pipeline import HybridRetrievalPipeline

project = Path("/absolute/path/to/project")
config = CodeIntelConfig(project_root=project)
config.retrieval.dense_top_k = 75
config.retrieval.sparse_top_k = 75
config.retrieval.final_top_k = 8

HybridIndexer(config).index_codebase(project)
response = HybridRetrievalPipeline(config).query(
    "Where is request authentication enforced?",
    top_k=8,
)

for result in response.results:
    print(result.citation, result.chunk.symbol_name, result.score)

print(response.reliability, response.reliability_reasons)

Поддерживаемые файлы

Сканер по умолчанию включает:

Python
JavaScript и TypeScript
Go
Rust
Java
C и C++
C#
Ruby
PHP
Swift
Kotlin и Scala
Скрипты оболочки
SQL
HTML и CSS
JSON, YAML, TOML и Markdown

Общие генерируемые каталоги, виртуальные окружения, папки зависимостей, lock-файлы, бинарные файлы, минифицированные ресурсы, .git, .code_intel_index и oss_evaluation по умолчанию исключены. Смотрите ParserConfig в semantic_code_intel/config.py, чтобы настроить расширения и шаблоны игнорирования.

Архитектура

flowchart LR
    A[Repository] --> B[Scanner and ignore rules]
    B --> C[Python AST or polyglot parser]
    C --> D[Symbol-aware chunks]
    D --> E[Local embedding model]
    E --> F[(FAISS)]
    D --> G[Code-aware tokenizer]
    G --> H[(BM25)]
    D --> I[(SQLite metadata)]

    Q[Query] --> X[Intent expansion]
    X --> F
    X --> H
    F --> R[Reciprocal Rank Fusion]
    H --> R
    R --> J[Cross-encoder reranker]
    J --> K[Exact symbol and path boosts]
    K --> L[Diversity and reliability]
    L --> M[CLI, API, Web, MCP, LSP]

Основные модули:

Package	Responsibility
`parser`	Сканирование репозитория и структурное разбиение кода на чанки
`indexing`	Эмбеддинги, FAISS, BM25, SQLite и отслеживание
`retrieval`	Расширение запросов, объединение, повторное ранжирование, надёжность и цитаты
`generation`	Обоснованные промпты, синтез через Ollama и детерминированный запасной вариант
`api`	Конечные точки FastAPI и веб-дашборд
`cli`	Интерфейсы командной строки
`graph`	Графы символов и зависимостей
`mcp`	Сервер Model Context Protocol
`lsp`	Мост Language Server Protocol
`benchmark`	Генерация синтетических репозиториев и оценка поиска

Тестирование

Запустите полный набор тестов:

uv run pytest -q

Или с активированным окружением:

pytest -q

Набор покрывает парсеры, FAISS, BM25, расширение запросов, повышение значимости точных совпадений, объединение, цитаты, конечные точки API, локальное поведение синтеза, MCP, LSP, патчи, отслеживание и генерацию бенчмарков.

Бенчмаркинг

Запустите воспроизводимый синтетический бенчмарк:

code-intel benchmark \
  --workspace ./benchmark_workspace \
  --loc 40000 \
  --queries 30

Исполнитель записывает benchmark_report.json, содержащий:

Размеры набора данных и индекса
Пропускная способность индексации
Процентили задержки плотного, разреженного, повторного ранжирования и сквозного поиска
Доля попаданий и средний обратный ранг
Записи выполненных запросов
Метаданные Python, платформы, оборудования, пакетов и моделей

Результаты бенчмарков зависят от оборудования, состояния кэша моделей, состава репозитория и набора запросов. Относитесь к историческим показателям как к измерениям, а не гарантиям.

Поиск и устранение неполадок

Модель недоступна локально

Выполните завершившуюся с ошибкой операцию один раз с включённой загрузкой:

CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 code-intel index /absolute/path/to/project --force
CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 code-intel query "warm up reranker" --dir /absolute/path/to/project

Индекс не найден

Значения --dir и --index-dir, используемые для поиска, должны совпадать с использованными при индексации.

code-intel stats --dir /absolute/path/to/project

Обзор сообщает, что Ollama недоступен

Проверьте локальный сервер и установленные модели:

ollama list
curl http://127.0.0.1:11434/api/tags

Вы всегда можете использовать режим детерминированных фактов:

code-intel ask "your question" --provider extractive

Результаты поиска слабые

Используйте точное имя класса, функции, метода, конечной точки или конфигурации, если оно известно.
Для обычного использования предпочитайте гибридный режим.
Увеличьте --top-k, если ответ охватывает несколько файлов.
Переиндексируйте с помощью --force после изменения конфигурации парсера или эмбеддингов.
Проверяйте индикатор надежности; низкая надежность означает, что поисковые сигналы недостаточно согласованы.

Порт сервера уже занят

Выберите другой порт:

code-intel serve --host 127.0.0.1 --port 8010

Статус проекта

Проект находится в активной разработке. Проверяйте сгенерированные патчи перед их применением, держите API привязанным к localhost для обычного использования и проверяйте утверждения о производительности на собственных целевых репозиториях.

Лицензия

Открытая лицензия пока не добавлена. Публичный доступ к репозиторию сам по себе не дает разрешения на копирование, изменение или распространение кода.

Available Tools

4 tools

code_intel_indexC

Build or refresh the semantic and lexical indexes for a local repository.

ParametersJSON Schema

Name	Required	Description
`force`	No
`index_dir`	No	Optional index storage directory.
`repo_path`	No	Repository root; defaults to the server --dir.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full behavioral burden. It doesn't disclose cost/duration (indexing can be slow), whether it blocks, whether it overwrites existing indexes, or what happens on failure. 'Refresh' hints at mutation but no depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single clear sentence with verb and scope front-loaded, zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations, no output schema, and an undocumented 'force' parameter, the description is too thin. It leaves the agent guessing about cost, prerequisites, and the effect of force.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, with index_dir and repo_path already documented in the schema. The 'force' parameter (schema has no description) is undocumented anywhere, and the description doesn't compensate. Baseline 3 given partial coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Build or refresh') and resource ('semantic and lexical indexes for a local repository'). It's distinct from siblings like code_intel_search, though it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to run this versus using existing indexes, nor prerequisites like whether search requires prior indexing. Purely descriptive, no when-to-use direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_intel_read_fileB

Read a bounded line range from a source file inside the configured repository.

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Repository-relative or absolute file path.
`end_line`	No	Inclusive; at most 400 lines are returned.
`repo_path`	No	Repository root; defaults to the server --dir.
`start_line`	No

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose two useful traits: reads are bounded to a line range and restricted to the configured repository. However, it never states that the operation is read-only/side-effect free, nor how it behaves on a missing file, an out-of-repo absolute path, or a range exceeding the cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the core action and its two constraints are stated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter read tool with no annotations and no output schema, the description is adequate but thin: it omits read-only confirmation, error/edge-case behavior, and any hint of the return shape (raw lines vs numbered lines). An agent can call it, but cannot fully predict its behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema already documents path, end_line, and repo_path; only start_line's default relies on the schema's default keyword. The description's 'bounded line range' and 'inside the configured repository' echoes rather than extends the end_line cap and repo_path semantics, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Read a bounded line range from a source file') and scopes it to the configured repository, which is enough for an agent to distinguish it from code_intel_search, code_intel_symbol_graph, and code_intel_index. It stops short of explicitly naming which sibling to use when, but the purpose itself is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as code_intel_search for locating content versus this tool for reading it. An agent must infer the read-content use case purely from the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_intel_searchB

Search indexed code with hybrid semantic and lexical retrieval, exact citations, match reasons, and reliability scoring.

ParametersJSON Schema

Name	Required	Description	Default
`mode`	No		hybrid
`query`	Yes	Question, behavior, or symbol to find.
`top_k`	No
`rerank`	No
`index_dir`	No	Optional index storage directory.
`repo_path`	No	Repository root; defaults to the server --dir.

TDQS

B3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose some behavioral traits: hybrid semantic/lexical retrieval, exact citations, match reasons, and reliability scoring. However it omits key operational facts such as whether the index must already exist, which repo/index is targeted by default, and whether results are bounded or truncated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; every clause adds information. It is efficient, though the terse packing of output traits without any usage context borders on under-specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with no annotations, no output schema, and half the parameters undocumented, the description is only partially complete. It hints at the return content (citations, match reasons, reliability) but leaves prerequisites and most parameter behavior unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%, and the description adds no parameter meaning at all – it does not explain mode options (hybrid/dense/sparse), rerank, top_k limits, index_dir, or repo_path defaults. An agent must infer the effect of switching from hybrid to dense/sparse with no help.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search indexed code") and names the retrieval techniques (hybrid semantic + lexical) plus output traits, so the agent knows this is a code search tool. It does not name or differentiate itself from siblings like code_intel_symbol_graph or code_intel_read_file, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this over code_intel_symbol_graph (symbol relations) or code_intel_read_file (direct reads), nor any preconditions such as needing the repository indexed first. Usage is only weakly implied by the verb "Search".

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_intel_symbol_graphC

Return repository dependency/call-graph data, optionally centered on a symbol.

ParametersJSON Schema

Name	Required	Description
`symbol`	No	Optional function, class, or symbol name.
`index_dir`	No	Optional index storage directory.
`repo_path`	No	Repository root; defaults to the server --dir.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does state that symbol centering is optional and that graph data is returned, but says nothing about output format, graph depth/limits, whether an index must exist first (relevant given index_dir), or cost/size of the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with no waste, front-loading the resource (dependency/call-graph data) before the optional scoping. Very brief, which is efficient but leaves little room for behavioral detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with no annotations and no output schema, the description is minimally adequate. It should mention whether an index is required beforehand and what the returned graph looks like, since an agent has no other source for that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already documented. The description only adds that symbol centering is optional, which is already reflected in the schema's 'Optional' prefix; baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Return) and resources (dependency/call-graph data) with a scoping qualifier (optionally centered on a symbol). Clear enough to distinguish from siblings like code_intel_search or code_intel_read_file, though it doesn't explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus code_intel_search (symbol lookup) or code_intel_index (index building). The optional symbol scoping is implied but no conditions or prerequisites are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.0Sep 11, 2026
- First observedcode_intel_index
- First observedcode_intel_read_file
- First observedcode_intel_search
- First observedcode_intel_symbol_graph

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-09-11 14:40 across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: indexing, hybrid search, dependency/call-graph retrieval, and bounded file reading. Although search and read_file both return code, their boundaries are clear from descriptions (retrieval vs direct file access).

Naming Consistency4/5

All tools share the consistent code_intel_ prefix, which provides a predictable namespace. However, suffixes mix verb forms (search, index) and noun forms (symbol_graph), so the pattern is mostly but not perfectly consistent.

Tool Count5/5

Four tools is well-scoped for a code intelligence server, covering the essential operations of indexing, searching, graph exploration, and reading without redundancy or bloat.

Completeness4/5

The core lifecycle (index → search → explore graph → read file) is covered, but missing operations such as listing indexed repositories, retrieving symbol definitions, or index management could create minor dead ends for some agent workflows.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

ref-tools-mcp AOAuth
tools.ref
Token-efficient search for coding agents over public and private documentation.
Documentation Access Search Coding Agents
221,180
GraphifyOAuth
io.github.Graphify-Labs
Search indexed code, trace dependencies, assess change impact, and recall repository memory.
Code Analysis Knowledge & Memory
1
Maguyva
ai.maguyva
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code Analysis Coding Agents
23
ContextStream MCP ServerOAuth
io.github.contextstream
Project memory, semantic code search, and grounded agent context.
Knowledge & Memory Code Analysis RAG Systems
144

Related MCP Servers

Qurio MCP Server
RAG Systems Search
irahardianto
A
license
Not graded
quality
D
maintenance
Enables AI coding assistants to search and retrieve information from a locally ingested knowledge base using hybrid search, grounded in user-curated documentation.
Updated 8 months ago (2026-02-15 22:06 UTC)
16
MIT
codebase-analyser
akshith120
F
license
Not graded
quality
D
maintenance
Enables AI agents and IDEs to ingest and search code repositories using hybrid retrieval (dense + sparse) with exact line-level citations for precise code analysis.
Updated 3 months ago (2026-07-20 14:32 UTC)
1
-
shelfmark
RAG Systems Knowledge & Memory Search
LucasSantana-Dev
A
license
A
quality
A
maintenance
Enables coding agents to query local notes, decisions, docs, and code with hybrid retrieval (BM25 + embeddings + reranking) and get path:line citations. It provides tools like rag_query for full-corpus search and search_knowledge for project-scoped knowledge recall.
Updated 8 days ago (2026-10-06 23:56 UTC)
2
1
MIT
LexiconLocal
Knowledge & Memory RAG Systems Search
alexeymohr
A
license
A
quality
B
maintenance
Enables coding agents to search a local, offline archive of past sessions and repository Markdown docs using hybrid lexical and semantic retrieval, and read matching records to ground new work in prior knowledge without external calls.
Updated a month ago (2026-09-11 16:18 UTC)
2
MIT