mcpmydocs (Mattdennewitz)

mcpmydocs

  ](https://github.com/mattdennewitz/mcpmydocs/releases) 

Markdown文档的本地第一语义搜索引擎。对文档进行索引，使用ONNX模型生成嵌入，将它们存储在DuckDB中，并通过CLI或MCP服务器公开对Claude Code等AI代理的搜索。

目录

• 快速开始
• 特性
• 需求
• 安装
• 配置
• 用法
• 与Claude Code集成
• 运作原理
• 项目结构
• 发展
• 贡献
• 故障排除
• 许可证

快速开始

# Install mcpmydocs and models
curl -sSL https://raw.githubusercontent.com/mattdennewitz/mcpmydocs/main/install.sh | bash

# Install ONNX Runtime
brew install onnxruntime  # macOS
# Linux: see Installation section for instructions

# Index your documentation
mcpmydocs index ~/Documents/wiki

# Search
mcpmydocs search "how to configure authentication"

注： A. Brewfile 适用于从源代码构建的macOS用户--run brew bundle 安装所有依赖项。

特性

• 语义搜索 -按含义查找文档，而不仅仅是关键字
• 交叉编码器重新排序 -两阶段检索以提高相关性
• 本地优先 -所有处理都发生在您的计算机上，没有API调用
• 快速 -用于毫秒查询的具有HNSW矢量索引的DuckDB
• MCP服务器 -与Claude Code或其他MCP兼容的AI工具集成
• 增量索引 -仅重新索引已更改的文件

需求

• macOS苹果Silicon、Linux x64或Linux ARM64（预构建二进制文件）
• macOS英特尔（从源代码构建）
• ONNX运行库
• 嵌入模型文件

安装

快速安装（macOS苹果Silicon/Linux）

curl -sSL https://raw.githubusercontent.com/mattdennewitz/mcpmydocs/main/install.sh | bash

这将：

• 下载适用于您平台的最新版本
• 将二进制文件安装到 ~/.local/bin
• 将嵌入和重新链接模型下载到 ~/.local/share/mcpmydocs/models/

注： 您仍然需要安装ONNX Runtime（见下文）。

对于macOS Intel，请参阅 从源头构建.

手动安装

如果你有一个预构建的二进制文件，你需要手动安装依赖关系：

1.安装ONNX运行时

macOS（Homebrew）：

brew install onnxruntime

Linux（Ubuntu/Debian）：

# Download from https://github.com/microsoft/onnxruntime/releases
# Extract and copy libonnxruntime.so to /usr/local/lib/
sudo ldconfig

或者，将库放置在 lib/ 二进制文件旁边的目录，或设置 ONNX_LIBRARY_PATH 环境变量。

2.下载模型

下载模型文件并将其放置在 assets/models/ 二进制文件旁边的目录：

mkdir -p assets/models

# Download embedding model (~90MB)
curl -L -o assets/models/embed.onnx \
  "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx"

# Download tokenizer
curl -L -o assets/models/tokenizer.json \
  "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json"

# Download reranker model (~90MB, optional but recommended)
curl -L -o assets/models/rerank.onnx \
  "https://huggingface.co/cross-encoder/ms-marco-MiniLM-L-6-v2/resolve/main/onnx/model.onnx"

应用程序会自动在以下位置搜索模型：

1. ~/.local/share/mcpmydocs/models/ （安装脚本位置）
2. assets/models/ 相对于二进制
3. assets/models/ 在当前工作目录中

3.验证安装

./mcpmydocs --help

从源头构建

需要Go 1.24+和Homebrew（macOS）。

1.克隆和构建

git clone https://github.com/mattdennewitz/mcpmydocs.git
cd mcpmydocs
make all

这将：

• 通过Homebrew安装系统依赖项（DuckDB、ONNX Runtime）
• 下载Go模块
• 下载嵌入模型、重链模型和标记器
• 构建二进制文件 dist/mcpmydocs

2.验证安装

mcpmydocs --help

配置

数据库位置

数据库文件 mcpmydocs.db 默认情况下在当前工作目录中创建。使用 --db 标志以指定自定义路径：

mcpmydocs index ~/Documents/wiki --db ~/data/mcpmydocs.db
mcpmydocs search "query" --db ~/data/mcpmydocs.db

环境变量

用法

注： 以下示例假设 mcpmydocs 在你的路径。如果您是从源代码构建的，请使用 mcpmydocs 相反。

为目录建立索引

索引目录中的所有Markdown文件：

mcpmydocs index ~/Documents/wiki

输出示例：

Indexing directory: /home/user/docs
Database: /home/user/docs/mcpmydocs.db
[247/247] guides/advanced-configuration.md
Indexing complete!
  Indexed: 247 files
  Skipped: 0 unchanged files

重新运行该命令仅处理更改的文件：

Indexing complete!
  Indexed: 2 files
  Skipped: 245 unchanged files

从CLI搜索

mcpmydocs search "how to configure authentication"

示例输出（默认情况下启用重新分级）：

Found 5 results for: "how to configure authentication" (reranked)

─────────────────────────────────────────────────────────────
[1] # Authentication > ## OAuth Setup (relevance: 2.15)
    File: /home/user/docs/auth/oauth.md:15

    OAuth Setup

    To configure OAuth authentication, you'll need to:
    1. Register your application with the OAuth provider
    2. Set the callback URL to https://yourapp.com/auth/callback
    ...

─────────────────────────────────────────────────────────────
[2] # Security > ## API Keys (relevance: 1.82)
    File: /home/user/docs/security/api-keys.md:8

    API Keys

    API keys provide a simple authentication mechanism...

选项：

# Return more results
mcpmydocs search "database migrations" -n 10

# Disable reranking (faster, uses vector similarity only)
mcpmydocs search "quick lookup" --no-rerank

# Adjust candidate pool for reranking (default: 50)
mcpmydocs search "detailed query" --candidates 100

以MCP服务器运行

启动MCP服务器以与AI工具集成：

mcpmydocs run

服务器使用JSON-RPC 2.0（MCP协议）通过stdio进行通信。

与Claude Code集成

创建一个设置工作目录的包装器脚本，然后用Claude Code注册它：

# Create the script (adjust MCPMYDOCS_DIR to your install location)
MCPMYDOCS_DIR="$HOME/.local/share/mcpmydocs"

mkdir -p ~/bin
cat > ~/bin/mcpmydocs-server << EOF
#!/bin/bash
cd $MCPMYDOCS_DIR && mcpmydocs run
EOF

chmod +x ~/bin/mcpmydocs-server

# Add to Claude Code
claude mcp add --transport stdio mcpmydocs -- ~/bin/mcpmydocs-server

包装器脚本是必要的，因为MCP服务器需要从包含数据库和模型的目录中运行。

可用的MCP工具

连接后，Claude Code可以访问：

search

具有跨编码器重新排序的语义搜索。

list_documents

列出所有带有标题和路径的索引文档。没有参数。

Claude代码中的示例用法

让Claude Code搜索您的索引文档：

Search my docs for information about database migrations

克劳德将自动使用 search 工具并返回相关文档片段。

运作原理

1. 分块 -Markdown文件按标题结构分成块
2. 嵌入 -每个块通过以下方式转换为384维向量 全迷你LM-L6-v2
3. 存储 -矢量通过HNSW索引存储在DuckDB中 vss扩展
4. 搜索 -两阶段检索：

- 第一阶段（检索）：嵌入查询，并使用余弦相似度提取前N个候选项 - 第二阶段（重新排名）：考生使用以下方式重新评分 ms-marco-MiniLM-L-6-v2 提高相关性的交叉编码器

项目结构

mcpmydocs/
├── cmd/
│   ├── config.go     # CLI configuration
│   ├── index.go      # Index command
│   ├── run.go        # MCP server command
│   └── search.go     # Search command
├── internal/
│   ├── app/          # Application initialization
│   ├── chunker/      # Markdown chunking logic
│   ├── embedder/     # ONNX embedding generation
│   ├── logger/       # Logging utilities
│   ├── paths/        # Path resolution for models
│   ├── reranker/     # Cross-encoder reranking
│   ├── search/       # Unified search service
│   └── store/        # DuckDB storage layer
├── assets/
│   └── models/       # Downloaded ONNX models
├── Makefile
├── Brewfile
└── main.go

发展

# Install dependencies only
make deps

# Build only
make build

# Clean build artifacts and models
make clean

# Run tests
go test ./...

贡献

欢迎投稿！拜托：

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/my-feature)
3. 提交前运行测试(go test ./...)
4. 提交拉取请求

对于错误或功能请求，请 打开一个问题.

故障排除

“找不到数据库”错误

首先运行index命令：

mcpmydocs index /path/to/your/docs

搜索结果不佳

该搜索使用语义相似性和跨编码器重新排序。尝试：

• 更具描述性的查询（“如何设置OAuth”与“OAuth”）
• 检查文档是否已实际编入索引（使用 list_documents 通过MCP）
• 确保重新登录模型可用（检查日志中的“重新登录已启用”）

重新排序器未加载

如果搜索结果显示相似性百分比而不是相关性分数，则不会加载重新排序器：

• 确保 rerank.onnx 存在于 assets/models/ 或设置 MCPMYDOCS_RERANKER_PATH
• 检查日志中是否有“重新登录初始化失败”消息

MCP服务器未连接

1. 确保包装器脚本从包含以下内容的目录运行 mcpmydocs.db 以及模型
2. 检查克劳德代码日志： ~/.claude/logs/
3. 直接测试服务器： echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | mcpmydocs run

许可证

麻省理工学院