Local Mcp Search

local-mcp-search

Chinese README: [README.zh-CN.md](/D:/traeprj/mcpsd/README.zh-CN.md)

local-mcp-search is a Windows-first local STDIO MCP Server for Codex, Claude Code, and similar MCP-capable coding agents. The core idea is simple: use a small amount of local CPU/GPU for retrieval, reranking, and context compression, so the remote model spends less budget on blind scanning and more budget on reasoning and editing.

Why It Matters

Without a local retrieval layer, coding agents often:

• search too broadly
• read too many files
• waste expensive context on low-value text
• take extra turns to recover the right implementation context

local-search pushes that work down to local infrastructure:

• exact search with local ripgrep
• semantic retrieval with local embeddings
• local reranking
• compact span selection and context packing
• MCP tools and resources that agents can call directly

The goal is not "more tools". The goal is better agent economics:

• preserve task success
• reduce wasted token budget
• reduce unnecessary turns
• improve time-to-context

Measured Impact

Current benchmark evidence already shows practical value, but the gain pattern is agent-specific.

| Agent | Sample | Success Rate | Main Measured Gain | | --- | --- | --- | --- | | Claude | 4 tasks, baseline vs local-search | 4/4 -> 4/4 | cost -31.92%, turns -33.33%, latency -15.59% | | Codex | 4 tasks, baseline vs local-search | 4/4 -> 4/4 | token -21.94%, latency -3.76% |

Interpretation:

• for Claude, the strongest current value signal is success rate + cost + latency + turn count
• for Codex, the strongest current value signal is success rate + latency + token
• the exact gain depends on the agent and provider route; do not force one metric across every client

So the public claim should be:

• local-search already shows practical, measurable efficiency wins in controlled agent benchmarks
• a typical gain range today is on the order of 15%~30%, but the metric that moves most depends on the agent

How It Works

The design is intentionally simple:

1. use small local resources to build and query a local index
2. retrieve and rerank candidate files or spans before the agent reads them
3. send the remote model only the most relevant context

That shifts cost away from repeated remote context waste and toward a lightweight local retrieval layer.

Current Positioning

• alpha / 0.1.x
• Windows-first
• built for Codex, Claude Code, and MCP-oriented coding workflows
• optimized for local llama-server deployment

What You Get

• local exact search that is fast enough to replace broad blind file scanning
• semantic retrieval and reranking before the agent spends remote context
• compact file/span packaging so the model reads less but sees better context
• a single cpx entrypoint for startup, reindex, MCP registration, and session resume
• stable MCP resources and tools that fit real coding-agent workflows

Included MCP Tools

• code_exact_search
• symbol_search
• code_semantic_search
• code_context_pack
• kb_search
• doc_answer_context
• file_outline
• symbol_context
• change_context
• dependency_overview
• repo_overview
• open_spans
• index_status
• reindex

Current Status

As of 2026-05-09:

• embedding and reranking are served locally through llama-server
• cpx defaults to Codex and resumes the latest session for the current workspace
• cpx -Claude resumes the latest Claude session for the current workspace
• doctor verifies model health and MCP registration
• repo://overview, repo://dependency-summary, and repo://changes are available as stable MCP resources
• the repo includes an automated benchmark harness for baseline x local-search x Codex x Claude

The current strongest controlled benchmark evidence comes from Claude + Xiaomi Mimo 2.5 Pro, plus an earlier verified compatible Codex route.

Good Fit

• medium or large repositories
• workflows that frequently resume prior context
• projects that need both code and knowledge retrieval
• daily Codex / Claude Code usage

Not A Good Fit

• very small repositories
• workflows with little need for semantic retrieval
• users unwilling to maintain local models
• users expecting cross-platform zero-config setup

Quick Start

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

Set model paths:

$env:LOCAL_SEARCH_LLAMA_SERVER="D:\path\to\llama-server.exe"
$env:LOCAL_SEARCH_EMBED_GGUF="D:\models\bge-base-zh.f16.gguf"
$env:LOCAL_SEARCH_RERANK_GGUF="D:\models\bge-reranker-v2-m3-Q8_0.gguf"

Then run a minimal smoke test:

python -m local_mcp_search.cli reindex --mode auto
python -m local_mcp_search.cli status
python -m local_mcp_search.cli doctor
codex mcp get local-search --json
claude mcp get local-search

Unified launcher entrypoint:

cpx
cpx -Claude

Local Models

The default setup expects local llama-server and launches two services through the Python launcher:

• embedding: bge-base-zh
• reranker: bge-reranker-v2-m3

The launcher reads model paths from environment variables first. If they are not configured, it uses:

• llama-server as the executable name
• empty GGUF paths, which causes startup to fail explicitly instead of silently falling back to a machine-specific path

Private local fallback config is supported and should not be committed:

• workspace-level: /.local-search.env
• user-level: %USERPROFILE%/.local-mcp-search.env

Resolution order:

• CLI arguments
• environment variables
• workspace private config
• user private config
• safe defaults

Recommended environment setup:

$env:LOCAL_SEARCH_LLAMA_SERVER="D:\path\to\llama-server.exe"
$env:LOCAL_SEARCH_EMBED_GGUF="D:\models\bge-base-zh.f16.gguf"
$env:LOCAL_SEARCH_RERANK_GGUF="D:\models\bge-reranker-v2-m3-Q8_0.gguf"

Or put the same values in a private dotenv file:

LOCAL_SEARCH_LLAMA_SERVER=D:\path\to\llama-server.exe
LOCAL_SEARCH_EMBED_GGUF=D:\models\bge-base-zh.f16.gguf
LOCAL_SEARCH_RERANK_GGUF=D:\models\bge-reranker-v2-m3-Q8_0.gguf

Default ports:

embedding port: 8887
reranker port: 8888

The launcher probes ports first:

• if a healthy service is already running, it is reused
• if the port is occupied but the endpoint is unhealthy, startup fails loudly
• if no service is running, local llama-server is started automatically

Logs are written to:

%TEMP%\llama-logs\

Environment Variables

In most cases you do not need to export embedding or reranker variables manually; the launcher injects them.

Project-specific search and indexing config can live at the workspace root as .local-search.json. See [.local-search.example.json](/D:/traeprj/mcpsd/.local-search.example.json:1).

If you want to run python -m local_mcp_search directly, you need at least:

$env:MCP_SEARCH_WORKSPACE_ROOT="D:\your_repo"
$env:EMBEDDING_BASE_URL="http://127.0.0.1:8887/v1"
$env:EMBEDDING_MODEL="bge-base-zh"
$env:EMBEDDING_API_KEY=""
$env:MCP_SEARCH_RERANKER_ENABLED="true"
$env:RERANKER_BASE_URL="http://127.0.0.1:8888"
$env:RERANKER_MODEL="bge-reranker-v2-m3"
$env:RERANKER_API_KEY=""

Common optional variables:

$env:MCP_SEARCH_INDEX_DIR="D:\your_repo\.mcp-index"
$env:MCP_SEARCH_MAX_FILE_BYTES="300000"
$env:MCP_SEARCH_AUTO_REINDEX="false"
$env:MCP_SEARCH_AUTO_REINDEX_INTERVAL_SECONDS="5"
$env:MCP_SEARCH_RERANKER_CANDIDATE_MULTIPLIER="6"
$env:MCP_SEARCH_RERANKER_MAX_CANDIDATES="80"
$env:MCP_SEARCH_RERANKER_CACHE_ENABLED="true"
$env:MCP_SEARCH_RERANKER_CACHE_MAX_ENTRIES="5000"
$env:MCP_SEARCH_CONTEXT_PACK_MAX_CHARS="20000"
$env:MCP_SEARCH_QUERY_DEBUG="false"
$env:EMBEDDING_TIMEOUT_SECONDS="10"
$env:RERANKER_TIMEOUT_SECONDS="30"
$env:MCP_SEARCH_CODE_CHUNK_LINES="120"
$env:MCP_SEARCH_KB_CHUNK_CHARS="1600"

Notes:

• the default workspace root is the current directory; if the current directory is inside a git repository, it is promoted to the git root
• the default index directory is \.mcp-index
• project-level .local-search.json can override part of the indexing and retrieval behavior
• reindex uses batch embedding requests to avoid oversized single requests
• if you switch embedding models or dimensions, run reindex full
• with MCP_SEARCH_QUERY_DEBUG=true, code_exact_search, code_semantic_search, kb_search, and code_context_pack include an extra debug field in their JSON payload
• if model paths are missing, launcher startup fails explicitly instead of falling back to the author's machine-specific paths

Currently supported .local-search.json keys:

• ignore_dirs
• doc_dirs
• max_file_bytes
• languages

Example:

{
  "ignore_dirs": [".openhands", "vendor", "tmp"],
  "doc_dirs": ["docs", "notes", "runbooks"],
  "max_file_bytes": 200000,
  "languages": ["python", "typescript", "javascript"]
}

CLI

Reindex:

python -m local_mcp_search.cli reindex --mode auto

Force a full rebuild:

python -m local_mcp_search.cli reindex --mode full

Incremental only:

python -m local_mcp_search.cli reindex --mode incremental

Status:

python -m local_mcp_search.cli status

Build a compact context pack:

python -m local_mcp_search.cli context-pack "authentication-related implementation" --max-results 6 --max-chars 12000

Enable query debug output:

$env:MCP_SEARCH_QUERY_DEBUG="true"
python -m local_mcp_search.cli context-pack "authentication-related implementation" --max-results 6 --max-chars 12000

Start The MCP Server Directly

If you already prepared the required environment variables:

python -m local_mcp_search

The more common entrypoint is the launcher:

python -m local_mcp_search.launcher

It will:

1. ensure local embedding and reranker services are available
2. inject workspace-specific environment variables
3. run reindex
4. refresh the local-search MCP registration
5. launch Codex by default and resume the latest session

cpx Unified Entry Point

[cpx.ps1](/D:/traeprj/mcpsd/cpx.ps1:1) is the PowerShell wrapper. By default it is equivalent to:

python -m local_mcp_search.launcher --client codex

Running:

cpx

automatically:

1. resolves the target workspace
2. starts or reuses local llama services
3. refreshes the index
4. registers local-search
5. launches Codex
6. resumes the latest workspace session, or starts a new one if none exists

If you want cpx available globally in PowerShell, add a thin wrapper to your profile:

function cpx {
    param(
        [Parameter(ValueFromRemainingArguments = $true)]
        [string[]]$Args
    )

    & "D:\trae_prj\mcp_sd\cpx.ps1" @Args
}

Common cpx Examples

Start in the current directory and resume the latest Codex session:

cpx

Explicitly start Codex:

cpx -Codex

Explicitly start Claude Code:

cpx -Claude

Specify a project root:

cpx -ProjectRoot D:\trae_prj\myagent -Codex

Resume the latest Claude session:

cpx -ProjectRoot D:\trae_prj\myagent -Claude

Ignore history and force a fresh session:

cpx -Codex -Fresh
cpx -Claude -Fresh

Interactively pick a session:

cpx -Codex -Pick
cpx -Claude -Pick

Fork the latest session:

cpx -Codex -Fork
cpx -Claude -Fork

Force full reindex:

cpx -Codex -ReindexMode full

Update MCP only and do not launch a client:

python -m local_mcp_search.launcher --client none

Disable reranking:

cpx -ProjectRoot D:\trae_prj\myagent -Claude -DisableReranker

Register Claude MCP at the same time:

cpx -ProjectRoot D:\trae_prj\myagent -Codex -RegisterClaude

Write project-level Claude .mcp.json:

cpx -ProjectRoot D:\trae_prj\myagent -WriteClaudeProjectConfig

MCP Registration

The launcher refreshes MCP configuration automatically.

Current Codex registration is equivalent to:

codex mcp add local-search -- C:\Program Files\Python311\python.exe D:\your_repo\.mcp-index\_mcp_server_wrapper.py

Current Claude Code registration is equivalent to:

claude mcp add local-search C:\Program Files\Python311\python.exe D:\your_repo\.mcp-index\_mcp_server_wrapper.py

The wrapper is written to:

\.mcp-index\_mcp_server_wrapper.py

It prepares:

• PYTHONPATH/src
• MCP_SEARCH_WORKSPACE_ROOT
• embedding and reranker endpoints

Verify MCP

Codex:

codex mcp list
codex mcp get local-search --json

Claude:

claude mcp list
claude mcp get local-search

You can also run a health check directly:

python -m local_mcp_search.cli status

Under normal conditions, index_status should show:

reranker_enabled: true
reranker_model: bge-reranker-v2-m3
embedding_model: bge-base-zh
health.status: healthy

If Codex or Claude Code still reports MCP startup failures, or tools such as change_context / repo://changes misbehave:

• first confirm that codex mcp get local-search --json / claude mcp get local-search points to the current workspace .mcp-index/_mcp_server_wrapper.py
• if the path is already correct but the session still uses an old connection, restart the client session
• then run python -m local_mcp_search.cli doctor and inspect codex_mcp_matches_workspace, embedding, and reranker status

How To Use It Inside Codex / Claude

Examples of direct prompts:

Use local-search to inspect the project structure first.

Call index_status and confirm reranker_enabled and reranker_model.

Use code_exact_search to find a concrete function name, then open the key spans.

Use code_context_pack to inspect authentication-related implementation, then continue from the returned spans.

Use kb_search to find deployment notes, then open the most relevant spans.

If the client prefers MCP resources, these stable resources are also available:

• repo://overview
• repo://dependency-summary
• repo://changes

Recommended Tool Order

• use repo_overview first for repository structure
• use symbol_search first for concrete symbols
• use code_exact_search first for concrete strings
• use code_semantic_search for similar logic or implementation patterns
• prefer code_context_pack for implementation or debugging work
• use file_outline before reading a file
• use open_spans for precise spans
• use symbol_context before editing a function or class
• use change_context for current worktree changes
• use dependency_overview for dependency and build configuration
• use index_status for index and backend health

change_context currently provides:

• change types such as added / modified / deleted / renamed / untracked
• grouping into docs / code / config / tests / high_attention
• risk levels based on file type and change scale
• git numstat summary

Benchmark

The repository includes an automated harness to compare baseline vs local-search on both Claude and Codex.

Current controlled results already show practical value:

| Agent | Sample | Success | Main Result | | --- | --- | --- | --- | | Claude | 4 tasks | 4/4 -> 4/4 | cost -31.92%, turns -33.33%, latency -15.59% | | Codex | 4 tasks | 4/4 -> 4/4 | token -21.94%, latency -3.76% |

That is the main benchmark takeaway:

• for Claude, the value is preserving success while reducing cost, time, and turn count
• for Codex, the clearest signal is token reduction with a modest latency win
• benchmark interpretation should stay agent-specific, rather than forcing one m

…

Source & license

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

• Author: etherled
• Source: etherled/local-mcp-search
• License: MIT

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