S3文档MCP服务器

![CI](https://github.com/yoanbernabeu/S3-Documentation-MCP-Server/actions/workflows/ci.yml) ![codecov](https://codecov.io/gh/yoanbernabeu/S3-Documentation-MCP-Server) ](https://github.com/yoanbernabeu/S3-Documentation-MCP-Server/actions/workflows/docker-build.yml) ](https://hub.docker.com/r/yoanbernabeu/s3-doc-mcp)

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

为简单而构建：

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

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

需求

嵌入提供者 （选择一个）：

- 奥拉玛 （建议本地/离线使用） nomic-embed-text 模型 - OpenAI 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发现和读取索引文件

运作原理

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

S3装载机：扫描S3存储桶以查找 .md 文件，下载其内容，并跟踪ETag以进行更改检测
同步服务：检测新的、修改的或删除的文件，并执行增量同步（无需不必要的重新处理）
向量存储:

- 将文档分割成块（默认情况下为1000个字符） - 使用您选择的提供程序生成嵌入： - 奥拉玛: nomic-embed-text （本地，免费） - 开放人工智能: text-embedding-3-small 或 text-embedding-3-large （云，高精度） - 使用索引向量 HNSWLib 用于快速相似性搜索

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请求、报告问题和为项目做出贡献的详细信息。

📝 许可证

麻省理工学院

👤 作者

尤安·伯纳乌

S3 Documentation MCP Server

快速接入

详细介绍