AI导哈

本地文档访问服务器

实现模型上下文协议（MCP）服务器，为Claude提供无缝访问多来源Markdown文档的功能，支持智能搜索、YAML前端元数据和高效缓存。

  • by umputun
  • Go
  • 本地部署
  • 21 星标
  • 更新于
在 GitHub 查看 umputun/local-docs-mcp

使用说明

本地文档MCP服务器  

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

特性

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

文档来源

  1. 共享文档 (~/.claude/commands/**/*.md)：用户命令和知识库（可配置）
  2. 项目文档 ($CWD/docs/**/*.md)：具有可配置排除项的项目特定文档
  3. 项目根 ($CWD/*.md)：根级文档，如README.md（选择加入）

YAML前端支持

文档文件可以选择包含YAML frontmatter以增强搜索能力：

---
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
  • Frontmatter将自动从中删除 read_doc 输出
  • list_all_docs 在文件元数据中包含描述和标签

备注：Frontmatter是完全可选的-没有它，普通的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以加载服务器。

配置

命令行选项

# 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

可用选项：

  • --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：

# use default 1h TTL
local-docs-mcp

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

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

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

运作原理:

  • 第一个查询扫描文件系统并填充缓存
  • 后续查询会立即从内存中返回
  • 文件监视器检测到更改并在500毫秒内使缓存无效
  • TTL提供安全回退（默认值：1小时）

用法

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

  • “显示路由组的文档”
  • “查找有关测试的文档”
  • “列出所有可用命令”
  • “go架构师命令中有什么？”

可用工具

search_docs

通过模糊匹配按名称搜索文档文件。

输入: {"query": "search-term"}

输出：得分最高的10个匹配文件

read_doc

阅读特定的文档文件。

输入: {"path": "file.md"} 或 {"path": "commands:action/commit.md"}

输出：包含元数据的文件内容

list_all_docs

列出所有来源的所有可用文档文件。

输出：完整的文件列表，包括大小和源信息

安全

  • 路径遍历预防
  • 文件大小限制（5MB）
  • UTF-8验证
  • 外部基本目录后没有符号链接
  • 绝对路径拒绝

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP