本地文档服务器
项目介绍
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: 强制执行Go代码的测试驱动开发方法，采用先测试的工作流程
tags: [测试, 开发, Go]
---
# 您的文档内容
支持字段：
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
性能：缓存命中比文件系统扫描快约3,000倍（66纳秒对201微秒）。当文档文件更改时，缓存会自动失效，确保数据新鲜。
如何工作：
- 第一次查询扫描文件系统并填充缓存
- 后续查询立即从内存返回
- 文件监视器检测更改并在500毫秒内使缓存失效
- TTL提供安全回退（默认：1小时）
使用
配置完成后，Claude可以自然查询文档：
- "显示routegroup的文档"
- "查找关于测试的文档"
- "列出所有可用命令"
- "go-architect命令里有什么？"
可用工具
search_docs
按名称模糊匹配搜索文档文件。
输入：{"query": "搜索词"}
输出：排名前十的匹配文件及其得分
read_doc
读取特定的文档文件。
输入：{"path": "file.md"} 或 {"path": "commands:action/commit.md"}
输出：文件内容及元数据
list_all_docs
列出所有来源的所有可用文档文件。
输出：完整的文件列表，包括大小和来源信息
安全
- 防止目录遍历
- 文件大小限制（5MB）
- UTF-8验证
- 不跟随基础目录外的符号链接
- 拒绝绝对路径
许可证
本项目根据MIT许可证授权 - 查看LICENSE文件获取详细信息。