docs_search MCP

docs_search MCP is a small Model Context Protocol server that lets an AI agent find the right project documentation before it edits code.

The repository contains two pieces:

• knowledge-server.mjs exposes MCP tools: docs_search and docs_reindex.

• scripts/ai/build-index.sh scans a project's docs/ folder and writes .semantic-index.json.

The important idea is simple: documentation stays inside each project, but the AI does not have to guess which markdown file to read. It asks docs_search with a symptom or task, the router selects relevant files from .semantic-index.json, and the agent reads only those files.

Why This Exists

Large projects collect many facts, fixes, design principles, and workflow notes. A normal README cannot carry all of that context, and asking an AI to read the whole docs/ folder wastes context.

This MCP creates a narrow lookup step:

1. A project stores docs in docs/knowledge/, docs/methodology/, docs/product/, and docs/meta/.

2. build-index.sh summarizes every markdown file into tags and user-visible symptoms.

3. .semantic-index.json becomes a compact routing table.

4. docs_search sends the developer request plus that index to Gemini or Claude.

5. The tool returns exact markdown files with absolute paths.

6. The AI reads those files before changing code.

Related MCP server: MCP Docs Provider

Project Documentation Layout

Recommended layout:

PROJECT_ROOT/
├── CLAUDE.md
├── docs/
│   ├── knowledge/
│   │   ├── fact-*.md
│   │   └── fix-*.md
│   ├── methodology/
│   │   └── *.md
│   ├── product/
│   │   └── *.md
│   ├── meta/
│   │   └── *.md
│   └── tmp/
└── scripts/
    └── ai/
        └── build-index.sh

docs/tmp/ and _intro.md files are skipped by the indexer.

Install

Clone this repository somewhere stable:

git clone https://github.com/RevinFedor/docs_search_mcp.git
cd docs_search_mcp
chmod +x knowledge-server.mjs scripts/ai/build-index.sh

Requirements:

• Node.js 18+;

• jq;

• Gemini API key for the default router and indexer;

• optional Claude CLI if you want provider="claude".

On macOS:

brew install jq

Add The Indexer To A Project

Copy the indexer into the project that has docs/:

mkdir -p /path/to/project/scripts/ai
cp scripts/ai/build-index.sh /path/to/project/scripts/ai/build-index.sh
chmod +x /path/to/project/scripts/ai/build-index.sh

Create or update the semantic index:

cd /path/to/project
export GEMINI_API_KEY="your_key"
bash scripts/ai/build-index.sh --gemini-write

The result is:

/path/to/project/.semantic-index.json

Commit .semantic-index.json when you want the same routing table available to every developer and AI session.

Register The MCP Server

Register globally for Claude Code:

claude mcp add docs-search \
  -s user \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  -- node /path/to/docs_search_mcp/knowledge-server.mjs

For one project, pin the default project directory:

claude mcp add docs-search \
  -s local \
  -e CLAUDE_PROJECT_DIR="/path/to/project" \
  -e GEMINI_API_KEY="$GEMINI_API_KEY" \
  -- node /path/to/docs_search_mcp/knowledge-server.mjs

You can still search any project from a tool call by passing projectPath.

Tools

docs_search

Searches the selected project index and returns markdown files to read.

Example request:

{
  "query": "fix stale loader state on mobile terminal project list",
  "projectPath": "/path/to/project"
}

Example result:

{
  "found": 3,
  "files": [
    {
      "path": "docs/knowledge/fact-mobile-web.md",
      "fullPath": "/path/to/project/docs/knowledge/fact-mobile-web.md"
    }
  ]
}

The agent should then read each fullPath before editing code.

docs_reindex

Runs the project's scripts/ai/build-index.sh and reloads .semantic-index.json.

Example:

{
  "projectPath": "/path/to/project",
  "provider": "gemini",
  "model": "gemini-3.5-flash",
  "parallel": 5
}

Use this after changing important documentation files.

Switching Models

Defaults:

• router provider: gemini;

• Gemini model: gemini-3.5-flash;

• Claude model: haiku.

Per-call override:

{
  "query": "timeline hover preview is clipped",
  "provider": "claude",
  "model": "haiku"
}

Environment defaults:

export KNOWLEDGE_ROUTER_PROVIDER=gemini
export KNOWLEDGE_INDEX_PROVIDER=gemini
export KNOWLEDGE_GEMINI_MODEL=gemini-3.5-flash
export KNOWLEDGE_CLAUDE_MODEL=haiku

If provider="claude" fails, the server falls back to Gemini when a Gemini key is available.

Global Cross-Project Docs

The server can merge a small global pattern library into every project search. By default it looks at:

~/Global-Templates/🧩 Code-Patterns/docs-projects/.semantic-index.json

Override it with:

export KNOWLEDGE_GLOBAL_DIR="/path/to/docs-projects"

Global entries are returned with docs-global/ prefixes. Keep this folder small and public-safe; it should contain reusable patterns, not private project notes.

Security

Do not publish private project docs by accident.

Safe to publish:

• this MCP server;

• the generic indexer;

• example .semantic-index.json shapes;

• public documentation written for reuse.

Do not publish:

• docs/knowledge/ from private projects;

• .env files;

• transcripts, logs, tokens, or local MCP configs;

• global documentation folders that include personal workflows or private prompts.

README Note For Projects

Add this note near the end of any repository that uses the MCP:

> ! Documentation is routed through `docs_search MCP`: agents call `docs_search` before complex work, receive the relevant files from `.semantic-index.json`, and read those files into context. Rebuild the index with `docs_reindex` or `bash scripts/ai/build-index.sh --gemini-write` after documentation changes.