Skip to main content
Glama
lemuelflores

mcp-semantic-search

by lemuelflores
OverviewSchemaSourceRelated ServersScoreDiscussions
TypeScript
Local

🔍 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: Personal Semantic Search MCP

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

Available Tools

3 tools
indexA

Index the specs/ directory in the current project (app). Automatically skips if content hasn't changed since last index.

ParametersJSON Schema
NameRequiredDescriptionDefault
reindexNoForce re-index even if content unchanged (default false)

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses the auto-skip behavior (content unchanged). Without annotations, the description carries the burden; it provides one key behavioral trait but no details on effects, auth, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero wasted words, highly efficient. Key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool (one optional param, no output schema), the description adequately covers purpose and behavior. Lacks explicit linkage to sibling tools, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers the single parameter 'reindex' with a description; the tool description adds no extra meaning beyond reinforcing the auto-skip context. With 100% schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Explicitly states 'Index the specs/ directory' (specific verb+resource). Clearly distinguishes from siblings 'search' and 'status' by its indexing action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'search' or 'status'. Does not mention prerequisites or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statusA

Show index status for the current project.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as side effects, performance implications, or access restrictions. It is too brief for full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, front-loaded with the action and object. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (no parameters, no output schema), the description is minimally adequate but does not elaborate on the return format or any nuances. It leaves the agent with little information beyond the basic purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivial. The description adds no parameter-specific meaning but the baseline for no parameters is 4, which is appropriate here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows index status, using a specific verb and resource. It is distinct from sibling tools 'index' and 'search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. The description only states what it does, without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv1.0.0
    • First observedindex
    • First observedsearch
    • First observedstatus
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a distinct, non-overlapping purpose: index builds the search index, search queries it, and status shows its state. No ambiguity exists among them.

Naming Consistency5/5

All three tool names are single lowercase words (index, search, status) that clearly describe their action. The naming pattern is uniform and predictable.

Tool Count5/5

Three tools are exactly right for a focused semantic search MCP server: index, search, and status cover the essential operations without excess or deficiency.

Completeness4/5

The set covers the core lifecycle (index, search, status) but lacks an explicit operation to clear or delete the index. This minor gap is acceptable for most use cases.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • AskDocs MCP Server

    dymk
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic search and retrieval of information from technical documentation PDFs using RAG-powered natural language queries with Ollama embeddings and LLMs.
    6
    -

  • Personal Semantic Search MCP

    Ethan2298
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic search over local notes and documents using natural language queries. Supports multiple file types (Markdown, Python, HTML, JSON, CSV, text) with fast local embeddings and persistent ChromaDB vector storage.
    1
    -

  • search-docs

    otolab
    A
    license
    A
    quality
    C
    maintenance
    Enables AI agents to search local Markdown documents using natural language, with automatic indexing and section-level retrieval.
    9
    5
    1
    MIT

  • Inkdex

    antonlunden
    A
    license
    A
    quality
    C
    maintenance
    Enables semantic search over local markdown documentation by indexing files and ranking results using vector similarity and BM25 fusion.
    1
    11
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lemuelflores/spec-search-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server