Local Docs MCP

🚀 Local Docs MCP Server

Implementation of the Model Context Protocol (MCP) server for local documentation access. It provides Claude with seamless access to markdown documentation from multiple sources.

🚀 Quick Start

The Local Docs MCP Server is an implementation of the Model Context Protocol (MCP) server, enabling local access to documentation. It allows Claude to access markdown documentation from multiple sources effortlessly.

✨ Features

• Multi - source documentation: Access docs from commands, project docs, and project root.
• Smart search: Fuzzy matching with exact/substring match priority.
• YAML frontmatter support: Optional metadata for enhanced search (description, tags).
• Always - on caching: File list caching with automatic invalidation on changes (~3000x faster).
• File watching: Automatic cache invalidation when documentation files change.
• Safe path handling: Prevents directory traversal and validates paths.
• Source prefixes: Explicitly specify documentation source (e.g., commands:file.md).
• Size limits: Prevents reading files larger than 5MB.

📚 Documentation

Documentation Sources

1. Shared Docs (~/.claude/commands/**/*.md): User commands and knowledge bases (configurable).
2. Project Docs ($CWD/docs/**/*.md): Project - specific documentation with configurable exclusions.
3. Project Root ($CWD/*.md): Root - level docs like README.md (opt - in).

YAML Frontmatter Support

Documentation files can optionally include YAML frontmatter for enhanced searchability:

---
description: Enforce Test - Driven Development approach for Go code with test - first workflow
tags: [testing, development, go]
---

# Your Documentation Content

Supported fields:

• description: Text description used to boost search relevance.
• tags: Array or comma - separated list of tags for categorization.

Search behavior:

• Description matches add +0.5 to search score.
• Exact tag matches add +0.3 to search score.
• Partial tag matches add +0.15 to search score.
• Frontmatter is automatically stripped from read_doc output.
• list_all_docs includes description and tags in file metadata.

Note: Frontmatter is completely optional - plain markdown files work perfectly without it.

📦 Installation

Download Binary

Download the latest release from the releases page.

Using Go

go install github.com/umputun/local-docs-mcp/app@latest

Using Homebrew (macOS)

brew tap umputun/apps
brew install umputun/apps/local-docs-mcp

Build from Source

git clone https://github.com/umputun/local-docs-mcp.git
cd local-docs-mcp
make build
make install

Configure Claude

Add to ~/.claude.json:

{
  "mcpServers": {
    "local-docs": {
      "command": "local-docs-mcp"
    }
  }
}

Or use absolute path:

{
  "mcpServers": {
    "local-docs": {
      "command": "/path/to/local-docs-mcp"
    }
  }
}

Restart Claude Code to load the server.

📚 Documentation

Configuration

Command Line Options

# customize documentation directories
local-docs-mcp --shared-docs-dir=~/.my-docs --docs-dir=documentation

# enable root-level markdown scanning
local-docs-mcp --enable-root-docs

# exclude directories from project docs scan
local-docs-mcp --exclude-dir=plans --exclude-dir=drafts

# multiple exclusions via environment variable
EXCLUDE_DIRS=plans,drafts,archive local-docs-mcp

Available options:

• --shared-docs-dir - shared documentation directory (default: ~/.claude/commands).
• --docs-dir - project docs directory (default: docs).
• --enable-root-docs - scan root - level *.md files (default: disabled).
• --exclude-dir - directories to exclude from project docs scan (default: plans).
• --cache-ttl - cache time - to - live (default: 1h).
• --max-file-size - maximum file size in bytes to index (default: 5242880 - 5MB).
• --dbg - enable debug logging.

Caching

File list caching is always enabled for significantly faster repeated queries. The cache TTL can be configured:

# use default 1h TTL
local-docs-mcp

# custom TTL
local-docs-mcp --cache-ttl=30m

# via environment variable
CACHE_TTL=2h local-docs-mcp

Performance: Cache hits are ~3,000x faster than filesystem scans (66 nanoseconds vs 201 microseconds). The cache automatically invalidates when documentation files change, ensuring fresh data.

How it works:

• First query scans filesystem and populates cache.
• Subsequent queries return instantly from memory.
• File watcher detects changes and invalidates cache within 500ms.
• TTL provides safety fallback (default: 1 hour).

💻 Usage Examples

Basic Usage

Once configured, Claude can query documentation naturally:

• "Show me docs for routegroup"
• "Find documentation about testing"
• "List all available commands"
• "What's in the go - architect command?"

Advanced Usage

Available Tools

search_docs

Search for documentation files by name with fuzzy matching. Input: {"query": "search-term"} Output: Top 10 matching files with scores

read_doc

Read a specific documentation file. Input: {"path": "file.md"} or {"path": "commands:action/commit.md"} Output: File content with metadata

list_all_docs

List all available documentation files from all sources. Output: Complete file listing with sizes and source information

🔧 Technical Details

Security

• Path traversal prevention.
• File size limits (5MB).
• UTF - 8 validation.
• No symlink following outside base directories.
• Absolute path rejection.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.