A privacy-first local document search server that enables semantic search through your documents without sending data to external services. All operations run entirely on your machine using local embedding models and a LanceDB vector database.
Core Capabilities:
Semantic Document Search (query_documents) - Search using natural language queries that understand meaning rather than keywords. Returns 1-20 relevant passages with similarity scores.
Document Ingestion (ingest_file) - Process and index PDF, DOCX, TXT, and Markdown files through text extraction, intelligent chunking with overlap, and embedding generation. Automatically updates documents upon re-ingestion.
File Management (list_files) - View all indexed documents with file paths and chunk counts. Permanently delete specific files and their associated data.
System Status (status) - Monitor server health including total documents, chunks, database size, memory usage, and configuration.
Key Features:
Complete Privacy: No data leaves your machine after initial model download; strict path restriction to configured BASE_DIR
Offline Operation: Works without internet once the embedding model is cached
Fast Performance: Query responses typically under 3 seconds even with thousands of chunks
Zero Cost: No API fees or subscriptions
No Complex Setup: Runs via npx with no installation required
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 "Install 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.
Runs locally: Document parsing, embeddings, storage, and search run on your machine. After the initial model download, text ingestion and search work offline.
Hybrid search: Semantic retrieval finds related concepts, while keyword matching boosts exact technical terms.
Configurable embeddings: Choose a Hugging Face embedding model that fits the language and domain of your documents.
Semantic chunking: Documents are split at topic boundaries instead of fixed character counts. Markdown code blocks stay intact.
MCP and CLI: Use the same index from an AI coding tool or directly from the terminal.
No API key, Docker, Python, or external database is required.
Related MCP server: cowork-semantic-search
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.
mcp-local-rag uses the standard MCP protocol over a local stdio server, so it works with AI coding tools and other MCP hosts that support local MCP servers.
Use one of the examples below, or register npx -y mcp-local-rag and set BASE_DIR using your
client's MCP configuration format.
For Claude Code: Run this command:
claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-ragFor Codex: Add 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"For OpenCode: 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"
}
}
}
}For Cursor: 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.
Some document sets cannot be sent to a hosted embedding service because of confidentiality or organizational policy. Keeping the index local makes them searchable without adding a per-query API cost.
Semantic search alone can miss exact identifiers that matter in technical documentation. Keyword reranking keeps those terms visible without giving up natural-language retrieval.
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.
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 |
sync_start ingests new and changed files, skips byte-identical files, and removes index entries
for files that no longer exist:
Sync everything under the configured document roots and wait for completion.The tool returns a jobId immediately. Clients should poll sync_status until its state becomes
succeeded or failed. Sync does not generate visual captions. Set STORE_IMAGES=true in the
MCP server environment to store supported PDF and DOCX images for new or changed files selected
by sync; unchanged files remain skipped.
Only one sync job is retained by the server process. A newer job replaces a finished record, and restarting the server discards it.
ingest_file accepts PDF, DOCX, TXT, and Markdown. MCP file paths must be absolute and must stay
inside a configured document root:
Ingest the document at /Users/me/docs/api-spec.pdf.Re-ingesting the same path replaces its existing chunks.
What does the API documentation say about authentication?
Find the documented behavior of ERR_CONNECTION_REFUSED.Results contain the text, source path, title, chunk index, relevance score, and any images stored
on that chunk. MCP returns each image as an image content block paired with its result identity;
CLI query includes an images array of { imageIndex, mimeType, data } on every result. Pass the
chunkIndex and either filePath or source from a result to read_chunk_neighbors when the
answer needs more context:
Read the surrounding chunks for that authentication result.Both query_documents and list_files accept an optional absolute scope path prefix, or a
list of prefixes. A prefix matches the exact path and its descendants.
Use ingest_data after the MCP client fetches a page:
Fetch https://example.com/docs and ingest the HTML.The server extracts the main article, converts it to Markdown, and stores it under the supplied source identifier. Reusing the same source updates the existing content.
Respect the source site's terms and copyright when indexing external content.
Visual mode adds a generated caption for figure-heavy PDF pages. It is opt-in and does not load a vision model during normal ingestion.
Ingest /Users/me/docs/research-paper.pdf with visual: true.npx mcp-local-rag ingest ./docs/research-paper.pdf --visualImage storage is independent of visual captions. Set STORE_IMAGES=true for the MCP server, or
pass --images to CLI ingestion and sync:
npx mcp-local-rag ingest ./docs/research-paper.pdf --images
npx mcp-local-rag sync ./docs/ --imagesPDF storage uses detected figure/table regions. DOCX storage includes only PNG/JPEG images that
the existing Mammoth conversion emits as <img>; charts, SmartArt, and shapes are not separately
rendered. Stored images follow their surrounding text into the final semantic chunk and do not
alter ranking, scores, or result count.
|
| PDF behavior |
false | false | Text only; no visual captions or returned images. |
true | false | Generated captions become searchable text; no images are stored or returned. |
true | true | Generated captions become searchable text, and images from matched chunks are returned inline. |
false | true | Images are attached to nearby retained PDF text and returned inline for matched chunks; the VLM is not imported, loaded, or run. |
Profile | Model cache | Use case |
| about 250 MB | Lightweight visual indexing |
| about 2.9 GB | Figures containing labels, annotations, or other in-image text |
Select the larger model with visualQuality: "quality" over MCP or
--visual-quality quality over CLI. Measured CPU inference was about twice as slow as fast,
though results depend on hardware and model updates.
Captions are auxiliary text, not faithful transcriptions. Treat retrieved captions and document text as untrusted input rather than instructions.
At high limits, matched chunks and their attachments can approach the model/client context ceiling; choose the query limit with the calling model's available context in mind.
The CLI uses the same parser, embedder, and vector store without an MCP client:
npx mcp-local-rag ingest ./docs/
npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "authentication API"
npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"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.
The CLI does not read MCP client configuration. Set the same environment variables or flags if
both interfaces should share an index. In particular, MODEL_NAME and the CLI --model-name
must match for a shared database.
Keyword boost is enabled by default. Relevance-gap grouping and the distance and file filters are optional controls for corpora that need tighter result selection.
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., |
For API specifications and other documents containing many identifiers, a stronger keyword weight can improve exact-term ranking:
"env": {
"RAG_HYBRID_WEIGHT": "0.7"
}0.7: slightly stronger exact-term reranking than the default
1.0: maximum keyword boost
During ingestion:
The parser extracts text for the input format.
The semantic chunker finds topic boundaries and preserves Markdown code blocks.
Transformers.js creates embeddings locally.
LanceDB stores the chunks, metadata, vectors, and full-text index.
During search:
The query is embedded with the same model.
Vector search retrieves semantically related chunks.
Optional distance and relevance-group filters narrow the candidates when configured.
Full-text matches boost exact query terms.
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.
The MCP server reads environment variables. The CLI accepts the listed global environment
variables and flags; image storage on CLI ingestion and sync is enabled only with --images.
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 |
|
|
| Hugging Face embedding model |
|
|
| Maximum file size in bytes |
|
|
| Minimum chunk length in characters (1–10000) |
| N/A |
| MCP server only: store supported PDF/DOCX images and return them with matched chunks. CLI uses |
| N/A |
| ONNX Runtime execution device |
| N/A |
| Embedding dtype passed to the selected model |
BASE_DIR and BASE_DIRS)mcp-local-rag only allows file operations inside configured roots. For multiple roots,
BASE_DIRS must be a JSON array of non-empty paths:
export BASE_DIRS='["/Users/me/Documents/work","/Users/me/Projects/specs"]'Root configuration is resolved in this order:
CLI --base-dir <path> flags (repeatable on ingest, list, and sync)
BASE_DIRS
BASE_DIR
Current directory
Each source replaces the lower-priority source rather than merging with it. Invalid BASE_DIRS
configuration fails instead of falling back to BASE_DIR or the current directory. status
remains available in MCP so the client can report the configuration error.
npx mcp-local-rag ingest --base-dir /Users/me/work --base-dir /Users/me/specs /Users/me/work/readme.md
npx mcp-local-rag list --base-dir /Users/me/work --base-dir /Users/me/specs
npx mcp-local-rag sync --base-dir /Users/me/work --base-dir /Users/me/specs
BASE_DIRS='["/Users/me/work","/Users/me/specs"]' npx mcp-local-rag listDB_PATH and CACHE_DIR are relative to the process working directory by default. Set absolute
paths when the MCP client may start the server from different project directories.
Set MODEL_NAME or pass --model-name to choose a Hugging Face embedding model that fits the
language and domain of your documents.
mcp-local-rag generates embeddings with mean pooling and L2 normalization. When choosing a model, check whether these settings match its recommended inference setup, since the pooling method can affect retrieval quality.
Changing MODEL_NAME, RAG_DEVICE, or RAG_DTYPE can make existing vectors incompatible.
Use a new DB_PATH or delete the existing index and re-ingest after changing the embedding
configuration.
An example model for English documents is Xenova/bge-small-en-v1.5.
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.
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.
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 provided, so description bears full burden. Mentions return fields but does not disclose side effects, permissions, or error cases (e.g., what happens if nothing matches).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no redundancy. Purpose, usage, and return are clearly separated and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, constraints, and return values. Lacks explanation of edge cases (both params provided or neither) but is generally sufficient given tool simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet description adds context by linking each parameter to the specific ingestion method and clarifying the mutual exclusivity requirement, which is not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and object (previously ingested file/data from vector database). Distinguishes from sibling tools which are for ingestion, listing, querying, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use filePath vs. source and states that at least one must be provided. Could further specify behavior if both are given or if the item does not exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest in-memory content as a string (use ingest_file for files on disk). The source identifier enables re-ingestion to update existing content. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to ingest (text, HTML, or Markdown) | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format but does not discuss side effects, idempotency, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste: first sentence states purpose and sibling alternative, second sentence adds key behavioral detail and return format. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nested object parameters and no output schema, the description covers purpose, parameters with examples, and return values. Lacks error conditions or prerequisites, but sufficient for most agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning to both parameters: content format types and detailed metadata source examples. Schema coverage is 50% but description compensates with concrete usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states it ingests in-memory content as a string and differentiates from ingest_file for files on disk. Specific verb+resource with clear distinction from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions when to use this tool ('use ingest_file for files on disk') and hints at re-ingestion capability. Lacks explicit when-not-to-use scenarios, but the sibling distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a document file (PDF, DOCX, TXT, MD) into the vector database. Path must be absolute; re-ingesting the same path replaces its existing data. Returns { filePath, chunkCount, timestamp, fileTitle }.
| Name | Required | Description | Default |
|---|---|---|---|
| visual | No | Run VLM captioning on figure pages (PDF only; default false). | |
| filePath | Yes | Absolute path to the file to ingest. Example: "/Users/user/documents/manual.pdf" | |
| visualQuality | No | VLM profile when visual is true (default "fast"). "quality" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false. | fast |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that ingestion is a write operation, that re-ingesting replaces existing data, and that it supports VLM captioning for PDFs with different quality profiles. It also specifies the return structure. This is thorough for a tool of this complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the main purpose, and the second adds critical behavioral details. No extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no nested objects, the description covers input requirements (absolute path), behavior (replace on re-ingest), return fields, and an optional feature (VLM captioning). It briefly addresses PDF-only behavior. Missing details like error handling or unsupported file types, but overall sufficient for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context like 'Path must be absolute' and the effect of re-ingesting, but the schema already describes each parameter adequately. No additional semantic depth beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Ingest', the resource 'document file (PDF, DOCX, TXT, MD)', and the destination 'into the vector database'. It distinguishes from siblings like 'delete_file' and 'list_files' by specifying file ingestion. The mention of absolute path and re-ingest behavior adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: 'Path must be absolute' and 're-ingesting the same path replaces its existing data'. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'ingest_data'), nor does it give exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested. Returns { baseDirs, files, sources }; sources lists ingested items reported apart from the file scan, chiefly ingest_data content (web pages, clipboard, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. "/docs/api" matches "/docs/api/x.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds value by explaining that 'sources' contains ingested items like web pages/clipboard, and that files are scanned from base directories. It doesn't explicitly state this is read-only or describe side effects, but the 'list' verb implies safety. Some edge behavior (e.g., invalid scope yielding empty files list) is only visible in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the core purpose, and the second explains the return structure and the 'sources' nuance. There is no redundancy or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with one optional parameter and no output schema, the description sufficiently covers the purpose, return shape, and the non-obvious 'sources' concept. It doesn't need to explain return values in detail since the return shape is stated. Path edge cases are handled in the schema, so the description is complete enough for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of the parameter 'scope' with a detailed explanation of prefix matching and path constraints. The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('list') and resource ('supported files (PDF, DOCX, TXT, MD)') under configured base directories, plus the ingestion status. This clearly distinguishes it from sibling tools like ingest_file, delete_file, and sync_status, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for inspecting the file inventory and its ingestion status, which is a distinct use case. It also explains the return shape to set expectations. However, it doesn't explicitly mention when not to use it or reference sibling alternatives, though the purpose is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ingested documents with hybrid keyword + semantic matching. Returns results sorted by relevance, each with filePath, chunkIndex, text, fileTitle, score (0 = best, higher = worse), and source (for ingest_data items).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10, range 1-20). Lower favors precision, higher recall. | |
| query | Yes | Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match). | |
| scope | No | Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. "/docs/api" matches "/docs/api/auth.md" but not "/docs/apiv2". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details return fields, sorting by relevance, and score meaning (0=best, higher=worse). It lacks pagination details but is generally transparent for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with clear, front-loaded purpose and a concise list of return fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers purpose, behavior, and return fields comprehensively. Context from sibling tools and parameter count is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds value by listing output fields not present in schema, enhancing parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ingested documents using hybrid keyword and semantic matching, and lists the return fields. It is distinct from sibling tools like list_files and read_chunk_neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (for searching documents) but does not explicitly state when not to use or provide alternatives among siblings. No exclusion criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the chunks immediately before and after a query_documents result, in the same document, for more surrounding context. Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data). Returns the target chunk (isTarget: true) and its neighbors, ascending by chunkIndex; an out-of-range chunkIndex returns []. Defaults: before=2, after=2 (max 50 each).
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Number of chunks to retrieve after the target (0–50, default 2). | |
| before | No | Number of chunks to retrieve before the target (0–50, default 2). | |
| source | No | Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: "https://example.com/page", "clipboard://2024-12-30". | |
| filePath | No | Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: "/Users/user/documents/manual.pdf". | |
| chunkIndex | Yes | Zero-based target chunk index (non-negative integer). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It details the behavior (reads neighbors), return structure (target with isTarget: true, ascending order), edge case (out-of-range returns []), and limits (defaults before/after=2, max 50 each). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise, and front-loaded with the most important information. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully covers the tool's behavior, parameter usage, return structure, and edge cases. It ties to the sibling tool query_documents, providing necessary context for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for all five parameters. The description adds value by explaining the mutual exclusivity of filePath and source, the default values for before and after, and the connection to query_documents for chunkIndex.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb ('Read'), the resource ('chunks immediately before and after'), and the context ('in the same document, for more surrounding context'). It ties the tool to query_documents, distinguishing it from siblings like query_documents itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit instructions on parameter usage: pass chunkIndex from query_documents and exactly one of filePath or source. It also states defaults and max limits. However, it doesn't explicitly state when not to use this tool or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get index status: { documentCount, chunkCount, memoryUsage (MB), uptime (s), ftsIndexEnabled, searchMode }.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not explicitly state read-only nature or other behavioral traits like cost or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, description fully covers functionality and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; description adds value by listing return fields beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states it gets index status and lists return fields, clearly distinguishing from sibling tools like delete_file or query_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives, but the simple nature (no parameters) makes usage implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone. Returns { jobId } without waiting for the run to finish; poll sync_status with that jobId for progress and the final outcome. Only one job is kept, and it is lost when the server process exits.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional absolute path to a file or directory inside a configured base directory; list_files returns those directories as baseDirs. A file synchronizes only itself and a directory only its own subtree, leaving every path outside it untouched. Omit it to synchronize every configured base directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: asynchronous execution (returns jobId without waiting), single-job constraint, and job loss on server exit. It also notes that index entries are removed for missing files, making side effects transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first states the core purpose, the second explains the return value and polling, and the third adds a critical lifecycle constraint. Every sentence contributes essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter, no annotations, and no output schema, the description fully captures the tool's behavior, return format, and lifecycle. It also refers to sync_status for progress, completing the operational picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a 100% coverage description for the 'path' parameter, explaining its optionality, scope, and behavior. The tool description adds no extra parameter context, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Reconcile the index with the files on disk' and enumerates specific behaviors (ingest new/changed, leave unchanged, remove gone entries). This distinguishes it from sibling tools like ingest_file or delete_file, which handle single files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (reconciling an index with disk state) and implicitly contrasts with sync_status for polling. It lacks explicit 'when not to use' statements or alternative tool names, but the context is unambiguous enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current or latest sync job record: { jobId, state ("running" | "succeeded" | "failed"), total (null until scanning has counted the files on disk), completed (upserted + skipped + empty; pruned is counted separately), summary { upserted, skipped, empty, pruned }, warnings, error (null unless the job failed) }. An unknown jobId means the job was replaced by a newer one or lost with a previous server process.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Identifier returned by sync_start. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It transparently explains field nullability (total null until scanning, error null unless failed), the enumerated state values, and the unknown jobId case. This gives the agent a complete picture of expected behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but intentionally structured to mirror the returned object, making the field relationships clear. The second sentence adds essential edge-case information without fluff. It is compact given the amount of detail about the response shape.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description fully defines every return field and its conditional behavior, including a nested summary object. It also references sync_start and server process loss to situate usage, making the tool self-sufficient in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers jobId ('Identifier returned by sync_start') at 100% coverage. The description adds extra meaning beyond the schema by explaining the consequences of an unknown jobId, which enriches the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the current or latest sync job record', providing a specific verb+resource. It further details the exact output shape including state values, total/completed semantics, and nested summary, clearly distinguishing it from sibling tools like sync_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: after starting a sync job, call this to retrieve its status. It explains the meaning of an unknown jobId (replaced or lost with server process), which guides the agent on interpreting results. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.17.3list_files1 field changedInput schema / properties / scope / descriptionPrevious value: -"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."New value: +"Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. A prefix outside every base directory yields an empty files list, so compare it against the baseDirs in the response before concluding no files exist. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed."sync_startsync_statusv0.16.1list_files1 field changedInput schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting the listing to files reachable at a path equal to or under a prefix within the base directories. \"/docs/api\" matches \"/docs/api/x.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing. Scope filters files by their scan path; ingest_data sources, which have no base-directory path, are always listed.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}v0.15.3ingest_data1 field changedInput schema / properties / metadata / properties / format / descriptionPrevious value: -"Content format: \"text\", \"html\", or \"markdown\""New value: +"Content format: text (plain/copied text), html (fetched web pages), or markdown."ingest_file2 fields changedInput schema / properties / visual / descriptionPrevious value: -"If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files."New value: +"Run VLM captioning on figure pages (PDF only; default false)."Input schema / properties / visualQuality / descriptionPrevious value: -"VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false."New value: +"VLM profile when visual is true (default \"fast\"). \"quality\" is more accurate on figures with in-image text but much heavier and slower. Ignored when visual is false."query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Max results (default 10, range 1-20). Lower favors precision, higher recall."Input schema / properties / query / descriptionPrevious value: -"Search query. Include specific terms and add context if needed."New value: +"Search query. Preserve specific user terms (for keyword match); add context when the query is vague (for semantic match)."Input schema / properties / scopeAdded value: +{
+ "description": "Optional absolute path prefix(es) — one string or a list (unioned) — restricting results to a filePath equal to or under a prefix. \"/docs/api\" matches \"/docs/api/auth.md\" but not \"/docs/apiv2\". Must be absolute (server OS style); a relative prefix matches nothing — derive one from a filePath returned by an earlier query, or omit scope.",
+ "oneOf": [
+ {
+ "type": "string"
+ },
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ ]
+}read_chunk_neighbors2 fields changedInput schema / properties / filePath / descriptionPrevious value: -"Absolute path to the file (for documents ingested via ingest_file). Example: \"/Users/user/documents/manual.pdf\". Provide either filePath or source, not both."New value: +"Absolute path to the file (for ingest_file documents). Provide exactly one of filePath or source. Example: \"/Users/user/documents/manual.pdf\"."Input schema / properties / source / descriptionPrevious value: -"Source identifier used in ingest_data (for data ingested via ingest_data). Examples: \"https://example.com/page\", \"clipboard://2024-12-30\". Provide either filePath or source, not both."New value: +"Source identifier (for ingest_data documents). Provide exactly one of filePath or source. Examples: \"https://example.com/page\", \"clipboard://2024-12-30\"."v0.15.0query_documents3 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."New value: +"Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / limit / maximumAdded value: +20Input schema / properties / limit / minimumAdded value: +1v0.14.1ingest_file1 field changedInput schema / properties / visualQualityAdded value: +{
+ "default": "fast",
+ "description": "VLM profile to use when visual is true. \"fast\" (default) is the lightweight SmolVLM-256M; \"quality\" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to \"fast\"). Silently ignored when visual is false.",
+ "enum": [
+ "fast",
+ "quality"
+ ],
+ "type": "string"
+}v0.14.0ingest_file1 field changedInput schema / properties / visualAdded value: +{
+ "description": "If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files.",
+ "type": "boolean"
+}v0.13.0read_chunk_neighborsv1.0.0delete_fileingest_dataquery_documents2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results to return (default: 5, max recommended: 20)"New value: +"Maximum number of results to return (default: 10). Recommended: 5 for precision, 10 for balance, 20 for broad exploration."Input schema / properties / query / descriptionPrevious value: -"Natural language search query (e.g., \"transformer architecture\", \"API documentation\")"New value: +"Search query. Include specific terms and add context if needed."ingest_filelist_filesquery_documentsstatusEach tool has a distinct purpose: sync_status tracks job progress while status reports index stats; ingest_file vs ingest_data clearly separate file-based and in-memory ingestion; query_documents, read_chunk_neighbors, delete_file, list_files, and sync_start all target different operations. No two tools are likely to be confused.
Most tools follow a verb_noun pattern (query_documents, ingest_file, delete_file, list_files, read_chunk_neighbors), but sync_status, sync_start, and status deviate, using noun compounds or a standalone noun. The mix is readable but not uniform.
9 tools is well-scoped for a local RAG server, covering ingestion (file and data), deletion, querying, context expansion, file listing, and status/sync operations without unnecessary redundancy or bloat.
The set covers the core lifecycle: ingest (file/data), delete, search, and context retrieval. Minor gaps include no direct way to fetch all chunks of a specific document or a bulk clear operation, but these can be worked around with existing tools like query_documents and sync_start.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Versioned documentation registry and semantic search for AI tools and coding assistants.
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Search everything you save: YouTube, articles, podcasts, PDFs, Notion, Obsidian. API key or OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinpr/mcp-local-rag'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
