Local Docs MCP Server  

实现用于本地文档访问的模型上下文协议（MCP）服务器。提供Claude无缝访问来自多个来源的Markdown文档。

功能

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

文档来源

1. 共享文档 (~/.claude/commands/**/*.md)：用户命令和知识库（可配置）
2. 项目文档 ($CWD/docs/**/*.md)：特定项目的文档，可配置排除项
3. 项目根目录 ($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文件获取详细信息。