STARWARCLOUD STARWAR.AI
返回市场
文档存储MCP服务器

文档存储MCP服务器

作者：yoanbernabeu6 星标更新：2025-10-31
安装使用来源：spider==github.com

项目介绍

技术文档摘要

S3 文档 MCP 服务器

CI codecov Build and Push Docker Image Docker Hub

一个轻量级的 模型上下文协议（MCP） 服务器，它为存储在 S3 上的 Markdown 文档提供了 RAG（检索增强生成）功能。

简单构建：

  • 🪶 轻量级堆栈：没有重型依赖或云服务
  • 🏠 灵活嵌入：选择 Ollama（本地，免费）或 OpenAI（云端，高精度）
  • 💾 基于文件的存储：向量索引以简单的文件形式存储（HNSWLib）
  • 🔌 兼容 S3：与任何兼容 S3 的存储（AWS、MinIO、Scaleway、Cloudflare R2 等）工作

[!IMPORTANT] 🚧 本项目正在进行中。 API 和行为可能会随时更改，并且不保证向后兼容性。 不适合生产环境。

要求

  • 嵌入提供者（选择一个）：
    • Ollama（推荐用于本地/离线使用），使用 nomic-embed-text 模型
    • OpenAI API 密钥（用于基于云的嵌入）
  • Node.js >= 18（如果从源代码运行）或 Docker（推荐）
  • 兼容 S3 的存储（AWS S3、MinIO、Scaleway、Cloudflare R2 等）

使用案例

  • 📚 产品文档：让 Claude/Cursor 等从您的文档中回答问题
  • 🏢 内部维基：AI 驱动的公司知识搜索
  • 📖 API 文档：帮助开发者查找 API 信息
  • 🎓 教育内容：用课程材料构建 AI 辅导员

快速开始

使用 Docker（推荐）

# 1. 先决条件
# 从 https://ollama.ai 安装 Ollama
ollama pull nomic-embed-text

# 2. 配置
cp env.example .env  # 添加您的 S3 凭证

# 3. 运行
docker run -d \
  --name s3-doc-mcp \
  -p 3000:3000 \
  --env-file .env \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v $(pwd)/data:/app/data \
  yoanbernabeu/s3-doc-mcp:latest

或者使用 Docker Compose（本地构建）：

docker compose up -d

从源代码

# 1. 先决条件
# 从 https://ollama.ai 安装 Ollama
ollama pull nomic-embed-text

# 2. 安装并运行
npm install
cp env.example .env  # 配置您的 S3 凭证
npm run build && npm start

# 3. 本地开发
npm run dev

您的 MCP 服务器现在正在 http://localhost:3000 运行。

连接到 MCP 客户端

一旦您的服务器运行起来，您需要配置您的 MCP 客户端以连接到它。

Cursor

编辑您的 ~/.cursor/mcp.json 文件并添加：

{
  "mcpServers": {
    "doc": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:3000/mcp",
        "note": "S3 文档 RAG 服务器"
    }
  }
}

Claude Desktop

编辑您的 Claude Desktop 配置文件：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "doc": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:3000/mcp",
        "note": "S3 文档 RAG 服务器"
    }
  }
}

重启您的 MCP 客户端，您应该能看到：

  • 3 个 MCP 工具：search_documentation，refresh_index，get_full_document
  • MCP 资源：完整的已索引文档列表及其直接访问

💡 提示：如果使用 Docker，请确保端口映射匹配您的配置（默认是 3000:3000）

功能

  • 🔌 通用 S3：AWS S3、MinIO、Scaleway、DigitalOcean Spaces、Cloudflare R2、Wasabi 等
  • 🧠 灵活嵌入：
    • Ollama（nomic-embed-text）- 本地、免费、离线可用
    • OpenAI（text-embedding-3-small，text-embedding-3-large）- 云端、高精度、多语言
  • 🔄 智能同步：通过 ETag 对比进行增量更新 + 在空向量存储时自动全量同步
  • ⚡ 快速搜索：使用 HNSWLib 向量索引和余弦相似度
  • 🔐 可选认证：API 密钥认证以实现安全部署
  • 🛠️ 3 个 MCP 工具：search_documentation，refresh_index 和 get_full_document
  • 📚 MCP 资源：原生支持通过标准 MCP 资源 API 发现和阅读已索引文件

工作原理

服务器遵循一个简单的流水线：

  1. S3Loader：扫描您的 S3 存储桶中的 .md 文件，下载其内容，并跟踪 ETags 以检测变化
  2. SyncService：检测新文件、修改过的文件或删除的文件，并执行增量同步（无不必要的重新处理）
  3. VectorStore：
    • 将文档分割成块（默认 1000 字符）
    • 使用您选择的提供商生成嵌入：
      • Ollama：nomic-embed-text（本地、免费）
      • OpenAI：text-embedding-3-small 或 text-embedding-3-large（云端、高精度）
    • 使用 HNSWLib 索引向量以实现快速相似度搜索
  4. MCP 服务器：通过 HTTP 暴露工具和资源：
    • 工具：search_documentation，refresh_index，get_full_document 用于语义搜索和操作
    • 资源：resources/list，resources/read 用于文件发现和直接访问

什么是 HNSWLib？

HNSWLib（分层可导航的小世界）是一个轻量级的内存向量搜索库，非常适合这个用例：

  • ⚡ 快速：毫秒级近似最近邻搜索
  • 💾 简单：将索引存储为本地文件（无需数据库）
  • 🪶 高效：低内存占用，适合个人/小团队文档
  • 🎯 准确：使用余弦相似度进行语义搜索时具有高召回率

它是 RAG 应用程序之间简单性和性能的最佳平衡点。

配置

复制 env.example 到 .env 并配置您的环境变量：

cp env.example .env

必要变量

# S3 配置
S3_BUCKET_NAME=your-bucket-name           # 您的 S3 存储桶名称
S3_ACCESS_KEY_ID=your-access-key          # S3 访问密钥
S3_SECRET_ACCESS_KEY=your-secret-key      # S3 秘密密钥
S3_REGION=us-east-1                       # S3 区域
S3_ENDPOINT=                              # 可选：非 AWS S3（MinIO、Scaleway 等）

# 嵌入提供者（选择一个）
EMBEDDING_PROVIDER=ollama                 # ollama（默认）或 openai

# 选项 1：Ollama（本地）
OLLAMA_BASE_URL=http://localhost:11434    # Ollama API 端点
OLLAMA_EMBEDDING_MODEL=nomic-embed-text   # Ollama 嵌入模型

# 选项  2：OpenAI（云端）- 仅当 EMBEDDING_PROVIDER=openai 时
OPENAI_API_KEY=                           # 您的 OpenAI API 密钥
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # 或 text-embedding-3-large

查看 env.example 以获取所有可用选项和详细文档（RAG 参数、同步模式、块大小等）。

嵌入提供者

服务器支持两个嵌入提供者：

🏠 Ollama（本地）- 默认

优点：

  • ✅ 免费：无 API 成本，无限使用
  • ✅ 私有：所有数据都留在您的机器上
  • ✅ 离线：无需互联网连接即可工作
  • ✅ 快速：直接本地 API 调用

缺点：

  • ⚠️ 需要安装 Ollama 并下载模型
  • ⚠️ 使用本地 CPU/GPU 资源

设置：

# 从 https://ollama.ai 安装 Ollama
ollama pull nomic-embed-text

# 配置
EMBEDDING_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

☁️ OpenAI（云端）

优点：

  • ✅ 高精度：最先进的嵌入
  • ✅ 多语言：支持 20 多种语言
  • ✅ 无需本地资源：完全在云端运行
  • ✅ 低延迟：快速 API 响应

缺点：

  • ⚠️ 需要 API 密钥和信用
  • ⚠️ 数据发送到 OpenAI 服务器
  • ⚠️ 按令牌收费（非常实惠：~$0.00002/1K 令牌对于 text-embedding-3-small）

设置：

# 从 https://platform.openai.com/api-keys 获取 API 密钥

# 配置
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...your-key...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # 或 text-embedding-3-large

模型比较：

模型维度性能成本最佳用途
text-embedding-3-small1536高低通用目的，成本敏感
text-embedding-3-large3072更高中等最大精度，多语言

💡 提示：大多数情况下从 text-embedding-3-small 开始。只有在需要绝对最佳精度或大量处理非英语内容时才切换到 text-embedding-3-large。

回退行为：

如果您设置了 EMBEDDING_PROVIDER=openai 但未提供有效的 OPENAI_API_KEY，服务器会自动回退到 Ollama（如果已配置）。这确保了即使配置不完整，服务器也能始终启动。

同步模式

服务器支持三种同步模式，通过 SYNC_MODE：

  • startup（默认）：在服务器启动时同步

    • ✅ 自动检测：如果向量存储为空，则自动执行全量同步
    • ✅ 否则执行增量同步（仅更改的文件）
    • ✅ 重启后不需要手动 refresh_index！

  • periodic：定期同步（SYNC_INTERVAL_MINUTES）

    • 自动执行增量同步

  • manual：无自动同步

    • 您必须手动调用 refresh_index 工具

💡 注意：服务器会自动检测向量存储是否为空（例如，在删除 ./data/ 文件夹或首次运行后），并触发全量同步。您不再需要在每次重启后手动运行 refresh_index！

🔐 安全与认证

API 密钥认证（可选）

默认情况下，服务器以 开放访问模式 运行，便于本地开发。对于共享或远程部署，您可以启用 API 密钥认证：

# 启用认证
ENABLE_AUTH=true

# 设置您的 API 密钥
MCP_API_KEY=your-secret-key-here

当启用认证时：

  • ✅ 所有端点（除了 /health）都需要有效的 API 密钥
  • ✅ API 密钥可以通过以下方式提供：
    • 授权头（推荐）：Authorization: Bearer your-secret-key
    • 查询参数：?api_key=your-secret-key
  • ✅ 无效或缺少的密钥返回 HTTP 401 未经授权

使用示例：

# 使用授权头（推荐）
curl -H "Authorization: Bearer your-secret-key" http://localhost:3000/mcp

# 使用查询参数
curl "http://localhost:3000/mcp?api_key=your-secret-key"

MCP 客户端配置带 API 密钥：

{
  "mcpServers": {
    "doc": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      },
      "note": "带认证的 S3 文档 RAG 服务器"
    }
  }
}

💡 最佳实践：

  • 本地开发时保持认证 禁用
  • 对于共享网络或远程部署 启用
  • 使用强随机生成的密钥（例如，openssl rand -hex 32）
  • /health 端点始终可以无认证访问，用于监控

MCP 工具

search_documentation

{
  "query": "如何配置 S3？",
  "max_results": 4
}

返回相关文档片段及其相似度分数和来源。

refresh_index

{
  "force": false  // 默认：增量同步（推荐）
}

将文档索引与 S3 同步，检测新文件、修改过的文件或删除的文件。

参数：

  • force（布尔值，可选，默认：false）
    • false：增量同步 - 只处理更改（快速、高效）✅
    • true：全量重新索引 - 重新处理所有文件（慢、昂贵）⚠️

⚠️ 重要：force 参数应仅在明确需要时设置为 true（例如，“强制重新索引”，“从零开始重建一切”）。全量重新索引是昂贵的：

  • 从 S3 下载所有文件
  • 重新生成所有嵌入
  • 重建整个向量存储

正常操作时，始终使用增量同步（默认行为）。

get_full_document

{
  "s3_key": "docs/authentification_magique_symfony.md"
}

从 S3 检索 Markdown 文件的完整内容及其元数据：

  • 完整的 S3 键：文档的 S3 标识符
  • 完整的 Markdown 内容：整个文档（不分块）
  • 元数据：字节大小、最后修改日期、ETag、分块数量（如果已索引）

使用场景：

  • 在通过 search_documentation 查找文档后查看完整文档
  • 导出文档供外部使用
  • 理解搜索结果的完整上下文
  • 在第三方集成中显示完整文档

重要说明：

  • 如果文档出现在搜索结果中但 get_full_document 返回“未找到”，这意味着该文件在被索引后已被从 S3 删除
  • 解决方案：运行 refresh_index 以使索引与当前 S3 状态同步
  • 该工具将提供一条有用的错误消息，指示何时需要同步

MCP 资源

除了三个工具外，服务器还实现了 MCP 资源，用于文件发现和直接访问：

  • resources/list：列出所有已索引的 Markdown 文件及其元数据（名称、URI、大小、分块数、最后修改时间）
  • **