Ищите в частных документах из MCP-клиента или терминала, не отправляя их в embedding API.
mcp-local-rag индексирует PDF, DOCX, Markdown и текстовые файлы на вашем компьютере. Поиск сочетает семантическое сходство с сопоставлением по ключевым словам, поэтому запросы могут соответствовать как намерению, так и точным техническим терминам, таким как имена API, имена классов и коды ошибок.
Работает локально: Разбор документов, эмбеддинги, хранение и поиск выполняются на вашем компьютере. После первоначальной загрузки модели обработка текста и поиск работают офлайн.
Гибридный поиск: Семантический поиск находит связанные концепции, а сопоставление по ключевым словам усиливает точные технические термины.
Настраиваемые эмбеддинги: Выберите модель эмбеддингов Hugging Face, которая соответствует языку и домену ваших документов.
Семантическое разбиение на чанки: Документы разбиваются по границам тем, а не по фиксированному количеству символов. Блоки кода Markdown остаются нетронутыми.
MCP и CLI: Используйте один и тот же индекс из ИИ-инструмента для кодирования или непосредственно из терминала.
Не требуется API-ключ, Docker, Python или внешняя база данных.
Related MCP server: cowork-semantic-search
Node.js 22 или новее
Доступ в Интернет при первом использовании для загрузки npm-пакета и модели эмбеддингов
Каталог, содержащий документы, которые вы хотите искать
Установите BASE_DIR в этот каталог. Он также является границей безопасности для файловых операций. Замените
/absolute/path/to/your/documents ниже на абсолютный путь к каталогу.
mcp-local-rag использует стандартный протокол MCP через локальный stdio-сервер, поэтому он работает с ИИ-инструментами для кодирования и другими MCP-хостами, поддерживающими локальные MCP-серверы.
Используйте один из примеров ниже или зарегистрируйте npx -y mcp-local-rag и установите BASE_DIR с помощью
формата конфигурации MCP вашего клиента.
Для Claude Code: Выполните эту команду:
claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-ragДля Codex: Добавьте в ~/.codex/config.toml:
[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]
[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"Для OpenCode: Добавьте в ~/.config/opencode/opencode.json (или opencode.jsonc):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"local-rag": {
"type": "local",
"command": ["npx", "-y", "mcp-local-rag"],
"environment": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}Для Cursor: Добавьте в ~/.cursor/mcp.json:
{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": ["-y", "mcp-local-rag"],
"env": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}Перезапустите клиент, затем попросите его создать индекс:
Sync all documents in the configured root and wait until it finishes.Первая синхронизация загружает модель эмбеддингов по умолчанию (около 90 МБ) и может занять 1–2 минуты до начала обработки. Последующие запуски используют локальный кэш.
После завершения синхронизации:
What does the API documentation say about authentication?Чтобы использовать CLI без MCP-клиента:
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"CLI по умолчанию использует текущий каталог как корень документов. Запускайте обе команды из одного
каталога, чтобы они использовали один и тот же индекс по умолчанию, или явно задайте BASE_DIR и DB_PATH.
Некоторые наборы документов нельзя отправлять в размещённый сервис эмбеддингов из-за конфиденциальности или политики организации. Локальное хранение индекса делает их доступными для поиска без дополнительных затрат на каждый запрос.
Семантический поиск сам по себе может пропускать точные идентификаторы, которые важны в технической документации. Повторное ранжирование по ключевым словам сохраняет эти термины видимыми, не отказываясь от поиска на естественном языке.
Входные данные | Как обрабатывать |
PDF, DOCX, TXT, Markdown | Загрузка файлов или синхронизация каталога |
HTML, уже полученный клиентом |
|
Простой текст или Markdown в памяти |
|
Получение HTML не встроено в сервер. MCP-клиент может получить страницу и передать её HTML в
ingest_data.
Excel, PowerPoint, отдельные изображения и расширения файлов исходного кода не поддерживаются при загрузке файлов. PDF-файлы могут опционально использовать локальную модель зрения для описания рисунков, но это не OCR и не поиск по изображениям.
Инструмент | Назначение |
| Согласовать индекс со всеми настроенными корнями или одним путём |
| Опрашивать выполняющуюся задачу синхронизации |
| Загрузить или заменить один файл |
| Загрузить текст, Markdown или HTML, уже имеющийся у клиента |
| Поиск с семантическим сопоставлением и усилением по ключевым словам |
| Читать соседние чанки из результата поиска |
| Показать поддерживаемые файлы и их состояние загрузки |
| Удалить индексированный файл или элемент |
| Показать состояние индекса и поиска |
sync_start загружает новые и изменённые файлы, пропускает байт-идентичные файлы и удаляет записи индекса
для файлов, которые больше не существуют:
Sync everything under the configured document roots and wait for completion.Инструмент немедленно возвращает jobId. Клиенты должны опрашивать sync_status, пока его состояние не станет
succeeded или failed. Синхронизация не генерирует визуальные подписи. Установите STORE_IMAGES=true в
окружении MCP-сервера, чтобы сохранять поддерживаемые изображения PDF и DOCX для новых или изменённых файлов,
выбранных синхронизацией; неизменённые файлы остаются пропущенными.
Серверный процесс хранит только одну задачу синхронизации. Новая задача заменяет завершённую запись, а перезапуск сервера отбрасывает её.
ingest_file принимает PDF, DOCX, TXT и Markdown. Пути к файлам MCP должны быть абсолютными и должны оставаться
внутри настроенного корня документов:
Ingest the document at /Users/me/docs/api-spec.pdf.Повторная загрузка того же пути заменяет его существующие чанки.
What does the API documentation say about authentication?
Find the documented behavior of ERR_CONNECTION_REFUSED.Результаты содержат текст, путь к источнику, заголовок, индекс чанка, оценку релевантности и любые изображения,
сохранённые в этом чанке. MCP возвращает каждое изображение как блок контента изображения, связанный с идентификатором
результата; CLI query включает массив images из { imageIndex, mimeType, data } в каждом результате. Передайте
chunkIndex и либо filePath, либо source из результата в read_chunk_neighbors, когда ответу нужен
дополнительный контекст:
Read the surrounding chunks for that authentication result.Оба инструмента query_documents и list_files принимают необязательный абсолютный префикс пути scope или
список префиксов. Префикс соответствует точному пути и его потомкам.
Используйте ingest_data после того, как MCP-клиент получит страницу:
Fetch https://example.com/docs and ingest the HTML.Сервер извлекает основную статью, преобразует её в Markdown и сохраняет под указанным идентификатором источника. Повторное использование того же источника обновляет существующий контент.
Уважайте условия и авторские права исходного сайта при индексации внешнего контента.
Визуальный режим добавляет сгенерированную подпись для страниц PDF с большим количеством рисунков. Он включается вручную и не загружает модель зрения во время обычной загрузки.
Ingest /Users/me/docs/research-paper.pdf with visual: true.npx mcp-local-rag ingest ./docs/research-paper.pdf --visualХранение изображений не зависит от визуальных подписей. Установите STORE_IMAGES=true для MCP-сервера или
передайте --images в CLI при загрузке и синхронизации:
npx mcp-local-rag ingest ./docs/research-paper.pdf --images
npx mcp-local-rag sync ./docs/ --imagesХранение PDF использует обнаруженные области рисунков/таблиц. Хранение DOCX включает только изображения PNG/JPEG,
которые существующее преобразование Mammoth выводит как <img>; диаграммы, SmartArt и фигуры не отображаются
отдельно. Сохранённые изображения следуют за окружающим текстом в итоговый семантический чанк и не изменяют
ранжирование, оценки или количество результатов.
|
| Поведение PDF |
false | false | Только текст; без визуальных подписей или возвращаемых изображений. |
true | false | Сгенерированные подписи становятся доступным для поиска текстом; изображения не сохраняются и не возвращаются. |
true | true | Сгенерированные подписи становятся доступным для поиска текстом, а изображения из совпавших чанков возвращаются встроенными. |
false | true | Изображения прикрепляются к близлежащему сохранённому тексту PDF и возвращаются встроенными для совпавших чанков; VLM не импортируется, не загружается и не запускается. |
Профиль | Кэш модели | Вариант использования |
| около 250 МБ | Лёгкая визуальная индексация |
| около 2,9 ГБ | Рисунки, содержащие метки, аннотации или другой текст внутри изображения |
Выберите более крупную модель с помощью visualQuality: "quality" через MCP или
--visual-quality quality через CLI. Измеренный вывод на CPU был примерно вдвое медленнее, чем fast,
хотя результаты зависят от оборудования и обновлений модели.
Подписи — это вспомогательный текст, а не точные транскрипции. Относитесь к полученным подписям и тексту документов как к ненадёжному вводу, а не как к инструкциям.
При высоких лимитах совпавшие чанки и их вложения могут приблизиться к пределу контекста модели/клиента; выбирайте лимит запроса с учётом доступного контекста вызывающей модели.
CLI использует тот же парсер, эмбеддер и векторное хранилище без MCP-клиента:
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "authentication API"
npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"Глобальные параметры, такие как --db-path, --cache-dir и --model-name, указываются перед подкомандой.
Параметры подкоманды указываются после неё:
npx mcp-local-rag --db-path ./my-db query "authentication"Выполните npx mcp-local-rag --help для полной справки по командам.
CLI не читает конфигурацию MCP-клиента. Установите те же переменные окружения или флаги, если оба интерфейса
должны использовать общий индекс. В частности, MODEL_NAME и флаг CLI --model-name должны совпадать для
общей базы данных.
Усиление по ключевым словам включено по умолчанию. Группировка по разрыву релевантности, а также фильтры расстояния и файлов являются необязательными элементами управления для корпусов, которым требуется более строгий отбор результатов.
Переменная | По умолчанию | Описание |
|
| Коэффициент усиления по ключевым словам (0.0–1.0). 0 отключает повторное ранжирование по ключевым словам; 1 применяет максимальное усиление. |
| (не задано) |
|
| (не задано) | Отфильтровать результаты с низкой релевантностью (например, |
| (не задано) | Ограничить результаты топ-N файлами (например, |
Для спецификаций API и других документов, содержащих много идентификаторов, более сильный вес ключевых слов может улучшить ранжирование точных терминов:
"env": {
"RAG_HYBRID_WEIGHT": "0.7"
}0.7: немного более сильное переранжирование по точным терминам, чем по умолчанию
1.0: максимальное усиление по ключевым словам
При индексировании:
Парсер извлекает текст из входного формата.
Семантический чанкер находит границы тем и сохраняет Markdown-блоки кода.
Transformers.js создаёт эмбеддинги локально.
LanceDB хранит чанки, метаданные, векторы и полнотекстовый индекс.
При поиске:
Запрос эмбеддится той же моделью.
Векторный поиск находит семантически связанные чанки.
При настройке дополнительные фильтры по расстоянию и группам релевантности сужают кандидатов.
Полнотекстовые совпадения усиливают точные термины запроса.
Agent Skills предоставляют рекомендации по запросам и индексированию для ИИ-ассистентов:
npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codexУстановленные навыки охватывают формулировку запросов, уточнение результатов и индексирование HTML. Если навык mcp-local-rag не активируется автоматически, попросите ассистента использовать его явно.
MCP-сервер читает переменные окружения. CLI принимает перечисленные глобальные переменные окружения и флаги; хранение изображений при индексировании и синхронизации через CLI включается только с --images.
Переменная окружения | Флаг CLI | По умолчанию | Описание |
|
| Текущий каталог | Один корень документов; флаг CLI можно повторять в |
| Н/Д | (не задано) | JSON-массив корней документов; имеет приоритет над |
|
|
| Расположение векторной базы данных |
|
|
| Каталог кэша моделей |
|
|
| Эмбеддинг-модель Hugging Face |
|
|
| Максимальный размер файла в байтах |
|
|
| Минимальная длина чанка в символах (1–10000) |
| Н/Д |
| Только MCP-сервер: сохранять изображения из поддерживаемых PDF/DOCX и возвращать их с совпавшими чанками. CLI использует |
| Н/Д |
| Устройство выполнения ONNX Runtime |
| Н/Д |
| Тип данных эмбеддингов, передаваемый выбранной модели |
BASE_DIR и BASE_DIRS)mcp-local-rag разрешает файловые операции только внутри настроенных корней. Для нескольких корней BASE_DIRS должен быть JSON-массивом непустых путей:
export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'Конфигурация корней разрешается в следующем порядке:
Флаги CLI --base-dir <путь> (повторяемые в ingest, list и sync)
BASE_DIRS
BASE_DIR
Текущий каталог
Каждый источник заменяет источник с более низким приоритетом, а не объединяется с ним. Некорректная конфигурация BASE_DIRS приводит к ошибке, а не к откату на BASE_DIR или текущий каталог. status остаётся доступным в MCP, чтобы клиент мог сообщить об ошибке конфигурации.
npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag listПо умолчанию DB_PATH и CACHE_DIR задаются относительно рабочего каталога процесса. Указывайте абсолютные пути, если MCP-клиент может запускать сервер из разных каталогов проекта.
Задайте MODEL_NAME или передайте --model-name, чтобы выбрать эмбеддинг-модель Hugging Face, подходящую для языка и предметной области ваших документов.
mcp-local-rag генерирует эмбеддинги с помощью mean pooling и L2-нормализации. При выборе модели проверьте, соответствуют ли эти настройки её рекомендованной схеме инференса, поскольку метод пулинга может влиять на качество поиска.
Изменение MODEL_NAME, RAG_DEVICE или RAG_DTYPE может сделать существующие векторы несовместимыми. Используйте новый DB_PATH или удалите существующий индекс и выполните повторное индексирование после изменения конфигурации эмбеддингов.
Пример модели для английских документов — Xenova/bge-small-en-v1.5.
Доступ к файлам ограничен корнями BASE_DIR, BASE_DIRS или CLI-флага --base-dir.
Симлинки, ведущие за пределы всех настроенных корней, отклоняются.
Обработка документов и поиск не выполняют сетевых запросов после кэширования необходимых моделей.
Сервер рассчитан на одного локального пользователя и не предоставляет аутентификацию или контроль доступа.
Не запускайте несколько CLI- или MCP-писателей против одного DB_PATH. Только чтение может выполняться во время активной синхронизации.
Для резервного копирования индекса скопируйте его каталог DB_PATH, пока не активен ни один писатель.
Сначала необходимо индексировать документы. Выполните «List all ingested files», чтобы проверить.
Проверьте подключение к интернету. При работе через прокси настройте сетевые параметры. Модель также можно скачать вручную.
Лимит по умолчанию — 100 МБ. Разбейте большие файлы или увеличьте MAX_FILE_SIZE.
Проверьте количество чанков с помощью status. Большие документы с множеством чанков могут замедлять запросы. Рассмотрите возможность разбиения очень больших файлов.
Убедитесь, что пути к файлам находятся внутри одного из настроенных корней (BASE_DIR, любой записи BASE_DIRS или любого CLI-флага --base-dir). Используйте абсолютные пути.
BASE_DIRS принимает JSON-массив из одного или нескольких непустых строковых путей:
Корректно: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
Некорректно: BASE_DIRS=/a:/b (синтаксис с разделителями не поддерживается)
Некорректно: BASE_DIRS='[]' (пустой массив)
Проверьте синтаксис файла конфигурации
Полностью перезапустите клиент (Cmd+Q на Mac для Cursor)
Проверьте напрямую: npx mcp-local-rag должен запускаться без ошибок
Вклад приветствуется! См. CONTRIBUTING.md для настройки и рекомендаций.
Лицензия MIT. Бесплатно для личного и коммерческого использования.
Building a Local RAG for Agentic Coding: технический разбор семантического чанкинга и гибридного поиска.
Создано с помощью Model Context Protocol от Anthropic, LanceDB и Transformers.js.
Delete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided. Returns deleted (operation succeeded), removedChunks, and existed (whether anything was actually present).
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Source identifier used in ingest_data. Examples: "https://example.com/page", "clipboard://2024-12-30" | |
| filePath | No | Absolute path to the file (for ingest_file). Example: "/Users/user/documents/manual.pdf" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Mentions return fields but does not disclose side effects, permissions, or error cases (e.g., what happens if nothing matches).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. Purpose, usage, and return are clearly separated and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, constraints, and return values. Lacks explanation of edge cases (both params provided or neither) but is generally sufficient given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet description adds context by linking each parameter to the specific ingestion method and clarifying the mutual exclusivity requirement, which is not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and object (previously ingested file/data from vector database). Distinguishes from sibling tools which are for ingestion, listing, querying, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use filePath vs. source and states that at least one must be provided. Could further specify behavior if both are given or if the item does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest in-memory content as a string (use ingest_file for files on disk). The source identifier enables re-ingestion to update existing content. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to ingest (text, HTML, or Markdown) | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format but does not discuss side effects, idempotency, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste: first sentence states purpose and sibling alternative, second sentence adds key behavioral detail and return format. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nested object parameters and no output schema, the description covers purpose, parameters with examples, and return values. Lacks error conditions or prerequisites, but sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning to both parameters: content format types and detailed metadata source examples. Schema coverage is 50% but description compensates with concrete usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states it ingests in-memory content as a string and differentiates from ingest_file for files on disk. Specific verb+resource with clear distinction from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions when to use this tool ('use ingest_file for files on disk') and hints at re-ingestion capability. Lacks explicit when-not-to-use scenarios, but the sibling distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a document file (PDF, DOCX, TXT, MD) into the vector database. Path must be absolute; re-ingesting the same path replaces its existing data. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| visual | No | Run VLM captioning on figure pages (PDF only; default false). | |
| filePath | Yes | Absolute path to the file to ingest. Example: "/Users/user/documents/manual.pdf" | |
| visualQuality | No | VLM profile when visual is true (default "fast"). "quality" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false. | fast |
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 discloses that ingestion is a write operation, that re-ingesting replaces existing data, and that it supports VLM captioning for PDFs with different quality profiles. It also specifies the return structure. This is thorough for a tool of this complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the main purpose, and the second adds critical behavioral details. No extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no nested objects, the description covers input requirements (absolute path), behavior (replace on re-ingest), return fields, and an optional feature (VLM captioning). It briefly addresses PDF-only behavior. Missing details like error handling or unsupported file types, but overall sufficient for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context like 'Path must be absolute' and the effect of re-ingesting, but the schema already describes each parameter adequately. No additional semantic depth beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Ingest', the resource 'document file (PDF, DOCX, TXT, MD)', and the destination 'into the vector database'. It distinguishes from siblings like 'delete_file' and 'list_files' by specifying file ingestion. The mention of absolute path and re-ingest behavior adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: 'Path must be absolute' and 're-ingesting the same path replaces its existing data'. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'ingest_data'), nor does it give exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested. Returns { baseDirs, files, sources }; sources lists ingested items reported apart from the file scan, chiefly ingest_data content (web pages, clipboard, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. "/docs/api" matches "/docs/api/x.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds value by explaining that 'sources' contains ingested items like web pages/clipboard, and that files are scanned from base directories. It doesn't explicitly state this is read-only or describe side effects, but the 'list' verb implies safety. Some edge behavior (e.g., invalid scope yielding empty files list) is only visible in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the core purpose, and the second explains the return structure and the 'sources' nuance. There is no redundancy or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with one optional parameter and no output schema, the description sufficiently covers the purpose, return shape, and the non-obvious 'sources' concept. It doesn't need to explain return values in detail since the return shape is stated. Path edge cases are handled in the schema, so the description is complete enough for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter 'scope' with a detailed explanation of prefix matching and path constraints. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('list') and resource ('supported files (PDF, DOCX, TXT, MD)') under configured base directories, plus the ingestion status. This clearly distinguishes it from sibling tools like ingest_file, delete_file, and sync_status, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for inspecting the file inventory and its ingestion status, which is a distinct use case. It also explains the return shape to set expectations. However, it doesn't explicitly mention when not to use it or reference sibling alternatives, though the purpose is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ingested documents with hybrid keyword + semantic matching. Returns results sorted by relevance, each with filePath, chunkIndex, text, fileTitle, score (0 = best, higher = worse), and source (for ingest_data items).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10, range 1-20). Lower favors precision, higher recall. | |
| query | Yes | Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match). | |
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. "/docs/api" matches "/docs/api/auth.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details return fields, sorting by relevance, and score meaning (0=best, higher=worse). It lacks pagination details but is generally transparent for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with clear, front-loaded purpose and a concise list of return fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers purpose, behavior, and return fields comprehensively. Context from sibling tools and parameter count is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds value by listing output fields not present in schema, enhancing parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ingested documents using hybrid keyword and semantic matching, and lists the return fields. It is distinct from sibling tools like list_files and read_chunk_neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for searching documents) but does not explicitly state when not to use or provide alternatives among siblings. No exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the chunks immediately before and after a query_documents result, in the same document, for more surrounding context. Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data). Returns the target chunk (isTarget: true) and its neighbors, ascending by chunkIndex; an out-of-range chunkIndex returns []. Defaults: before=2, after=2 (max 50 each).
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Number of chunks to retrieve after the target (0–50, default 2). | |
| before | No | Number of chunks to retrieve before the target (0–50, default 2). | |
| source | No | Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: "https://example.com/page", "clipboard://2024-12-30". | |
| filePath | No | Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: "/Users/user/documents/manual.pdf". | |
| chunkIndex | Yes | Zero-based target chunk index (non-negative integer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details the behavior (reads neighbors), return structure (target with isTarget: true, ascending order), edge case (out-of-range returns []), and limits (defaults before/after=2, max 50 each). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the most important information. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully covers the tool's behavior, parameter usage, return structure, and edge cases. It ties to the sibling tool query_documents, providing necessary context for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all five parameters. The description adds value by explaining the mutual exclusivity of filePath and source, the default values for before and after, and the connection to query_documents for chunkIndex.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb ('Read'), the resource ('chunks immediately before and after'), and the context ('in the same document, for more surrounding context'). It ties the tool to query_documents, distinguishing it from siblings like query_documents itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit instructions on parameter usage: pass chunkIndex from query_documents and exactly one of filePath or source. It also states defaults and max limits. However, it doesn't explicitly state when not to use this tool or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get index status: { documentCount, chunkCount, memoryUsage (MB), uptime (s), ftsIndexEnabled, searchMode }.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not explicitly state read-only nature or other behavioral traits like cost or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, description fully covers functionality and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; description adds value by listing return fields beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it gets index status and lists return fields, clearly distinguishing from sibling tools like delete_file or query_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, but the simple nature (no parameters) makes usage implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone. Returns { jobId } without waiting for the run to finish; poll sync_status with that jobId for progress and the final outcome. Only one job is kept, and it is lost when the server process exits.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional absolute path to a file or directory inside a configured base directory; list_files returns those directories as baseDirs. A file synchronizes only itself and a directory only its own subtree, leaving every path outside it untouched. Omit it to synchronize every configured base directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: asynchronous execution (returns jobId without waiting), single-job constraint, and job loss on server exit. It also notes that index entries are removed for missing files, making side effects transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first states the core purpose, the second explains the return value and polling, and the third adds a critical lifecycle constraint. Every sentence contributes essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, no annotations, and no output schema, the description fully captures the tool's behavior, return format, and lifecycle. It also refers to sync_status for progress, completing the operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a 100% coverage description for the 'path' parameter, explaining its optionality, scope, and behavior. The tool description adds no extra parameter context, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Reconcile the index with the files on disk' and enumerates specific behaviors (ingest new/changed, leave unchanged, remove gone entries). This distinguishes it from sibling tools like ingest_file or delete_file, which handle single files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (reconciling an index with disk state) and implicitly contrasts with sync_status for polling. It lacks explicit 'when not to use' statements or alternative tool names, but the context is unambiguous enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current or latest sync job record: { jobId, state ("running" | "succeeded" | "failed"), total (null until scanning has counted the files on disk), completed (upserted + skipped + empty; pruned is counted separately), summary { upserted, skipped, empty, pruned }, warnings, error (null unless the job failed) }. An unknown jobId means the job was replaced by a newer one or lost with a previous server process.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Identifier returned by sync_start. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It transparently explains field nullability (total null until scanning, error null unless failed), the enumerated state values, and the unknown jobId case. This gives the agent a complete picture of expected behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but intentionally structured to mirror the returned object, making the field relationships clear. The second sentence adds essential edge-case information without fluff. It is compact given the amount of detail about the response shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description fully defines every return field and its conditional behavior, including a nested summary object. It also references sync_start and server process loss to situate usage, making the tool self-sufficient in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers jobId ('Identifier returned by sync_start') at 100% coverage. The description adds extra meaning beyond the schema by explaining the consequences of an unknown jobId, which enriches the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the current or latest sync job record', providing a specific verb+resource. It further details the exact output shape including state values, total/completed semantics, and nested summary, clearly distinguishing it from sibling tools like sync_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: after starting a sync job, call this to retrieve its status. It explains the meaning of an unknown jobId (replaced or lost with server process), which guides the agent on interpreting results. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.17.3list_files1 field changedInput schema / properties / scope / descriptionPrevious value: -"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."New value: +"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."sync_startsync_statusv0.16.1list_files1 field changedInput schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}v0.15.3ingest_data1 field changedInput schema / properties / metadata / properties / format / descriptionPrevious value: -"Content format: \"text\", \"html\", or \"markdown\""New value: +"Content format: text (plain/copied text), html (fetched web pages), or markdown."ingest_file2 fields changedInput schema / properties / visual / descriptionPrevious value: -"If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files."New value: +"Run VLM captioning on figure pages (PDF only; default false)."Input schema / properties / visualQuality / descriptionPrevious value: -"VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false."New value: +"VLM profile when visual is true (default \"fast\"). \"quality\" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false."query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Max results (default 10, range 1-20). Lower favors precision, higher recall."Input schema / properties / query / descriptionPrevious value: -"Search query. Include specific terms and add context if needed."New value: +"Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match)."Input schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. \"/docs/api\" matches \"/docs/api/auth.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}read_chunk_neighbors2 fields changedInput schema / properties / filePath / descriptionPrevious value: -"Absolute path to the file (for documents ingested via ingest_file). Example: \"/Users/user/documents/manual.pdf\". Provide either filePath or source, not both."New value: +"Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: \"/Users/user/documents/manual.pdf\"."Input schema / properties / source / descriptionPrevious value: -"Source identifier used in ingest_data (for data ingested via ingest_data). Examples: \"https://example.com/page\", \"clipboard://2024-12-30\". Provide either filePath or source, not both."New value: +"Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: \"https://example.com/page\", \"clipboard://2024-12-30\"."v0.15.0query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / limit / maximumAdded value: +20Input schema / properties / limit / minimumAdded value: +1v0.14.1ingest_file1 field changedInput schema / properties / visualQualityAdded value: +{
+ "default": "fast",
+ "description": "VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false.",
+ "enum": [
+ "fast",
+ "quality"
+ ],
+ "type": "string"
+}v0.14.0ingest_file1 field changedInput schema / properties / visualAdded value: +{
+ "description": "If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files.",
+ "type": "boolean"
+}v0.13.0read_chunk_neighborsv1.0.0delete_fileingest_dataquery_documents2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 5, max recommended: 20)"New value: +"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / query / descriptionPrevious value: -"Natural language search query (e.g., \"transformer architecture\", \"API documentation\")"New value: +"Search query. Include specific terms and add context if needed."ingest_filelist_filesquery_documentsstatusEach tool has a distinct purpose: sync_status tracks job progress while status reports index stats; ingest_file vs ingest_data clearly separate file-based and in-memory ingestion; query_documents, read_chunk_neighbors, delete_file, list_files, and sync_start all target different operations. No two tools are likely to be confused.
Most tools follow a verb_noun pattern (query_documents, ingest_file, delete_file, list_files, read_chunk_neighbors), but sync_status, sync_start, and status deviate, using noun compounds or a standalone noun. The mix is readable but not uniform.
9 tools is well-scoped for a local RAG server, covering ingestion (file and data), deletion, querying, context expansion, file listing, and status/sync operations without unnecessary redundancy or bloat.
The set covers the core lifecycle: ingest (file/data), delete, search, and context retrieval. Minor gaps include no direct way to fetch all chunks of a specific document or a bulk clear operation, but these can be worked around with existing tools like query_documents and sync_start.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Versioned documentation registry and semantic search for AI tools and coding assistants.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Search everything you save: YouTube, articles, podcasts, PDFs, Notion, Obsidian. API key or OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinpr/mcp-local-rag'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
