Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-local-rag What do my documents say about handling PDF uploads?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
本地文档检索服务：在本机完成文档解析、向量化、LanceDB 存储和混合检索，不上传文档。 可通过 MCP 客户端或命令行使用。
要求：Node.js 22+。首次运行需要网络下载 npm 依赖和 embedding 模型；模型缓存后可离线运行。
pnpm install
pnpm build
$env:BASE_DIR = 'D:\Rag\documents'
npx mcp-local-rag sync
npx mcp-local-rag query '查询内容'默认索引为当前工作目录下的 lancedb。本项目 Windows 脚本统一使用 D:\Rag，目录结构为：
D:\Rag\documents
D:\Rag\models
D:\Rag\indexes\lancedb
D:\Rag\indexes\lancedb-intel-npu使用 npm CLI 时，建议显式设置绝对路径：
$env:BASE_DIR = 'D:\Rag\documents'
$env:DB_PATH = 'D:\Rag\indexes\lancedb'
npx mcp-local-rag sync
npx mcp-local-rag query '查询内容' --scope 'D:\Rag\documents\gmsl'也可以直接运行 npx -y mcp-local-rag 作为 MCP server，并在 MCP 客户端配置同样的
BASE_DIR、DB_PATH 等环境变量。
Related MCP server: ragi
文件：PDF、DOCX、Markdown、TXT。
HTML：由 MCP 客户端抓取后通过 ingest_data 传入。
检索：语义相似度与关键词匹配结合。
工具：sync_start、sync_status、ingest_file、ingest_data、query_documents、
read_chunk_neighbors、list_files、delete_file、status。
文件操作只能访问配置的文档根目录。修改模型、设备、精度或分块规则后，必须使用新的索引目录或重新建库。
全局安装后可直接使用以下命令：
npm install -g mcp-local-rag项目内安装时，在命令前加 npx，例如 npx mcp-local-rag-onnx sync。npm 包内部仍包含
tools/ 与 requirements-openvino.txt，无需手动定位它们。
以下脚本需要 Python 3.10+；标准 npm CLI 不需要 Python。默认文档根目录为
D:\Rag\documents，模型缓存为 D:\Rag\models。
与 NPU 脚本一样，通过子命令区分建库和查询。默认索引为
D:\Rag\indexes\lancedb：
mcp-local-rag-onnx sync
mcp-local-rag-onnx query '查询内容' `
--scope 'D:\Rag\documents\gmsl'sync 默认 webgpu，query 默认 cpu；两者均可通过 --device cpu|webgpu|dml
显式覆盖。例如使用 DirectML 建库：
mcp-local-rag-onnx sync --device dml。
建库批次默认是 8，可通过 sync --batch-size <数量> 调整；查询一次只嵌入一个问题，
批次固定为 1。
首次使用、删除 .openvino-venv 或更新 OpenVINO/NPU 驱动后执行一次。脚本会准备 FP32
模型并编译四个固定形状 [1,128]、[1,256]、[1,512]、[1,1024] 的 NPU blob：
mcp-local-rag-npu-setup在单独终端启动服务，并在建库或查询期间保持运行：
mcp-local-rag-npu-start健康检查只在排查问题时执行，不需要每次运行：
Invoke-RestMethod http://127.0.0.1:8765/health返回的 device 应为 NPU。服务不会自动回退 CPU，关闭服务进程或终端后服务才会停止。
在另一个终端建库或查询。默认 NPU 索引为 D:\Rag\indexes\lancedb-intel-npu：
mcp-local-rag-npu sync
mcp-local-rag-npu query '查询内容' `
--scope 'D:\Rag\documents\gmsl'可用 --database-path、--documents-root、--models-path 和 --endpoint 覆盖默认值。
NPU 服务按文本 token 数选择最小可容纳的固定长度，batch 固定为 1。
环境变量 | 默认值 | 作用 |
| 当前目录 | 文档根目录 |
|
| LanceDB 索引目录 |
|
| 模型缓存目录 |
|
| embedding 模型 |
|
| Transformers.js 设备，如 |
|
| embedding 精度 |
|
|
|
|
| OpenVINO 服务地址 |
RAG_EMBEDDER_BACKEND=openvino 时，必须先启动 OpenVINO 服务。不同模型或后端生成的向量
不可混用，应分别使用不同的 DB_PATH。
pnpm build
pnpm test
pnpm run check:all项目许可证为 MIT。
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 are provided, so the description carries the full burden. It discloses return values (deleted, removedChunks, existed) and the conditional requirement, which goes beyond the schema. It does not explicitly state irreversibility, but the term 'delete' implies it, and chunk removal is mentioned.
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, front-loaded with the action, and every sentence adds value. It is concise without sacrificing important details like return values and parameter selection.
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 the moderate complexity of the tool, the description covers the essential decision (filePath vs source), the required parameter constraint, and the return values. It lacks edge-case details like what happens if both parameters are provided, but this is minor given the overall clarity.
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%, but the description adds critical semantic context by mapping parameters to ingestion methods and clarifying the 'either/or' requirement. This goes beyond the schema's examples and helps the agent choose correctly.
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 deletes a previously ingested file or data from the vector database, using specific verbs and resource. It distinguishes itself from sibling tools like ingest_file and query_documents, as deletion is a unique operation.
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 explains when to use each parameter: filePath for files ingested via ingest_file, source for data ingested via ingest_data. It also states that either must be provided, guiding the agent on parameter selection.
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?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals a key behavioral trait—re-ingestion with the same source identifier updates existing content—and specifies the return shape. While it does not mention auth, permissions, or side effects, it covers the main behavioral consequences for the typical use case.
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 long and front-loaded with the tool's core purpose. It efficiently packs the alternative tool reference, the re-ingestion behavior, and the return value into a compact, well-structured format with zero filler.
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 the tool has 2 parameters (one nested), no annotations, and no output schema, the description provides a complete picture: what it does, when to use it, how the source identifier behaves, and what it returns. It lacks explicit error scenarios or prerequisites, but these are not critical for a simple ingestion tool. The return value statement covers the output side.
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 50% (content and format described in schema, metadata partially). The description adds significant value by explaining the 'source' identifier protocol with examples (e.g., 'clipboard://2024-12-30', 'chat://2024-12-30/project-discussion'), which is essential for correct invocation. This compensates well for the moderate schema coverage.
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 uses the specific verb 'Ingest' and clearly specifies the resource: 'in-memory content as a string'. It further distinguishes itself from a sibling tool by explicitly pointing to 'ingest_file' for disk files, making the purpose unambiguous.
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 explicitly states when to use this tool (in-memory string content) and when not to (files on disk, via 'use ingest_file for files on disk'). This provides clear alternatives and context for selection.
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?
With no annotations provided, the description carries the burden of disclosing behavior. It explicitly states that re-ingesting replaces existing data, revealing a destructive side effect, and also specifies the return object structure. It does not cover other potential behaviors like long-running VLM processing, but the key destructive behavior is disclosed.
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 zero waste. First sentence front-loads action and resource, second sentence covers constraints and return value. Highly scannable 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 no output schema and no annotations, the description covers essential operational context: supported file types, absolute path requirement, replacement behavior, and return format. It lacks explicit separation from sibling ingest tools (ingest_data, ingest_directory) but otherwise provides a complete picture for a single-file ingestion tool.
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%, so baseline is 3. The description adds value by listing allowed file extensions (PDF, DOCX, TXT, MD) for filePath, which the schema does not specify. It also clarifies replacement semantics tied to the file path. It does not add extra detail for visual or visualQuality beyond what the schema provides, so a slight uplift is appropriate.
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 'Ingest' and resource 'document file (PDF, DOCX, TXT, MD) into the vector database'. It implicitly distinguishes itself from sibling tools like ingest_directory by focusing on a single document file with an absolute path, and from ingest_data by specifying file formats.
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 states clear context: use for ingesting a document file, path must be absolute, and re-ingesting the same path replaces existing data. It does not explicitly name alternatives or exclusions, but the singular 'file' and mention of supported extensions imply single-file use, differentiating from ingest_directory.
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 full burden. It discloses the return structure ({ baseDirs, files, sources }), explains that sources lists non-file ingested items, and the scope parameter details behavior for relative/out-of-base prefixes. It does not explicitly state read-only intent or mention recursion depth/sorting, but for a list tool the essentials are covered. Edge cases for scope are thoroughly disclosed.
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: first states the core function and return object, second clarifies what 'sources' contains. No filler, front-loaded with the verb 'List'. The parameter schema is detailed but that is separate. The main description earns its place.
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 list tool with no output schema, the description explains the return object and the meaning of sources. The scope parameter covers traversal/filtering behavior. It could additionally disclose recursion depth or permission requirements, but these are less critical for a read-only list operation. Overall, sufficiently complete for an agent to invoke correctly.
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% for the single optional parameter 'scope', and its description is detailed (absolute path, prefix matching, union for arrays, behavior for relative/out-of-base). The tool description adds no extra parameter semantics beyond the schema. Per guidelines, high schema coverage yields a baseline of 3, which is appropriate.
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 what the tool does: 'List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested.' This is a specific verb+resource combination with scope (supported extensions, base directories, ingestion status). It distinguishes from siblings: query_documents and status focus on querying, ingest_* on adding content, delete_file on removal. The tool is unambiguously the file-listing utility.
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 usage: use this when you need to see files and their ingestion status, and it notes that sources include non-file ingest_data content (web pages, clipboard). The scope parameter description adds clear guidance about absolute path prefixes and how to interpret empty results (compare against baseDirs). However, it does not explicitly contrast with alternative tools such as query_documents or status, nor state when not to use it.
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 provided, the description carries the full burden of behavioral disclosure. It adds value by explaining the score semantics (0 = best, higher = worse) and the special 'source' field for ingest_data items. It does not mention side effects, but 'search' inherently implies a read-only operation.
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 exactly two sentences: the first states the purpose, the second details the return structure. Every word earns its place, with no redundancy or filler.
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 the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is adequate. It explains the return format and score meaning, while the schema covers parameter semantics. It does not mention pagination, but the limit parameter implicitly addresses that.
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 schema already documents all parameters comprehensively. The description adds no parameter-specific details beyond implying the query benefits from both keyword and semantic matching. A baseline score of 3 is appropriate.
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 action ('Search ingested documents') with a distinctive approach ('hybrid keyword + semantic matching'), clearly distinguishing it from sibling tools like list_files or read_chunk_neighbors. It also lists return fields, making the tool's purpose unambiguous.
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 the tool is for searching documents but does not explicitly state when to use it versus alternatives. No pruning or exclusions are given, leaving usage context solely to the user's judgment.
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?
With no annotations, the description carries the full burden for behavioral disclosure. It thoroughly explains return behavior: target chunk (isTarget: true), neighbors ascending by chunkIndex, out-of-range returns [], and defaults (before=2, after=2, max 50 each). This goes well beyond basic descriptions and covers edge cases and ordering.
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, directly front-loaded with the main purpose. Each sentence earns its place: purpose, parameter usage, and return behavior. No filler or 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?
Despite lacking an output schema, the description fully explains the return structure: target chunk, neighbors, ordering, and edge-case behavior. It also sets expectations for defaults and limits, making it complete for a moderate-complexity read tool.
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%, so the baseline is 3. The description adds significant context beyond the schema: it explicitly ties chunkIndex to a query_documents result, emphasizes the exclusivity of filePath vs source, and reiterates defaults and maximums. This enriches the parameter semantics meaningfully.
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 a specific action: 'Read the chunks immediately before and after a query_documents result, in the same document.' This distinguishes it from query_documents (which retrieves results) and other tools by focusing on neighboring chunks. The verb 'read' and resource 'chunks' are explicit and specific.
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 gives explicit usage guidance by instructing to 'Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data).' This contextualizes the tool as a follow-up to query_documents. However, it does not explicitly compare to alternatives or state when not to use it, so it falls just short of a 5.
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?
With no annotations, the description must carry the burden of behavioral disclosure. It communicates the output fields and implies a read-only operation via 'Get', but it does not explicitly state safety, side effects, or any operational conditions. The field list adds context, but some behavioral aspects remain implicit.
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, front-loaded sentence that immediately states the tool's purpose and then lists the output fields in a structured way. There is no redundancy or 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 simple status tool with no parameters and no output schema, the description adequately covers the return values and purpose. It does not mention potential delays or whether the status is a snapshot, but for its simplicity, the information provided is sufficient for basic 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 tool has no parameters and an empty input schema, so parameter semantics are not needed. The description adds value by enumerating the output fields, which helps the agent understand what to expect, thus justifying a baseline score of 4.
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 action (Get) and resource (index status), and the listed field names specify exactly what the tool returns. This distinguishes it from sibling tools like query_documents or sync_status, which have different purposes.
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 is given on when to use this tool versus alternatives such as sync_status, which may also report on index state. There is no mention of exclusions or typical use cases, leaving the agent to infer when this tool is appropriate.
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), polling via sync_status, job retention (only one job kept), and loss on server exit. It also explains impact on unchanged and missing files. This goes well beyond basic safety hints.
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 sentences, no fluff, all information is relevant and front-loaded. It efficiently covers purpose, async behavior, job lifecycle, and parameter scoping in a compact form.
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?
The description is complete for a tool of this complexity: it explains the return value, polling mechanism, job limitation, and optional path semantics. No output schema exists, so return-value explanation is sufficient. It covers all critical operational aspects.
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 provides 100% coverage for the single 'path' parameter, including optionality, base directory behavior, and scoping rules. The description adds no new parameter semantics beyond what the schema says. Baseline 3 is appropriate.
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 purpose: 'Reconcile the index with the files on disk' with specific actions (ingest new/changed, leave unchanged, remove gone). This distinguishes it from siblings like ingest_file (single file ingest) and delete_file, and it explicitly notes the async jobId return and polling via sync_status.
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 it: to reconcile the index with disk, with optional path scoping. It provides context on behavior (leaves unchanged files alone) but does not explicitly state when not to use it or name alternatives (e.g., use ingest_file for a single file). Still, context is clear and useful.
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, the description carries the full burden. It clearly states the return shape (jobId, state, total, completed, summary, warnings, error) and explains null/unknown meanings. It does not mention side effects, but 'Get' implies a read-only operation, and no side effects are likely. The level of detail is strong for a status 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 longer than a typical one-liner, but it is dense and structured with the return object in braces, using spaces and parentheses for clarity. Every sentence adds value, though it could be slightly trimmed without loss. It is front-loaded with the core action.
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 single-parameter status tool with no output schema, the description is remarkably complete. It details all possible state values, null semantics, and the meaning of an unknown jobId. There is no obvious missing behavior; the tool's functionality is fully described.
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 covers jobId with 'Identifier returned by sync_start.' The description adds meaning by explaining that an unknown jobId indicates replacement/loss, and by showing jobId in the return structure. This goes beyond the schema's basic parameter comment.
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 starts with 'Get the current or latest sync job record' — a specific verb and resource. It clearly distinguishes itself from siblings like sync_start (which creates a job) and status (which likely relates to something else) by focusing on sync job state retrieval.
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 the intended context: to poll or inspect a previously started sync job. It does not explicitly name alternatives, but the mention of 'unknown jobId means the job was replaced by a newer one or lost with a previous server process' gives practical guidance on interpreting results, which helps decide when this tool is useful.
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.
v0.17.3delete_fileingest_dataingest_filelist_filesquery_documentsread_chunk_neighborsstatussync_startsync_statusScored across 9 tools
Each tool has a clear, non-overlapping purpose: status, query, two ingestion methods differentiated by source type, delete, list, context reading, and sync start/status. Even the two ingest tools are unambiguous due to explicit input-type distinction.
Most tools follow a verb_noun snake_case pattern (query_documents, ingest_file, delete_file, list_files, read_chunk_neighbors, sync_start, sync_status). The lone 'status' tool deviates slightly by being a bare noun rather than a verb action, but the overall naming is predictable and consistent.
With 9 tools, the server is well-scoped for a local RAG system. Each tool serves a distinct and necessary function: ingestion (file and data), querying, context exploration, deletion, listing, status, and synchronization, with no unnecessary bloat.
The tool set covers the full lifecycle: ingestion (create), querying (read), deletion (delete), and updating via re-ingestion or synchronization. Additional utilities like status, list_files, and read_chunk_neighbors fill out the surface for effective RAG management, leaving no obvious gaps.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
