🔍 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.

Related MCP server: search-docs

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

Ollama Backend (Default)

Gemini Backend (Cloud Option)

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]

License

MIT