LocalVectorSearchMcp

# LocalVectorSearchMcp

<!-- mcp-name: io.github.DimonSmart/local-vector-search-mcp -->

**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

```text
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):

```bash
dotnet tool install --global DimonSmart.LocalVectorSearchMcp
```

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

```bash
dnx DimonSmart.LocalVectorSearchMcp@<version> --yes -- \
  --project-root "$PWD" --embedding-provider none --search-mode lexical --status
```

The [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.DimonSmart%2Flocal-vector-search-mcp) 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:

```bash
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@<version> --yes -- \
  --project-root "$PWD" --embedding-provider none --search-mode lexical --watch-files
```

Replace `<version>` 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:

```bash
local-vector-search-mcp --project-root "$PWD" \
  --embedding-provider none --search-mode lexical --reindex
```

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

```bash
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](docs/integrations/intent-driven-development.md)
for `.idd/intent`, explicit paths, `dnx`, and Claude Code.

## Optional hybrid/semantic quick start

### 1. Install the tool and embedding model

```bash
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

```bash
claude mcp add local-vector-search \
  --scope local \
  --transport stdio \
  -- local-vector-search-mcp
```

#### Codex

```bash
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](docs/clients/chatgpt-secure-tunnel.md).

### 3. Ask the agent to initialize and use the index

```text
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](docs/getting-started.md) for the complete setup and verification flow.

## Example tasks

```text
Before changing the indexing pipeline, find the documented architectural
decisions and constraints that apply to it.
```

```text
Search the project documentation for rules governing persisted state.
Summarize the relevant invariants and cite the source files.
```

```text
Attach this PNG and save it as cover.png in the project images folder.
Return the Markdown image reference.
```

## Capabilities

| Capability | Implementation |
|---|---|
| Exact search | SQLite FTS5 with BM25 |
| Semantic search | sqlite-vec |
| Hybrid ranking | Reciprocal Rank Fusion |
| Storage | Project-local SQLite |
| Indexed content | Markdown |
| Editable content | Markdown, guarded by exact element and subtree hashes |
| Image assets | PNG, JPEG, WebP, GIF; all image tools use root-relative paths, saving to `images/` by default |
| Navigation | File listing, image listing, and heading outlines |
| Transport | MCP over stdio |
| Clients | Claude Code, Codex, ChatGPT via OpenAI Secure MCP Tunnel |
| Default embeddings | Local Ollama-compatible endpoint; use `embedding.provider: none` for offline FTS5-only mode |

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:

```json
{
  "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.

| Goal | Arguments |
|---|---|
| List a directory | `{ "request": { "pathPrefix": "books" } }` |
| Select one file | `{ "request": { "pathPrefix": "books/chapter.md" } }` |
| Find matching names | `{ "request": { "includeGlob": "qa-*.md" } }` |
| Limit a pattern to a directory | `{ "request": { "pathPrefix": "books", "includeGlob": "**/*.md" } }` |

## PDF book export

`kb_create_pdf_book(path, outputPath?, pageFormat?, style?, profile?)` creates a PDF from a root-rela