Local Docs MCP Server

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

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 Sources

Shared Docs (~/.claude/commands/**/*.md): User commands and knowledge bases (configurable)
Project Docs ($CWD/docs/**/*.md): Project-specific documentation with configurable exclusions
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.

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

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?"

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

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.

MCP Servers