MCP Document Search

MCP文档搜索服务器

一种模型上下文协议（MCP）服务器，使用分块嵌入和向量相似性搜索在文档中提供语义搜索。

注意： 这是由克劳德·科德建造的。

特性

• 语义搜索：使用自然语言查询搜索索引文档
• 多种来源：索引本地文件、URL或直接内容
• 向量搜索：使用OpenAI嵌入和SQLite以及SQLite-vec进行高效的相似性搜索
• 智能分块：通过单词边界检测和可配置的重叠对文本进行分块
• HTML支持：索引URL时自动从HTML页面中提取文本
• 四种工具: search, index, list，以及 delete 用于完整的文档管理

建筑

• 嵌入：OpenAI文本嵌入3-small（1536个维度）
• 矢量数据库：带SQLite-vec扩展名的SQLite
• 相似性：余弦相似性
• 组块：1000个字符，100个字符重叠（可配置），遵守单词边界

先决条件

1.OpenAI API密钥

您需要一个OpenAI API密钥：

export OPENAI_API_KEY="sk-..."

2.Go and CGO（从源头开始构建）

• 转到1.21或更高版本
• 启用CGO（SQLite和SQLite-vec需要）
• C编译器（gcc或clang）

备注：sqlite-vec是 静态链接 进入二进制文件，因此您不需要单独安装它！

安装

从源代码构建

# Clone the repository
git clone https://github.com/cmrigney/mcp-document-search.git
cd mcp-document-search

# Build
mkdir -p bin
CGO_ENABLED=1 go build -o bin/doc-search ./cmd/doc-search

# Run
export OPENAI_API_KEY="sk-..."
./bin/doc-search

快速开始任务

该项目包括一个任务文件，便于构建和测试。首先，安装 任务。然后使用以下命令：

# Build the binary
task build

# Run all tests
task test

# Test with MCP Inspector
task inspector

# See all available tasks
task --list

配置

服务器是通过环境变量配置的：

用法

使用克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "doc-search": {
      "command": "/path/to/mcp-document-search/bin/doc-search",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

工具

1.搜索

通过索引文档进行语义搜索。

论据：

• query （必填）：搜索查询
• top_k （可选）：要返回的结果数（默认值：5）
• min_score （可选）：最小相似性得分0-1（默认值：0.3）
• source_filter （可选）：筛选到特定源（文件路径或URL）

例子：

{
  "query": "How do I configure authentication?",
  "top_k": 3,
  "min_score": 0.3
}

2.指标

为文件、URL或内容建立索引以进行语义搜索。

参数 （只提供一个来源）：

• file_path （可选）：要索引的文件路径
• url （可选）：获取和索引的URL
• content + source （可选）：带有源标识符的直接内容
• reindex （可选）：如果已经索引，则强制重新索引（默认值：false）

示例：

索引文件：

{
  "file_path": "/path/to/document.txt"
}

索引URL：

{
  "url": "https://example.com/docs/guide.html"
}

索引直接内容：

{
  "content": "This is the content to index...",
  "source": "manual-entry-1"
}

3.列表

列出所有带有元数据的索引文档。

论据：

• source_type （可选）：按类型筛选：“file”或“url”（全部为空）

例子：

{
  "source_type": "url"
}

4.删除

从数据库中删除索引文档。

论据：

• source （必填）：要删除的源（文件路径或URL）

例子：

{
  "source": "/path/to/document.txt"
}

数据库模式

文件表

• id：自动递增主键
• source：文件路径或URL（唯一）
• source_type：“文件”、“网址”或“内容”
• indexed_at：索引时的时间戳
• content_size：总内容大小（字符）
• chunk_count：块数
• title：可选标题（从HTML中提取）

大块桌子

• id：自动递增主键
• document_id：文档的外键
• chunk_index：文档中的块索引
• content：块的文本内容
• start_offset：原始文档中的起始位置
• end_offset：原始文档中的结束位置
• embedding：1536维向量（6144字节）

发展

运行测试

# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run specific package tests
go test -v ./internal/chunker

项目结构

mcp-document-search/
├── cmd/doc-search/          # Main entry point
├── internal/
│   ├── chunker/            # Text chunking logic
│   ├── fetcher/            # URL content fetcher
│   ├── embeddings/         # OpenAI API client
│   ├── storage/            # SQLite + sqlite-vec
│   ├── search/             # Search orchestration
│   └── config/             # Configuration
└── pkg/server/             # MCP server implementation

故障排除

构建过程中的CGO错误

如果您看到与CGO相关的错误：

1. 确保 CGO_ENABLED=1
2. 安装C编译器（gcc或clang）
3. 在macOS上： xcode-select --install

API费率限制

如果你达到了OpenAI的速率限制：

• 客户端以指数回退方式自动重试
• 考虑减小块大小或以较小的批处理文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请打开问题或拉取请求。