从 MCP 客户端或终端搜索私有文档，无需将其发送到嵌入 API。
mcp-local-rag 为机器上的 PDF、DOCX、Markdown 和文本文件建立索引。搜索将语义相似度与关键词匹配相结合，因此查询既能匹配意图，也能匹配精确的技术术语，如 API 名称、类名和错误代码。
本地运行： 文档解析、嵌入、存储和搜索均在您的机器上运行。 初始模型下载完成后，文本摄取和搜索可离线工作。
混合搜索： 语义检索查找相关概念，关键词匹配提升精确技术术语的权重。
可配置嵌入： 选择适合文档语言和领域的 Hugging Face 嵌入模型。
语义分块： 文档按主题边界而非固定字符数进行拆分。Markdown 代码块保持完整。
MCP 和 CLI： 从 AI 编码工具或直接通过终端使用同一索引。
无需 API 密钥、Docker、Python 或外部数据库。
Related MCP server: cowork-semantic-search
Node.js 22 或更高版本
首次使用需联网以下载 npm 包和嵌入模型
包含要搜索文档的目录
将 BASE_DIR 设置为该目录。它也是文件操作的安全边界。将下面的 /absolute/path/to/your/documents 替换为该目录的绝对路径。
mcp-local-rag 通过本地 stdio 服务器使用标准 MCP 协议，因此可与支持本地 MCP 服务器的 AI 编码工具和其他 MCP 主机配合使用。
使用以下示例之一，或注册 npx -y mcp-local-rag 并使用客户端的 MCP 配置格式设置 BASE_DIR。
对于 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 MB），摄取开始前可能需要 1–2 分钟。后续运行使用本地缓存。
同步完成后：
What does the API documentation say about authentication?要在没有 MCP 客户端的情况下使用 CLI：
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"CLI 默认使用当前目录作为文档根目录。请从同一目录运行这两个命令，以便它们使用相同的默认索引，或显式设置 BASE_DIR 和 DB_PATH。
某些文档集因保密性或组织策略而无法发送到托管嵌入服务。将索引保留在本地，即可在不增加每次查询 API 成本的情况下实现可搜索性。
仅靠语义搜索可能会遗漏技术文档中重要的精确标识符。关键词重排序可在不放弃自然语言检索的情况下保持这些术语的可见性。
输入 | 摄取方式 |
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。同步不会生成视觉标题。在 MCP 服务器环境中设置 STORE_IMAGES=true，以存储同步所选新增或变更文件中的受支持 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 路径前缀，或前缀列表。前缀匹配精确路径及其后代。
在 MCP 客户端抓取页面后使用 ingest_data：
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图片存储独立于视觉标题。为 MCP 服务器设置 STORE_IMAGES=true，或为 CLI 摄取和同步传递 --images：
npx mcp-local-rag ingest ./docs/research-paper.pdf --images
npx mcp-local-rag sync ./docs/ --imagesPDF 存储使用检测到的图形/表格区域。DOCX 存储仅包含现有 Mammoth 转换以 <img> 形式输出的 PNG/JPEG 图片；图表、SmartArt 和形状不会单独渲染。存储的图片会跟随其周围文本进入最终语义分块，不会改变排序、分数或结果数量。
|
| PDF 行为 |
false | false | 仅文本；无视觉标题或返回的图片。 |
true | false | 生成的标题成为可搜索文本；不存储或返回图片。 |
true | true | 生成的标题成为可搜索文本，匹配分块中的图片以内联方式返回。 |
false | true | 图片附加到附近保留的 PDF 文本，并为匹配分块内联返回；不导入、加载或运行 VLM。 |
配置文件 | 模型缓存 | 使用场景 |
| 约 250 MB | 轻量级视觉索引 |
| 约 2.9 GB | 包含标签、注释或其他图像内文字的图形 |
通过 MCP 使用 visualQuality: "quality" 或通过 CLI 使用 --visual-quality quality 选择更大的模型。实测 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 为 AI 助手提供查询和摄取指导：
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 <path> 标志（可在 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 listDB_PATH 和 CACHE_DIR 默认相对于进程工作目录。当 MCP 客户端可能从不同的项目目录启动服务器时，请设置绝对路径。
设置 MODEL_NAME 或传入 --model-name 以选择适合文档语言和领域的 Hugging Face 嵌入模型。
mcp-local-rag 使用均值池化和 L2 归一化生成嵌入向量。选择模型时，请检查这些设置是否与其推荐的推理配置匹配，因为池化方法可能影响检索质量。
更改 MODEL_NAME、RAG_DEVICE 或 RAG_DTYPE 可能导致现有向量不兼容。更改嵌入配置后，请使用新的 DB_PATH 或删除现有索引并重新摄取。
适用于英文文档的示例模型是 Xenova/bge-small-en-v1.5。
文件访问仅限于 BASE_DIR、BASE_DIRS 或 CLI --base-dir 根目录。
解析到所有已配置根目录之外的符号链接将被拒绝。
在所需模型缓存之后，文档处理和搜索不会发出任何网络请求。
该服务器专为单个本地用户设计，不提供身份验证或访问控制。
不要对同一 DB_PATH 运行多个 CLI 或 MCP 写入器。同步进行时可以运行只读查询。
在没有写入器活动时，通过复制其 DB_PATH 目录来备份索引。
必须先摄取文档。运行“列出所有已摄取的文件”以验证。
检查互联网连接。如果位于代理后面，请配置网络设置。也可以手动下载该模型。
默认限制为 100MB。拆分大文件或增大 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='[]'（空数组）
验证配置文件语法
完全重启客户端（Mac 上 Cursor 使用 Cmd+Q）
直接测试：npx mcp-local-rag 应能无错误运行
欢迎贡献！有关设置和指南，请参阅 CONTRIBUTING.md。
MIT 许可证。免费用于个人和商业用途。
构建用于 Agent 编码的本地 RAG：语义分块和混合搜索设计的技术深入解析。
基于 Anthropic 的 Model Context Protocol、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
