🔍 mcp-semantic-search

Ask your specs a question instead of grepping them.

An MCP server & CLI that gives AI agents local semantic search over markdown docs — running 100% on your machine by default.

---

Why use this?

Traditional grep misses ideas that don't match exact keywords.

mcp-semantic-search understands intent across your local specs, RFCs, and internal docs.

$ mcp-semantic-search search "how do we stop repeated failed logins"

--- Result 1  [0.688]  content ---
file: auth.md
section: Sessions > Credential attempts

After five consecutive bad passwords the account enters a 15-minute
cooling-off period. The counter resets on any successful sign-in.

--- Result 2  [0.541]  content ---
file: gateway.md
section: Rate limits > Edge throttling

A single IP address is capped at 20 requests per minute against
/session endpoints. Anything beyond that receives a 429 before it
ever reaches the application.

Notice: Neither chunk contains the words "failed" or "login" — grep -ri "failed login" returns nothing at all. Semantic search finds both halves of the answer: the account lockout in the auth spec, and the network throttle that backs it up in a different file with entirely different vocabulary.

---

Key Features

• 🧱 Structure-Aware Chunking — Splits markdown on heading boundaries (H1–H4) without breaking code blocks or tables.
• 🔒 Local & Private — Runs via LanceDB & Ollama. Zero docs leave your machine.
• 🗺️ Document Maps — Generates outline (toc) chunks so agents can scan doc structures before reading details.
• ⚡ Zero-Overhead Indexing — File hashes ensure re-indexing only happens when files actually change.
• 🎯 Targeted Filtering — Filter search by filename, heading, or chunk type (content, code, table, toc).

---

Quick Start

1. Requirements & Build

Requires Node.js 22+ and Ollama (or a Gemini API key).

# Pull default model
ollama pull qwen3-embedding:0.6b

# Clone & Build
git clone <repo-url> mcp-semantic-search
cd mcp-semantic-search
npm install && npm run build

2. Run locally (CLI)

Inside the target repository you want to index:

cd ~/projects/my-app
echo '.mcp-search/' >> .gitignore

/path/to/mcp-semantic-search index
/path/to/mcp-semantic-search search "how are expired sessions cleaned up"

---

Setup as an MCP Server

Add to your project's .mcp.json:

{
  "mcpServers": {
    "specs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-semantic-search/dist/index.js"]
    }
  }
}

MCP Tools Exposed

• index — Indexes your markdown specs directory (set reindex: true to force rebuild).
• search — Queries indexed documents (query, file, section, chunk_type, limit, min_score).
• status — Checks index health, chunk counts, and staleness.

Agent Prompting Tip (CLAUDE.md): Add this to your project's CLAUDE.md: "Search specs using the specs MCP server. Run index first if status shows the index as missing or stale."

---

Configuration

Set environment variables in your shell or directly inside .mcp.json under the "env" block.

Global Settings

Variable	Default	Purpose
EMBEDDING_BACKEND	ollama	Vector provider: ollama or gemini
SPECS_DIR	<project>/specs	Absolute path to markdown specs
DB_PATH	<project>/.mcp-search	Where LanceDB index is stored
MIN_SCORE	0.44	Default similarity threshold

Ollama Backend (Default)

Variable	Default	Purpose
OLLAMA_BASE_URL	http://localhost:11434	Endpoint for Ollama daemon
OLLAMA_EMBEDDING_MODEL	qwen3-embedding:0.6b	Embedding model to use

Gemini Backend (Cloud Option)

Variable	Default	Purpose
GEMINI_API_KEY	(Required)	Required when EMBEDDING_BACKEND=gemini
GEMINI_EMBEDDING_MODEL	gemini-embedding-001	Embedding model to use
GEMINI_EMBEDDING_DIMENSIONS	768	Vector width (128–3072)

Note: Changing backends automatically triggers a clean index rebuild on the next run.

Example .mcp.json with Custom Config

{
  "mcpServers": {
    "specs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-semantic-search/dist/index.js"],
      "env": {
        "SPECS_DIR": "/absolute/path/to/my-app/docs",
        "EMBEDDING_BACKEND": "gemini",
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

CLI Options

mcp-semantic-search search <query> [options]

Flag	Description	Default
--file <str>	Filter by matching filename	—
--section <str>	Filter by matching section heading	—
--chunk-type <type>	content | code | table | toc	All
--limit <n>	Max results to return	5
--min-score <f>	Similarity floor (0.0–1.0)	0.44
--json	Output raw JSON instead of plain text	false

---

License

MIT