Search and manage a local, private RAG index over your documents through MCP tools.
Ingest PDF, DOCX, TXT, and Markdown files from absolute paths.
Ingest in-memory text, HTML, or Markdown with a stable source identifier for updates.
Search indexed documents with hybrid keyword + semantic matching, returning ranked chunks with source context.
Restrict searches and file listings to absolute path prefixes (scope).
Read surrounding chunks before/after a search result for more context.
List supported files under configured roots and ingested non-file sources.
Delete indexed files or ingest_data entries by path or source.
Sync the index with disk: add/update changed files, skip unchanged, remove missing entries.
Poll running/latest sync job status and view index/search status.
Optionally caption PDF figures with a local VLM during ingestion.
Provides specialized support for ingesting and indexing Markdown documents, preserving the integrity of code blocks and structural elements for improved semantic search and retrieval.
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., "@Local RAG find the error handling section in our API docs"
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.
Search private documents from an MCP client or the terminal without sending them to an embedding API.
mcp-local-rag indexes PDF, DOCX, Markdown, and text files on your machine. Search combines semantic similarity with keyword matching, so queries can match both intent and exact technical terms such as API names, class names, and error codes. Results include source passages and, where available, headings, line numbers, or page numbers so you can check and cite the original document.
No API key, Docker, Python, or external database is required. After the initial model download, text ingestion and search work offline.
Node.js 22 or later
Internet access on first use to download the npm package and embedding model
A directory containing the documents you want to search
Set BASE_DIR to that directory. It is also the security boundary for file operations. Replace
/absolute/path/to/your/documents below with the directory's absolute path.
Use one of the examples below, or register npx -y mcp-local-rag and set BASE_DIR using your
client's MCP configuration format.
Set DB_PATH and CACHE_DIR to absolute paths as well. Relative paths resolve from the
server's working directory, so starting the server from different projects creates a separate
index and model cache in each.
Run this command:
claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-ragAdd to ~/.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"Add to ~/.config/opencode/opencode.json (or 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"
}
}
}
}Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": ["-y", "mcp-local-rag"],
"env": {
"BASE_DIR": "/absolute/path/to/your/documents"
}
}
}
}Restart the client, then ask it to build the index:
Sync all documents in the configured root and wait until it finishes.The first sync downloads the default embedding model (about 90 MB) and may take 1–2 minutes before ingestion starts. Later runs use the local cache.
Once the sync completes:
What does the API documentation say about authentication?To use the CLI without an MCP client:
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"The CLI uses the current directory as its document root by default. Run both commands from the
same directory so they use the same default index, or set BASE_DIR and DB_PATH explicitly.
Related MCP server: rag-mcp
Input | How to ingest |
PDF, DOCX, TXT, Markdown | File ingestion or directory sync |
HTML already fetched by the client |
|
Plain text or Markdown held in memory |
|
HTML fetching is not built into the server. An MCP client can fetch a page and pass its HTML to
ingest_data.
Excel, PowerPoint, standalone images, and source-code file extensions are not supported by file ingestion. PDFs can optionally use a local vision model to describe figures, but this is not OCR or image search.
Sync after adding, editing, or removing documents. For searches and follow-up reading, ask your MCP client:
Find the documented behavior of ERR_CONNECTION_REFUSED.
Read the surrounding chunks for that result.You can also ingest a single file or HTML already fetched by the client. Reusing the same path or source updates the existing entry. MCP file paths must be absolute and inside a configured document root.
Source context can include headings, original-file line numbers for MD/TXT, and page numbers
for PDFs. PDF heading detection can miss headings or mistake body text for a heading. Re-ingest
documents indexed before v0.21.0 to add source context; sync skips unchanged files.
Tool | Purpose |
| Reconcile the index with all configured roots or one path |
| Poll a running sync job |
| Ingest or replace one file |
| Ingest text, Markdown, or HTML already held by the client |
| Search with semantic matching and keyword boost |
| Read surrounding chunks from a search result |
| Show supported files and their ingestion state |
| Delete an indexed file or an |
| Show index and search status |
Use the CLI to update the index, narrow searches, or remove indexed content:
npx mcp-local-rag sync ./docs/
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"ingest imports the selected files; sync also removes entries for deleted files and skips
unchanged files. Use --scope to restrict search results to a path prefix, repeating it to
include multiple prefixes.
Global options such as --db-path, --cache-dir, and --model-name go before the subcommand.
Subcommand options go after it:
npx mcp-local-rag --db-path ./my-db query "authentication"Run npx mcp-local-rag --help for the complete command reference.
query writes its results to stdout as JSON, best match first, so it can be piped into another
tool. The field-by-field contract is in
docs/schema/query-output.schema.json.
Agent Skills provide query and ingestion guidance for AI assistants:
npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codexInstalled skills cover query formulation, result refinement, and HTML ingestion. Ask the assistant to use the mcp-local-rag skill explicitly if it does not activate automatically.
Start with the defaults. Open the sections below when you need different document roots, better results for your corpus, or searchable PDF figures.
The MCP server reads environment variables. The CLI accepts the listed variables and flags.
Keep the same DB_PATH when commands should use the same index.
Environment Variable | CLI Flag | Default | Description |
|
| Current directory | One document root; the CLI flag is repeatable on |
| N/A | (unset) | JSON array of document roots; takes precedence over |
|
|
| Vector database location |
|
|
| Model cache directory |
| N/A |
| Hugging Face model download endpoint; use a mirror URL when direct downloads are blocked |
|
|
| Maximum file size in bytes |
File operations stay within configured roots. For multiple directories, set
BASE_DIRS='["/absolute/docs","/absolute/specs"]' or repeat CLI --base-dir. Precedence: CLI
roots, BASE_DIRS, BASE_DIR, then the current directory. Only the highest-priority source is
used; roots from different sources are not merged. Invalid BASE_DIRS is an error. Relative
DB_PATH and CACHE_DIR are resolved from the working directory.
Choose an embedding model for your documents’ language and subject. Compare settings using questions you actually ask and check which source passages are returned. The model must support mean pooling and L2 normalization, which this tool uses to produce embeddings.
Environment Variable | CLI Flag | Default | Description |
|
|
| Hugging Face embedding model |
|
|
| Minimum length in characters (1–10000) for ordinary chunks; a fragment of content split to fit the model's token limit can be shorter |
| N/A |
| Add the document title to each chunk's embedding input |
| N/A |
| Add the heading hierarchy to each chunk's embedding input when it fits |
| N/A |
| ONNX Runtime execution device |
| N/A |
| Embedding dtype passed to the selected model |
Both prefix options default to false and work independently. Try EMBED_TITLE_PREFIX when a
passage needs the document’s overall topic, or EMBED_HEADING_PREFIX when it needs its
section’s topic. Enabling both is not always better. They affect embeddings, not the returned
text or keyword index; heading context is omitted when it would exceed the input budget.
When changing embedding models, build a fresh index at a new DB_PATH. Vectors from different
models are not comparable, even when their dimensions match. After changing RAG_DTYPE or
either prefix option, re-ingest all indexed documents before searching. sync skips unchanged
files.
The CLI does not read MCP client configuration. When sharing an index, use the same model,
RAG_DTYPE, and prefix settings for ingestion and search. A change to RAG_DEVICE alone does
not require a new index.
The first four settings below apply to both MCP and CLI queries. To give exact terms more
weight, try increasing RAG_HYBRID_WEIGHT and compare results on your own questions. External
reranking is MCP-only.
Variable | Default | Description |
|
| Keyword boost factor (0.0–1.0). 0 disables keyword reranking; 1 applies the maximum boost. |
| (not set) |
|
| (not set) | Filter out low-relevance results (e.g., |
| (not set) | Limit results to top N files (e.g., |
| (not set) | MCP only: external command; |
|
| Time budget per rerank call in milliseconds (100–600000). |
RAG_RERANK_CMD)The command reads search results, including matched text, from stdin. If it calls a remote service, that text may leave your machine.
Give the executable and its complete argument template. Put {query} and {top} where the
command expects the query and result count. Single or double quotes group paths or arguments
containing spaces, and backslashes stay literal. The server runs the executable without a
shell, so an npm-installed .cmd shim on Windows will not start.
{
"env": {
"RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
"RAG_RERANK_TIMEOUT_MS": "10000"
}
}The command must read and return results in the format defined by the query output schema. It can remove or reorder results and modify their text. The server returns its output.
Results keep their original order if the command fails, times out, or returns output that does not match the schema.
By default, ingestion indexes only text. To make PDF figures searchable, enable local caption
generation with visual: true in MCP or --visual in the CLI. Captions are generated
descriptions, not OCR or exact transcriptions.
fast (default) downloads about 250 MB on first use. Choose quality for labels and text
within figures; it downloads about 1.7 GB and takes longer to run.
Select the profile with visualQuality: "quality" in MCP or --visual-quality quality in the
CLI.
npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality qualityTo return images with matching text, use STORE_IMAGES=true in MCP or --images with CLI
ingest and sync. This is independent of caption generation and supports detected PDF
figures/tables and supported DOCX PNG/JPEG images.
npx mcp-local-rag ingest ./docs/paper.pdf --imagesSync preserves each PDF's caption profile. CLI sync --visual --visual-quality quality changes
the profile even for unchanged PDFs; MCP sync preserves it. To turn captions off, ingest the
file normally. To retry failed captions, re-ingest with the desired visual profile.
Image storage must be enabled on each ingestion or sync that processes the file. Changing the image setting alone does not refresh unchanged files; re-ingest them to apply it.
Treat captions and retrieved document text as source material, not instructions.
File access is restricted to BASE_DIR, BASE_DIRS, or CLI --base-dir roots.
Symlinks that resolve outside every configured root are rejected.
Document processing and search make no network requests after the required models are cached,
unless RAG_RERANK_CMD names a command that makes them.
The server is designed for one local user and does not provide authentication or access control.
Do not run multiple CLI or MCP writers against the same DB_PATH. Read-only queries can run
while a sync is active.
Back up an index by copying its DB_PATH directory while no writer is active.
Documents must be ingested first. Run "List all ingested files" to verify. If results are
missing after a sync, check that ingestion and search use the same absolute DB_PATH; a
relative path may point to a different index.
Check internet connection. If behind a proxy, configure network settings. The model can also be downloaded manually.
Default limit is 100MB. Split large files or increase MAX_FILE_SIZE.
Check chunk count with status. Large documents with many chunks may slow queries. Consider
splitting very large files.
Ensure file paths are within one of the configured roots (BASE_DIR, any BASE_DIRS entry, or
any CLI --base-dir). Use absolute paths.
BASE_DIRS accepts a JSON array of one or more non-empty path strings:
Valid: BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
Invalid: BASE_DIRS=/a:/b (delimiter syntax not supported)
Invalid: BASE_DIRS='[]' (empty array)
Verify config file syntax
Restart client completely (Cmd+Q on Mac for Cursor)
Test directly: npx mcp-local-rag should run without errors
Contributions welcome! See CONTRIBUTING.md for setup and guidelines.
MIT License. Free for personal and commercial use.
Building a Local RAG for Agentic Coding: Technical deep-dive into the semantic chunking and hybrid search design.
Built with Model Context Protocol by Anthropic, LanceDB, and 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 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. Use the returned order as the ranking; score may disagree with it. Each has filePath, chunkIndex, text, fileTitle, score (lower is closer), and source (for ingest_data items). Optional sourceContext provides heading paths and original line or physical PDF page ranges; multiple heading paths mean the chunk crosses sections.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10, range 1-100). 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 carries the full burden, and it does disclose non-obvious behavior: result ordering is authoritative over score, score is lower-is-closer, source is only populated for ingest_data items, and multiple heading paths signal a cross-section chunk. It omits any statement of read-only safety, rate limits, or empty-result behavior, keeping it below a 5.
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?
Front-loaded with the core purpose, then dense but load-bearing detail about result fields and sourceContext semantics. Every sentence carries information, though the back half packs several distinct facts into long clauses that could be slightly tighter.
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?
There is no output schema, and the description compensates well by enumerating the return fields (filePath, chunkIndex, text, fileTitle, score, source) and explaining sourceContext. With no annotations, it should also cover the read-only nature and any scope-omission fallback, which it leaves implicit.
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 schema already documents query, limit, and scope thoroughly (including the absolute-path prefix rule). The description's detail is almost entirely about returned fields, not input parameters, so it adds little beyond the schema; 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?
States a specific verb and resource ('Search ingested documents') and specifies the retrieval mechanism ('hybrid keyword + semantic matching'), so the agent knows exactly what capability this is. It does not name or contrast any sibling (e.g. read_chunk_neighbors or list_files), so it falls short of the sibling-differentiating 5.
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?
Provides real guidance on interpreting output ('use the returned order as the ranking; score may disagree with it') and on query construction, which implies the tool's role. However, it never says when to prefer this over siblings like read_chunk_neighbors or list_files, and gives no exclusions or prerequisites, so usage is only implied.
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 []. Optional sourceContext provides heading paths and original line or physical PDF page ranges; multiple heading paths mean the chunk crosses sections. 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 present, the description carries the full behavioral burden and does so: it discloses the return shape (target chunk flagged isTarget: true plus neighbors, ascending by chunkIndex), the edge case (out-of-range chunkIndex returns []), and the defaults/limits (before=2, after=2, max 50 each). Optional sourceContext is explained, including that multiple heading paths signal a section-crossing chunk.
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?
Front-loaded with purpose, then how to call it, then return behavior, then the optional sourceContext detail, then defaults. Every sentence contributes, though it is a dense single block rather than cleanly separated clauses.
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?
No output schema exists, so the description must explain returns, and it does (target + neighbors, ordering, empty result). Combined with the documented defaults, limits, and input constraints, an agent has everything needed to call this correctly against a 5-parameter schema.
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 already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by stating that chunkIndex originates from a query_documents result and by restating the mutual-exclusion rule for filePath/source, plus the semantics of sourceContext's heading paths.
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?
States a specific verb and resource (read the chunks immediately before/after a query_documents result) and ties itself directly to the sibling query_documents, so an agent can distinguish it from a plain search. The scope constraint 'in the same document' further narrows what it returns.
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?
Explains the triggering context clearly: use it after a query_documents result when you need more surrounding context, and it names the exact input to carry over (chunkIndex plus one of filePath/source). It gives no explicit 'when not to use it' or alternative (e.g., re-running query_documents with a wider window), so it stops 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. Each changed PDF is re-ingested with the visual profile ("fast" or "quality") already recorded for it, so a PDF indexed with VLM captions keeps them; a PDF with no recorded profile stays text-only. There is no option to change a profile here — use the CLI (mcp-local-rag sync --visual) to set one, or ingest_file to replace the file, where a normal ingest clears the recorded profile. Stored images are unrelated: STORE_IMAGES applies to whatever this run re-ingests and never makes a file changed. 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?
No annotations are provided, so the description carries the full burden. It discloses side effects (index updates/removals), non-blocking execution, job retention, and process-exit loss. It also clarifies the behavior regarding visual profiles and STORE_IMAGES, ensuring the agent understands the tool's operational nuances.
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 overly verbose and repetitive. Phrases like 'visual profile' and 'only one job is kept' are repeated, and the whole text could be condensed to a few sentences without losing meaning. The single-paragraph structure lacks scannable clarity, and the redundancy detracts from conciseness.
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 covers the main operational aspects: return value, polling mechanism, job limitations, and process-exit behavior. It is slightly incomplete regarding error cases or permission requirements, but given the moderate complexity and the absence of an output schema, it provides sufficient context for correct 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 for 'path' is already highly detailed, covering optionality, file/directory semantics, baseDirs, and omission behavior. The tool description repeats this verbatim without adding new semantic information, so the value beyond the schema is minimal, resulting in the baseline score of 3.
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: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone.' It also specifies the non-blocking return of a jobId, making the tool's primary function 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?
Explicitly mentions alternatives and complementary tools: 'use the CLI (mcp-local-rag sync --visual) to set one, or ingest_file to replace the file' and 'poll sync_status with that jobId'. Also clarifies scope behavior and omission of path to sync all base directories, providing clear guidance on when and how to use the tool.
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.19.0query_documents2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Max results (default 10, range 1-20). Lower favors precision, higher recall."New value: +"Max results (default 10, range 1-100). Lower favors precision, higher recall."Input schema / properties / limit / maximumPrevious value: -20New value: +100v0.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."Scored across 9 tools
Most tools have clearly distinct purposes: ingest_file vs ingest_data split by source type, query_documents vs read_chunk_neighbors split by search vs context, and delete_file/list_files/sync_start are unique. The only mild overlap is status (index state) vs sync_status (sync job record), but descriptions disambiguate them well.
Seven of nine tools follow a clean verb_noun pattern (query_documents, read_chunk_neighbors, delete_file, ingest_data, ingest_file, list_files, sync_start). The two noun-only names (status, sync_status) are minor deviations but still readable and consistent with each other.
Nine tools is well-scoped for a local RAG server, with each tool earning its place across ingest, query, context, delete, list, sync, and status concerns. No redundant or filler tools.
The lifecycle is well covered: ingest (file/data), query, context retrieval, list, delete, sync, and status. The main gap is that changing a PDF's visual profile is only possible via the CLI, not through an MCP tool, though re-ingest provides a workaround.
Ingest, manage, and retrieve documents for RAG-powered AI applications
One semantic search across your sites, Drive, Notion, email, files and Basecamp.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Search everything you save: YouTube, articles, podcasts, PDFs, Notion, Obsidian. API key or OAuth.
