Local Vector Search MCP

LocalVectorSearchMcp

Give Codex, Claude Code, and ChatGPT a local, editable, project-aware Markdown workbench.

LocalVectorSearchMcp is a local MCP server that indexes one project's Markdown files into a project-local SQLite database. Agents can search, read focused semantic slices, edit by semantic pointer, manage Markdown files, navigate the workspace, and manage ordinary image assets.

It helps an agent find the right specification, architectural decision, guide, or invariant without loading the entire documentation set into its context.

Why use it?

Large repositories often contain the answer, but not in the file the agent happens to open first.

• Exact text search finds identifiers, API names, and quoted terminology.
• Vector search finds conceptually related documentation even when wording differs.
• Hybrid search combines both result lists through Reciprocal Rank Fusion.
• kb_read returns focused slices from the current Markdown source instead of forcing the agent to read whole files or wait for indexing.
• Element-level optimistic concurrency prevents an agent from overwriting a semantic target that changed after it was read, while unrelated document edits do not block the patch.
• Optional file watching keeps the index synchronized with edits from VS Code, Obsidian, or other editors.
• PNG, JPEG, WebP, and GIF files can be stored as non-indexed assets throughout knowledgeBase.root (default images/).
• Every project gets its own local SQLite index.
• No cloud database or mandatory YAML configuration is required.

How it works

Workspace Markdown (source of truth)

↓ Markdown elements and search chunks ↓ SQLite FTS5 (+ sqlite-vec when embeddings are enabled) ↓ Scoped retrieval + semantic editing ↓ MCP tools over stdio

images/ assets ↓ save / list / load / delete / safe move ↓ not indexed

Claude Code and Codex can launch the stdio server directly. ChatGPT can use the same MCP surface through OpenAI Secure MCP Tunnel, where the external tunnel-client bridges ChatGPT to the local stdio process.

Quick start: offline lexical search

Install the .NET tool (requires .NET 10):

dotnet tool install --global DimonSmart.LocalVectorSearchMcp

Alternatively, run a pinned published version directly with dnx (requires the .NET 10 SDK; no global tool install):

dnx DimonSmart.LocalVectorSearchMcp@<version> --yes -- \

--project-root "$PWD" --embedding-provider none --search-mode lexical --status

The official MCP Registry uses the canonical name io.github.DimonSmart/local-vector-search-mcp. A listing is available only after a matching NuGet release has been successfully registered.

To register the server using dnx without a global install:

codex mcp add local-vector-search -- dnx DimonSmart.LocalVectorSearchMcp@<version> --yes -- \

--project-root "$PWD" --embedding-provider none --search-mode lexical --watch-files

claude mcp add --transport stdio local-vector-search -- dnx DimonSmart.LocalVectorSearchMcp@ --yes -- \ --project-root "$PWD" --embedding-provider none --search-mode lexical --watch-files

Replace with a version published on NuGet.org, and run the commands from the Markdown project's root. The server uses stdio and offline lexical mode here; no Ollama endpoint or API key is required.

From the project you want to index, run the following. This needs no Ollama server, no remote embedding endpoint and no API key:

local-vector-search-mcp --project-root "$PWD" \

--embedding-provider none --search-mode lexical --reindex

Register a project-specific MCP server using the same arguments:

codex mcp add local-vector-search -- \

local-vector-search-mcp --project-root "$PWD" \ --embedding-provider none --search-mode lexical --watch-files

The SQLite FTS5 index is stored in .local-vector-search-mcp/index.db under the project root. Markdown remains the source of truth. The server is read-only for Markdown and images unless knowledgeBase.allowWrites: true is explicitly set in YAML.

See the IDD integration example for .idd/intent, explicit paths, dnx, and Claude Code.

Optional hybrid/semantic quick start

1. Install the tool and embedding model

dotnet tool install --global DimonSmart.LocalVectorSearchMcp

ollama pull bge-m3:latest

Make sure Ollama is running before the first reindex.

2. Connect your client

Run the command from the project whose documentation should be indexed.

Claude Code

claude mcp add local-vector-search \

--scope local \ --transport stdio \ -- local-vector-search-mcp

Codex

codex mcp add local-vector-search \

-- local-vector-search-mcp

ChatGPT

Keep LocalVectorSearchMcp as a local stdio server and bridge it with OpenAI Secure MCP Tunnel. For the tunnel scenario, use an explicit configuration with absolute knowledge-base and storage paths.

See ChatGPT via Secure MCP Tunnel.

3. Ask the agent to initialize and use the index

Check the local documentation index status. Reindex it if necessary,

then find the project's main architectural decisions and summarize them with file references.

By default, the server indexes *.md files under the detected project root and stores the index in .local-vector-search-mcp/index.db.

See Getting started for the complete setup and verification flow.

Example tasks

Before changing the indexing pipeline, find the documented architectural

decisions and constraints that apply to it.

Search the project documentation for rules governing persisted state.

Summarize the relevant invariants and cite the source files.

Attach this PNG and save it as cover.png in the project images folder.

Return the Markdown image reference.

Capabilities

The MCP server exposes eighteen tools. MCP reindexing is asynchronous: kb_reindex starts or joins the single active reindex and returns immediately, while kb_status.indexing reports progress and the last outcome. The CLI --reindex command remains synchronous and exits only after indexing finishes.

• kb_status — inspect the current index.
• kb_reindex — start a background build or rebuild; monitor kb_status.indexing for progress and the final result.
• kb_search — run optionally path-scoped lexical, semantic, or hybrid search against the derived index; each result identifies its indexed revision with indexedSourceHash.
• kb_read — read the current Markdown source from a semantic pointer and receive the exact source revision sourceHash.
• kb_patch — atomically replace/delete individual semantic elements or complete heading sections, and insert before/after elements.
• kb_edit_table — source-aware editing of GFM table cells, rows, columns and alignment through a hashed table pointer.
• kb_create, kb_move, kb_delete — manage Markdown source files.
• kb_list_files — list Markdown files and non-indexed assets; use pathPrefix for a directory or exact file, and includeGlob for filename patterns.
• kb_outline — return a deterministic heading tree.
• kb_create_pdf_book — render a Markdown document as a formatted PDF book.
• kb_download_file — return any permitted workspace file as a downloadable binary resource.
• kb_save_image — save an image supplied through the OpenAI file parameter (optional targetPath).
• kb_list_images — list supported image assets recursively with cursor pagination.
• kb_load_image — return an existing image as a real MCP image content block.
• kb_delete_image — delete one binary image under root without changing Markdown.
• kb_move_image — safely move one binary image anywhere inside root without changing Markdown references.

For low-level MCP or connector calls, a tool with no user arguments still uses an explicit empty arguments object. The canonical kb_status wire call is:

{

"name": "kb_status", "arguments": {} }

Clients should not rely on omitting the argument object; {} is the interoperable contract for parameterless tools.

File-list filters

kb_list_files.pathPrefix is a root-relative directory path or an exact file path, not a partial filename prefix. books and books/ include files below books/; books/chapter.md selects that exact file; books/chapter does not match books/chapter.md. Use includeGlob for filename matching. Both filters apply when supplied.

PDF book export

kb_create_pdf_book(path, outputPath?, pageFormat?, style?, profile?) creates a PDF from a root-relative Markdown file. It renders headings, emphasis, code, lists, quotes, links, GFM tables, and local images. The default output is the source name with a .pdf extension; it must remain under knowledgeBase.root. As a derived reading artifact, an existing PDF at that path is atomically replaced on the next export. Export requires knowledgeBase.allowWrites: true, does not alter Markdown, assets, or the search index, and returns {path,bytes,warnings}. Unavailable images are represented by a PDF placeholder and included in warnings; remote and absolute image URLs are not fetched. Formats: a4, a5 (default), a6, b5, letter; styles: compact (default), classic, modern, technical, academic.

Profiles (application-defined presets): screen = 96 DPI / JPEG quality 65, standard = 150 DPI / JPEG quality 82 (default), print = 300 DPI / JPEG quality 95. All profiles use PDF full compression, preserve Unicode text and the layout/physical size of images, and share identical embedded image resources. High-resolution JPEGs and PNGs may be downsampled; unchanged or already efficient files stay in their original encoding. JPEG with EXIF/ICC/Adobe metadata and PNG with explicit color metadata are preserved rather than risk altering orientation or colors; unsupported GIF/WebP retain the renderer's prior behavior. Output size is not guaranteed to fit kb_download_file's unchanged 25 MiB limit. Print is for ordinary printing, not PDF/X, CMYK production, or press-ready preflight. Image processing may take longer than before; the default profile may change the raster quality/size of previously exported PDFs.

Examples (all calls use the existing nested request):

{"request":{"path":"book.md","outputPath":"exports/screen.pdf","profile":"screen"}}

{"request":{"path":"book.md","