embed-guide

mcp-vector-search

Semantic search for your documents, available to AI agents via MCP.

Index documentation, code, and knowledge bases with semantic embeddings. AI assistants can search on-demand without loading everything into context.

;; .mcp-vector-search/config.edn
{:sources [{:path "/docs/**/*.md"}]}

# Search from Claude Code
"Find authentication documentation"
→ Returns relevant docs based on semantic similarity

Quick Links: Quick Start · Installation · What & Why · Advanced Features

---

Table of Contents

• Quick Start
• What & Why
• Installation
• Basic Configuration
• Using the Search Tool
• Claude Code Plugins
• Advanced Features
• Development
• Documentation

Quick Start

1. Install the MCP server (requires Clojure CLI tools):

# Add to ~/.clojure/deps.edn
{:aliases
 {:mcp-vector-search
  {:replace-paths []
   :replace-deps {org.hugoduncan/mcp-vector-search
                  {:git/url "https://github.com/hugoduncan/mcp-vector-search"
                   :git/sha "LATEST_SHA_HERE"}
                  org.clojure/clojure {:mvn/version "1.12.3"}}
   :jvm-opts ["--enable-native-access=ALL-UNNAMED"]
   :exec-fn mcp-vector-search.main/start}}}

# Configure Claude Code
claude mcp add mcp-vector-search -- $(which clojure) -X:mcp-vector-search

2. Create config file at ~/.mcp-vector-search/config.edn or .mcp-vector-search/config.edn:

{:sources [{:path "/path/to/your/docs/**/*.md"}]}

3. Restart Claude Code - the search tool is now available.

4. Search from Claude Code:

"Search for authentication best practices"
"Find code examples for user validation"
"Show me documentation about API rate limiting"

The assistant will use the search tool to find relevant content semantically, without you loading all documents into context.

What & Why

What It Does

mcp-vector-search is an MCP server that:

• Indexes documents using semantic embeddings (AllMiniLmL6V2 model)
• Provides a search tool to AI assistants via the Model Context Protocol
• Enables semantic search - find content by meaning, not just keywords
• Filters by metadata - narrow searches to specific projects, categories, or file types
• Works as a library - embed in your own MCP servers with bundled documentation

Why Use It

Expand what's accessible, not what's loaded. AI agents have limited context windows. Instead of loading all documentation upfront, they search when needed.

Key benefits:

• Work with knowledge bases larger than context windows
• Discover related content through semantic similarity
• Retrieve information just-in-time, not speculatively
• The search tool doesn't consume context - only results do

When to use:

• Large documentation sets (hundreds of pages)
• Multi-project codebases (find patterns across projects)
• Historical context (design docs, decision logs)
• API references (look up functions and examples as needed)
• Custom MCP servers needing semantic search over bundled documentation

See doc/about.md for a detailed explanation of the problem and solution.

Library usage: mcp-vector-search can be embedded in your own MCP servers to provide semantic search over bundled resources. See doc/library-usage.md for details.

Installation

Prerequisites

• Clojure CLI tools
• Java 11+ (required for embedding model)

Configure Clojure Alias

Add to ~/.clojure/deps.edn:

{:aliases
 {:mcp-vector-search
  {:replace-paths []
   :replace-deps {org.hugoduncan/mcp-vector-search
                  {:git/url "https://github.com/hugoduncan/mcp-vector-search"
                   :git/sha "LATEST_SHA_HERE"}
                  org.clojure/clojure {:mvn/version "1.12.3"}}
   :jvm-opts ["--enable-native-access=ALL-UNNAMED"]
   :exec-fn mcp-vector-search.main/start}}}

Note: Replace LATEST_SHA_HERE with the latest commit SHA from this repository.

Add to MCP Client

Claude Code:

claude mcp add mcp-vector-search -- $(which clojure) -X:mcp-vector-search

Claude Desktop, Cline, and other MCP clients: See doc/install.md for setup instructions and troubleshooting.

Basic Configuration

Configuration file location (first found is used):

• .mcp-vector-search/config.edn (project-specific)
• ~/.mcp-vector-search/config.edn (global)

Minimal Example

{:sources [{:path "/docs/**/*.md"}]}

Indexes all markdown files recursively under /docs/.

Path Patterns and Metadata

Path specs support globs (*, **), regex captures, and custom metadata:

;; Basic: recursive glob
{:sources [{:path "/docs/**/*.md"}]}