JinDaGe - local-docs-mcp MCP Details

article

README

🚀 Local Docs MCP Server

Local Docs MCP Server是一个实现了模型上下文协议（MCP）的服务器，用于本地文档访问。它能让Claude无缝访问来自多个来源的Markdown文档，为用户提供便捷的文档查询体验。

✨ 主要特性

多源文档支持：可从命令、项目文档和项目根目录访问文档。
智能搜索：采用模糊匹配，优先精确匹配和子串匹配。
YAML前置元数据支持：可添加可选元数据（描述、标签），增强搜索效果。
持续缓存：对文件列表进行缓存，文件更改时自动失效，速度提升约3000倍。
文件监控：文档文件更改时自动使缓存失效。
安全路径处理：防止目录遍历，验证路径有效性。
源前缀：可明确指定文档来源（例如 commands:file.md）。
大小限制：避免读取超过5MB的文件。

📚 详细文档

文档来源

共享文档 (~/.claude/commands/**/*.md)：用户命令和知识库（可配置）。
项目文档 ($CWD/docs/**/*.md)：特定项目的文档，可配置排除项。
项目根目录 ($CWD/*.md)：根级文档，如README.md（可选启用）。

YAML前置元数据支持

文档文件可选择包含YAML前置元数据，以提高搜索性能：

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

# Your Documentation Content

支持的字段：

description：用于提高搜索相关性的文本描述。
tags：用于分类的标签数组或逗号分隔列表。

搜索行为：

描述匹配使搜索得分增加0.5。
精确标签匹配使搜索得分增加0.3。
部分标签匹配使搜索得分增加0.15。
read_doc 输出会自动去除前置元数据。
list_all_docs 在文件元数据中包含描述和标签。

注意：前置元数据是可选的，纯Markdown文件无需它也能正常工作。

📦 安装指南

下载二进制文件

从发布页面下载最新版本。

使用Go安装

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

使用Homebrew（macOS）

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

从源代码构建

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

配置Claude

添加到 ~/.claude.json：

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

或者使用绝对路径：

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

重启Claude Code以加载服务器。

🔧 技术细节

命令行选项

# 自定义文档目录
local-docs-mcp --shared-docs-dir=~/.my-docs --docs-dir=documentation

# 启用根级Markdown扫描
local-docs-mcp --enable-root-docs

# 从项目文档扫描中排除目录
local-docs-mcp --exclude-dir=plans --exclude-dir=drafts

# 通过环境变量进行多个排除
EXCLUDE_DIRS=plans,drafts,archive local-docs-mcp

可用选项：

--shared-docs-dir - 共享文档目录（默认：~/.claude/commands）
--docs-dir - 项目文档目录（默认：docs）
--enable-root-docs - 扫描根级 *.md 文件（默认：禁用）
--exclude-dir - 从项目文档扫描中排除的目录（默认：plans）
--cache-ttl - 缓存生存时间（默认：1h）
--max-file-size - 要索引的最大文件大小（默认：5242880 - 5MB）
--dbg - 启用调试日志

缓存

文件列表缓存始终启用，以显著加快重复查询速度。缓存的生存时间（TTL）可以配置：

# 使用默认的1小时TTL
local-docs-mcp

# 自定义TTL
local-docs-mcp --cache-ttl=30m

# 通过环境变量设置
CACHE_TTL=2h local-docs-mcp

性能：缓存命中比文件系统扫描快约3000倍（66纳秒 vs 201微秒）。当文档文件更改时，缓存会自动失效，确保数据新鲜。

工作原理：

首次查询扫描文件系统并填充缓存。
后续查询直接从内存返回。
文件监控器检测到更改后，会在500毫秒内使缓存失效。
TTL提供安全回退机制（默认：1小时）。

💻 使用示例

配置完成后，Claude可以自然地查询文档：

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

可用工具

search_docs

通过模糊匹配按名称搜索文档文件。输入：{"query": "search-term"} 输出：前10个匹配文件及其得分

read_doc

读取特定的文档文件。输入：{"path": "file.md"} 或 {"path": "commands:action/commit.md"} 输出：包含元数据的文件内容

list_all_docs

列出所有来源的可用文档文件。输出：包含文件大小和来源信息的完整文件列表

🔒 安全保障

防止目录遍历
文件大小限制（5MB）
UTF-8验证
不跟随基础目录外的符号链接
拒绝绝对路径

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

local-docs-mcp