/mcp-local-rag

name: mcp-local-rag
description: Searches, saves, and maintains a local document index through a local RAG MCP server. Use when user says "search my docs", "save this page", "read around that chunk", "sync my index", or invokes `npx mcp-local-rag`.

MCP Local RAG Skills

Tools

| MCP Tool | CLI Equivalent | Use When | |----------|---------------|----------| | `ingest_file` | `npx mcp-local-rag ingest <path> [--visual]` | Local files (PDF, DOCX, TXT, MD). CLI for bulk/directory. PDF visual mode: see [Visual content (PDFs)](#visual-content-pdfs). | | `ingest_data` | — | Raw content (HTML, text) with source URL | | `query_documents` | `npx mcp-local-rag query <text>` | Semantic + keyword hybrid search; optional `scope` to limit to a path prefix | | `delete_file` | `npx mcp-local-rag delete <path>` | Remove ingested content | | `list_files` | `npx mcp-local-rag list [--scope <prefix>]` | File ingestion status; optional `scope` to limit to a path prefix (reachable scan path) | | `status` | `npx mcp-local-rag status` | Database stats | | `read_chunk_neighbors` | `npx mcp-local-rag read-neighbors` | Read N chunks adjacent to a known chunkIndex (context expansion; call after `query_documents` or grep) | | `sync_start` | `npx mcp-local-rag sync [path]` | Reconcile the index with disk after files changed outside this session. See [Index sync](#index-sync) | | `sync_status` | — | Poll a `sync_start` job for progress and its final outcome |

Workflow

1. For search requests, formulate a focused hybrid query, choose `limit` by intent, optionally narrow to a corpus/path with `scope`, then filter results by score AND topical relevance. 2. When a retrieved hit lacks enough surrounding context for a grounded answer, expand only that chunk via `read_chunk_neighbors`. 3. For ingestion, choose `ingest_file` for local files and `ingest_data` for raw/web content. 4. For PDFs, ask once about ingest mode unless the current request already specifies one (text-only, visual fast, or visual quality). See decision protocol in Ingestion. 5. Call `sync_start` once and poll `sync_status` when the user asks to synchronize, or when a change they reported on disk has to be reflected before you can answer. It replaces re-running `ingest_file` file by file.

Search: Core Rules

Hybrid search combines vector (semantic) and keyword (BM25).

Score Interpretation

Lower = better match. Use this to filter noise.

| Score | Action | |-------|--------| | < 0.3 | Use directly | | 0.3-0.5 | Include if mentions same concept/entity | | 0.5-0.7 | Include only if directly relevant to the question | | > 0.7 | Skip unless no better results |

Limit Selection

| Intent | Limit | |--------|-------| | Specific answer (function, error) | 5 | | General understanding | 10 | | Comprehensive survey | 20 |

Scope (Optional)

Use `scope` when one database mixes multiple corpora and you want results from only one. Pass an absolute path prefix, or a list (results are unioned); it matches a `filePath` equal to or under the prefix.

| Intent | scope | |--------|-------| | Search everything | omit | | One corpus/folder | absolute prefix, e.g. `/Users/me/docs/api` | | Several corpora | list of absolute prefixes |

Prefixes must be absolute, in the server's OS path style — relative prefixes match nothing. If the user gives a relative path, derive an absolute prefix from a `filePath` in an earlier `query_documents`/`list_files` result, or omit `scope` when no absolute prefix is known.

Query Formulation

| Situation | Why Transform | Action | |-----------|---------------|--------| | Specific term mentioned | Keyword search needs exact match | KEEP term | | Vague query | Vector search needs semantic signal | ADD context | | Error stack or code block | Long text dilutes relevance | EXTRACT core keywords | | Multiple distinct topics | Single query conflates results | SPLIT queries | | Few/poor results | Term mismatch | EXPAND (see below) |

Query Expansion

When results are few or all score > 0.5, expand query terms:

• Keep original term first, add 2-4 variants
• Types: synonyms, abbreviations, related terms, word forms
• Example: `"config"` → `"config configuration settings configure"`
• Cap expansion at 2-4 added terms to prevent topic drift.

Result Selection

When to include vs skip—based on answer quality, not just score.

**INCLUDE** if:

• Directly answers the question, OR
• Provides necessary context for the answer, OR
• Topically relevant AND score < 0.5

**SKIP** if:

• Shares keywords with the query but not intent
• Mentions the term without explanation
• Score > 0.7 AND better results exist

fileTitle

Each result includes `fileTitle` (document title extracted from content). Null when extraction fails.

| Use | How | |-----|-----| | Disambiguate chunks | Use fileTitle to identify which document the chunk belongs to | | Group related chunks | Same fileTitle = same document context | | Deprioritize mismatches | fileTitle unrelated to query AND score > 0.5 → rank lower |

Context Expansion (read_chunk_neighbors)

`read_chunk_neighbors` (CLI: `read-neighbors`) is an **on-demand context expansion utility**. Use it when a `query_documents` hit lacks enough surrounding context for a grounded answer. Chunks in this index are **semantic units** — sentences or paragraphs grouped by topic via Max-Min semantic chunking, not fixed-size text slices. Reading the chunks immediately before and after a target chunk yields coherent surrounding context, not arbitrary fragments.

Each `query_documents` result item includes `chunkIndex` plus either `filePath` or `source`. Pass `filePath` for files ingested with `ingest_file`, or `source` for content ingested with `ingest_data`.

Use this tool when one of these signals is present:

• **Insufficient context for your answer**: during response generation, the target chunk alone is not enough to reach a grounded conclusion (e.g., it references "this approach" or "as shown abov