AI导哈

S3文档RAG服务器

一个轻量级的MCP服务器，为存储在S3上的Markdown文档提供检索增强生成（RAG）功能，支持本地Ollama或云端OpenAI嵌入。

  • by yoanbernabeu
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 yoanbernabeu/S3-Documentation-MCP-Server

使用说明

S3文档MCP服务器

轻量级 模型上下文协议（MCP） 该服务器通过存储在S3上的Markdown文档为您的LLM带来RAG（检索增强生成）功能。

为简单而构建：

  • 🪶 轻量级堆栈：没有严重的依赖关系或云服务
  • 🏠 灵活嵌入：从中选择 奥拉玛 （本地，免费）或 开放人工智能 （云，高精度）
  • 💾 基于文件的存储：矢量索引存储为简单文件（HNSWLib）
  • 🔌 S3兼容：适用于任何S3兼容存储（AWS、MinIO、Scaleway、Cloudflare R2…）

[！重要]
🚧 这个项目正在进行中。 API和行为可能随时发生变化，并且不能保证向后兼容性。 不适合生产。

需求

  • 嵌入提供者 （选择一个）：
  • Node.js>=18 （如果从源运行） 或 码头工人 （推荐）
  • S3兼容存储 （AWS S3、MinIO、Scaleway、Cloudflare R2等）

用例

  • 📚 产品文档：让Claude/Cursor/etc从您的文档中回答
  • 🏢 内部Wiki：人工智能驱动的公司知识搜索
  • 📖 API文件：帮助开发人员查找API信息
  • 🎓 教育内容：用课程材料建立人工智能导师

快速开始

使用Docker（推荐）

# 1. Prerequisites
# Install Ollama from https://ollama.ai
ollama pull nomic-embed-text

# 2. Configure
cp env.example .env  # Add your S3 credentials

# 3. Run
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. Prerequisites
# Install Ollama from https://ollama.ai
ollama pull nomic-embed-text

# 2. Install & Run
npm install
cp env.example .env  # Configure your S3 credentials
npm run build && npm start

# 3. For local development
npm run dev

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

连接到MCP客户端

服务器运行后，您需要配置MCP客户端以连接到它。

光标

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

{
  "mcpServers": {
    "doc": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:3000/mcp",
        "note": "S3 Documentation RAG Server"
    }
  }
}

克劳德桌面

编辑您的Claude Desktop配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "doc": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:3000/mcp",
        "note": "S3 Documentation RAG Server"
    }
  }
}

重新启动MCP客户端，您现在应该看到：

  • 3个MCP工具: search_documentation, refresh_index, get_full_document
  • MCP资源：可直接访问的索引文档文件的完整列表

💡 小贴士：如果使用Docker，请确保端口映射与您的配置匹配（默认值为 3000:3000)

特性

  • 🔌 通用S3：AWS S3、MinIO、Scaleway、DigitalOcean Spaces、Cloudflare R2、Wasabi。。。
  • 🧠 灵活嵌入:
    • 奥拉玛 (nomic嵌入文本)-本地、免费、离线
    • 开放人工智能 (text-embedding-3-small, text-embedding-3-large)-基于云、高精度、多语言
  • 🔄 智能同步：通过ETag比较进行增量更新+在空矢量存储上自动完全同步
  • ⚡ 快速搜索：具有余弦相似度的HNSWLib矢量索引
  • 🔐 可选身份验证：用于安全部署的API密钥身份验证
  • 🛠️ 3个MCP工具: search_documentation, refresh_index，以及 get_full_document
  • 📚 MCP资源：本机支持通过标准MCP资源API发现和读取索引文件

运作原理

服务器遵循一个简单的管道：

  1. S3装载机：扫描S3存储桶以查找 .md 文件，下载其内容，并跟踪ETag以进行更改检测
  2. 同步服务：检测新的、修改的或删除的文件，并执行增量同步（无需不必要的重新处理）
  3. 向量存储:
    • 将文档分割成块（默认情况下为1000个字符）
    • 使用您选择的提供程序生成嵌入：
      • 奥拉玛: nomic-embed-text （本地，免费）
      • 开放人工智能: 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 （Hierarchical Navigable Small World）是一个轻量级的内存中向量搜索库，非常适合此用例：

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

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

配置

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

cp env.example .env

基本变量

# S3 Configuration
S3_BUCKET_NAME=your-bucket-name           # Your S3 bucket name
S3_ACCESS_KEY_ID=your-access-key          # S3 access key
S3_SECRET_ACCESS_KEY=your-secret-key      # S3 secret key
S3_REGION=us-east-1                       # S3 region
S3_ENDPOINT=                              # Optional: for non-AWS S3 (MinIO, Scaleway, etc.)

# Embeddings Provider (choose one)
EMBEDDING_PROVIDER=ollama                 # ollama (default) or openai

# Option 1: Ollama (Local)
OLLAMA_BASE_URL=http://localhost:11434    # Ollama API endpoint
OLLAMA_EMBEDDING_MODEL=nomic-embed-text   # Ollama embedding model

# Option 2: OpenAI (Cloud) - Only if EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=                           # Your OpenAI API key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # or text-embedding-3-large

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

嵌入提供者

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

🏠 Ollama（本地）-默认

赞成的意见：

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

欺骗：

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

设置：

# Install Ollama from https://ollama.ai
ollama pull nomic-embed-text

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

☁️ OpenAI（云）

赞成的意见：

  • ✅ 高精度：最先进的嵌入技术
  • ✅ 多语言：对20多种语言的出色支持
  • ✅ 没有本地资源：完全在云中运行
  • ✅ 减少延迟：API快速响应

欺骗：

  • ⚠️ 需要API密钥和信用
  • ⚠️ 发送到OpenAI服务器的数据
  • ⚠️ 每个代币的成本（非常实惠：约0.00002/K代币 text-embedding-3-small)

设置：

# Get an API key from https://platform.openai.com/api-keys

# Configure
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...your-key...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # or text-embedding-3-large

型号比较：

型号 尺寸 性能 成本 最适合
text-embedding-3-small 1536 高 低 通用，对成本敏感
text-embedding-3-large 3072 较高 中等 最高精度，多语言

💡 小贴士：从以下内容开始 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 authentication
ENABLE_AUTH=true

# Set your API key
MCP_API_KEY=your-secret-key-here

启用身份验证时：

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

使用示例：

# With Authorization header (recommended)
curl -H "Authorization: Bearer your-secret-key" http://localhost:3000/mcp

# With query parameter
curl "http://localhost:3000/mcp?api_key=your-secret-key"

带有API密钥的MCP客户端配置：

{
  "mcpServers": {
    "doc": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      },
      "note": "S3 Documentation RAG Server with authentication"
    }
  }
}

💡 最佳实践：

  • 保持身份验证 残疾的 促进地方发展
  • 启用 它适用于共享网络或远程部署
  • 使用强的、随机生成的密钥（例如。， openssl rand -hex 32)
  • 这 /health 端点始终可以访问，无需进行身份验证即可进行监控

MCP工具

search_documentation

{
  "query": "How to configure S3?",
  "max_results": 4
}

返回具有相似性得分和来源的相关文档块。

refresh_index

{
  "force": false  // default: incremental sync (recommended)
}

将文档索引与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资源

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

  • resources/list：列出所有带有元数据的索引Markdown文件（名称、URI、大小、块、最后修改时间）
  • resources/read：通过URI读取特定文件的完整内容（例如。， s3doc://docs/authentication.md)

使用案例： 当用户询问“你有什么文件？”或“显示文件X”时，LLM可以直接浏览和访问文件，而无需语义搜索。

🤝 贡献

欢迎投稿！请阅读我们的 贡献指南 有关如何提交pull请求、报告问题和为项目做出贡献的详细信息。

📝 许可证

麻省理工学院

👤 作者

尤安·伯纳乌

相关 MCP