shinpr/mcp-local-rag

MCP Search & Web

Local RAG for developers that provides semantic search with keyword boost, runs entirely offline, and requires zero‑friction setup via a single `npx` command.

Track releases GitHub

TypeScript Latest v0.14.2 · 11d ago Security brief →

Features

Semantic search with keyword boost prioritizing exact technical terms
Smart semantic chunking based on embedding similarity rather than character count
Quality‑first result filtering using relevance gaps instead of fixed top‑K
Runs fully locally with no external API calls or data exfiltration
Zero‑friction setup via a single `npx` command (no Docker, Python, or servers)

Recent releases

View all 24 releases →

Review required

v0.14.2 Security relevant 11d

RCE / SSRF Auth

Path rejection + realpath checks

Open

No immediate action

v0.14.1 New feature 17d

Quality visual profile

Open

No immediate action

v0.14.0 Breaking risk 18d

Env‑only MCP config

Open

v0.13.2 Bug fix 23d

Fixed read_chunk_neighbors handling of empty/whitespace file paths and improved validation error messages.

Full changelog

Patch release improving read_chunk_neighbors input validation.

Fixes

read_chunk_neighbors now treats an empty or whitespace-only filePath/source as not provided. Passing source: "" alongside a valid filePath returns the document window instead of resolving to an empty raw-data path and returning nothing.
The filePath/source validation error now matches the actual situation: "Provide either filePath or source, not both" when both are given, "Either filePath or source must be provided" when neither is.

Maintenance

Upgraded dev dependencies (@biomejs/biome, @types/node, knip, lint-staged, dpdm) to their latest non-major releases.

Contributors

Thanks to @dburner for the initial work on empty filePath/source handling.

View release on GitHub

v0.13.0 New feature 1mo

Notable features

`read_chunk_neighbors` tool (MCP and CLI) for retrieving asymmetric before/after chunks with configurable window sizes, target marking, and lenient boundary handling
Updated Agent Skills documentation to include context‑expansion guidance

Full changelog

What's New

New tool: read_chunk_neighbors — Expand a search result by reading the chunks immediately before and after it in the same document.

After finding a relevant chunk via query_documents, pass its chunkIndex and filePath (or source) to retrieve surrounding context in a single call. Useful when a hit answers a question only partially.

MCP Tool

read_chunk_neighbors({ filePath: "/path/to/doc.md", chunkIndex: 5 })

CLI

npx mcp-local-rag read-neighbors --file-path /path/to/doc.md --chunk-index 5

Key details

Asymmetric window: --before and --after control each direction independently (default 2, max 50)
Target marking: The requested chunk is included with isTarget: true
Lenient boundaries: Out-of-range indices return only existing chunks (no error)
Dual input: Accepts filePath (from ingest_file) or source (from ingest_data)
Skills docs updated: Agent Skills now include context-expansion guidance