# Kb Search Mcp

> Hybrid BM25 + vector search over a Markdown wiki, as a Model Context Protocol server for Claude Code. Cuts session-start token cost ~95% and adds a compaction-proof session scratchpad.

- **Type:** MCP server
- **Install:** `agentstack add mcp-draakaap-kb-search-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [draakaap](https://agentstack.voostack.com/s/draakaap)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [draakaap](https://github.com/draakaap)
- **Source:** https://github.com/draakaap/kb-search-mcp

## Install

```sh
agentstack add mcp-draakaap-kb-search-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# kb-search-mcp

A local, read-only MCP server that gives Claude Code persistent memory by
searching a markdown wiki on demand instead of loading it whole at session
start.

Session-start cost on a 226-page wiki dropped from ~25k tokens to ~600
tokens + 1–3 pages retrieved on demand. About 95% reduction, same recall
on a 20-query benchmark (20/20 top-3 hits, no tuning).

## What it exposes

| Tool | Purpose |
|---|---|
| `kb_search(query, k, alpha)` | BM25 + vector retrieval with Reciprocal Rank Fusion |
| `kb_get_page(slug)` | Fetch a wiki page by slug |
| `kb_top_important(n)` | Top-N pages by frontmatter `importance_score` |
| `kb_index_status()` | Schema version, chunk/vector counts, last reindex |

The wiki stays the source of truth — markdown in a folder. SQLite (FTS5 +
sqlite-vec) is the derived index, regenerable from disk in ~2 minutes via
the companion indexer.

## Repo layout

```
kb-search-mcp/
├── mcp/        — the read-only MCP server (.NET 10)
├── indexer/    — the indexer that produces wiki.db (.NET 10 CLI)
├── sample-wiki/— a tiny seed wiki so you can index and search out of the box
└── README.md
```

## Quick start

```powershell
# 1. Clone and restore
git clone https://github.com/draakaap/kb-search-mcp
cd kb-search-mcp

# 2. Fetch the native sqlite-vec extension (one-time)
./indexer/scripts/fetch-vec0.ps1

# 3. Index the bundled sample wiki
$env:KB_SEARCH_PROJECT = "your-gcp-project"
dotnet run --project indexer/src/KbSearchIndexer -- --full --wiki ./sample-wiki

# 4. Wire the MCP server in your .mcp.json
{
  "mcpServers": {
    "kb-search": {
      "command": "dotnet",
      "args": ["run", "--project", "/mcp/src/KbSearchMcp", "--no-build"],
      "env": { "KB_SEARCH_PROJECT": "your-gcp-project" }
    }
  }
}
```

## How it works

```
wiki/*.md  →  indexer  →  wiki.db (FTS5 + vec0)  →  MCP server  →  Claude Code
```

- **.NET 10** stdio MCP server, single self-contained binary
- **Microsoft.Data.Sqlite** with sqlite-vec loaded via `LoadExtension("vec0")`
- **Vertex AI** `text-embedding-005` (768d) for query embeddings, swappable
  behind `IQueryEmbedder`
- **RRF** with k=60 (Cormack/Clarke/Buettcher 2009), default α=0.6 —
  BM25-leaning because exact-token recall on technical jargon beat
  conceptual recall in the benchmark

The indexer chunks pages on H2/H3 boundaries with an 800-token soft cap,
hashes content for incremental updates, and writes vectors as float32
BLOBs into vec0.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `KB_SEARCH_PROJECT` | required | GCP project for Vertex embeddings |
| `KB_SEARCH_DBPATH` | `./wiki.db` | Override DB path |
| `KB_SEARCH_DEFAULTALPHA` | `0.6` | BM25 vs vector weight (0..1) |

The indexer also accepts CLI flags (`--wiki`, `--db`, `--model`, `--batch`)
that override the equivalent appsettings.

## Stack baseline

On a 226-page wiki: 1,931 chunks, 1,931 vectors, 10.5 MB DB.
Full reindex ~2 min. Incremental ~2 s.

## Known limits

- **Single-user.** WAL allows concurrent readers but the DB is a local file.
- **Index drift.** Edit the wiki without rerunning the indexer and search
  returns stale hits. `kb_index_status` reports `lastReindexAt` so you can
  detect this from the agent side.
- **No streaming.** Results return as a single payload.
- **Vertex dependency.** BM25-only fallback works without it but conceptual
  recall drops. Drop in OpenAI / a local embedder via `IQueryEmbedder`.

## License

MIT. See `LICENSE`.

## Related

This server is the retrieval layer of a larger setup that gives Claude Code
persistent memory across sessions. The full kit — 23 production-ready
skills, a 200+-page seed wiki, auto-memory bootstrapping, and a
session-start playbook — is at
[draakaap.gumroad.com/l/second-brain](https://draakaap.gumroad.com/l/second-brain).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [draakaap](https://github.com/draakaap)
- **Source:** [draakaap/kb-search-mcp](https://github.com/draakaap/kb-search-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-draakaap-kb-search-mcp
- Seller: https://agentstack.voostack.com/s/draakaap
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.