项目简介

S3 文档 MCP 服务器是一个后端应用，它实现了 Model Context Protocol (MCP)，旨在帮助大型语言模型（LLM）从存储在S3兼容对象存储中的Markdown文档中获取上下文信息。通过集成本地的Ollama嵌入模型和HNSWLib向量存储，它为您的LLM应用提供了高效的检索增强生成（RAG）功能，支持智能搜索、文档同步和全文检索等操作，而无需依赖昂贵的云API。

主要功能点

S3兼容性： 支持AWS S3、MinIO、Scaleway、Cloudflare R2等任何S3兼容存储服务。
本地RAG： 利用本地运行的Ollama模型（如'nomic-embed-text'）生成嵌入向量，实现无需API费用的检索增强。
智能同步： 通过ETag比较，自动检测S3中文档的增、删、改，并进行增量更新，避免重复处理。
快速搜索： 使用HNSWLib向量索引库，提供毫秒级的近似最近邻搜索，支持语义搜索。
MCP 工具： 提供'search_documentation'、'refresh_index'和'get_full_document'三个MCP工具，供LLM客户端调用，实现文档搜索、索引刷新和全文获取。

安装步骤

在运行服务器之前，请确保您的系统满足以下条件：

安装并运行 Ollama：
- 访问 Ollama 官方网站下载并安装。
- 安装完成后，拉取嵌入模型：'ollama pull nomic-embed-text'

配置环境：

从项目根目录复制 '.env.example' 文件并重命名为 '.env'。

编辑 '.env' 文件，填入您的S3存储凭据和其他配置信息，例如：

S3_BUCKET_NAME=您的S3存储桶名称
S3_ACCESS_KEY_ID=您的S3访问密钥ID
S3_SECRET_ACCESS_KEY=您的S3秘密访问密钥
S3_REGION=您的S3存储桶区域，例如 us-east-1
# OLLAMA_BASE_URL 默认是 http://localhost:11434
# 如果通过 Docker 运行，为了让容器访问宿主机的 Ollama 服务，需要将其配置为 http://host.docker.internal:11434
# 其他RAG参数、同步模式、分块大小等可在 .env 文件中详细配置

运行服务器（推荐使用 Docker）：

确保 Docker 已安装并运行。

执行以下命令：

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'

运行服务器（从源代码）：
- 确保 Node.js (版本 >= 18) 已安装。
- 在项目根目录执行：
```
npm install
npm run build && npm start
```
- 服务器将在 'http://localhost:3000' 端口运行。

服务器配置 (MCP 客户端用)

MCP服务器启动后，您的MCP客户端需要知道如何连接它。以下是配置MCP客户端连接此服务器所需的信息。这些信息通常以JSON格式添加到客户端的配置文件中，例如Cursor的'~/.cursor/mcp.json'或Claude Desktop的'~/Library/Application Support/Claude/claude_desktop_config.json'。

MCP客户端配置示例 (JSON 格式，请根据您的客户端实际情况修改)

{
  "mcpServers": {
    "s3_doc_rag": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp",
      "note": "连接到本地运行的S3文档RAG服务器",
      "server_capabilities": {
        "tools": [
          {
            "name": "search_documentation",
            "description": "语义搜索S3文档，查找最相关的段落。",
            "inputSchema": {
              "type": "object",
              "properties": {
                "query": { "type": "string", "description": "要查询的问题或搜索词" },
                "max_results": { "type": "number", "description": "最大结果数量 (默认: 4)" }
              },
              "required": ["query"],
              "additionalProperties": false
            },
            "outputSchema": {
              "type": "object",
              "properties": {
                "results": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "content": { "type": "string", "description": "文档分块内容" },
                      "source": { "type": "string", "description": "S3文档键，例如 doc1.md" },
                      "score": { "type": "number", "description": "相关性得分 (0-1)" },
                      "chunk_info": { "type": "string", "description": "分块信息，例如 Chunk 1/2" }
                    },
                    "required": ["content", "source", "score", "chunk_info"],
                    "additionalProperties": false
                  }
                },
                "context": { "type": "string", "description": "为LLM提供的格式化上下文，包含多个搜索结果" },
                "total_results": { "type": "number", "description": "返回的总结果数量" }
              },
              "required": ["results", "context", "total_results"],
              "additionalProperties": false
            }
          },
          {
            "name": "refresh_index",
            "description": "刷新文档索引，与S3同步文件。自动检测新增、修改和删除的文件。",
            "inputSchema": {
              "type": "object",
              "properties": {
                "force": { "type": "boolean", "description": "强制进行完整重新索引 (默认: false)" }
              },
              "additionalProperties": false
            },
            "outputSchema": {
              "type": "object",
              "properties": {
                "success": { "type": "boolean", "description": "操作是否成功" },
                "message": { "type": "string", "description": "操作结果消息" },
                "metrics": {
                  "type": "object",
                  "properties": {
                    "duration_seconds": { "type": "number", "description": "同步持续时间（秒）" },
                    "documents_scanned": { "type": "number", "description": "扫描的文档总数" },
                    "documents_added": { "type": "number", "description": "新增的文档数量" },
                    "documents_modified": { "type": "number", "description": "修改的文档数量" },
                    "documents_deleted": { "type": "number", "description": "删除的文档数量" },
                    "documents_unchanged": { "type": "number", "description": "未更改的文档数量" },
                    "errors_count": { "type": "number", "description": "同步过程中发生的错误数量" }
                  },
                  "required": ["duration_seconds", "documents_scanned", "documents_added", "documents_modified", "documents_deleted", "documents_unchanged", "errors_count"],
                  "additionalProperties": false
                }
              },
              "required": ["success", "message", "metrics"],
              "additionalProperties": false
            }
          },
          {
            "name": "get_full_document",
            "description": "从S3检索Markdown文件的完整内容及其元数据（大小、最后修改日期、ETag、分块计数）。",
            "inputSchema": {
              "type": "object",
              "properties": {
                "s3_key": { "type": "string", "description": "S3文档键 (例如: \"docs/authentification_magique_symfony.md\")" }
              },
              "required": ["s3_key"],
              "additionalProperties": false
            },
            "outputSchema": {
              "type": "object",
              "properties": {
                "s3_key": { "type": "string", "description": "S3文档键" },
                "content": { "type": "string", "description": "完整的Markdown文档内容" },
                "metadata": {
                  "type": "object",
                  "properties": {
                    "size_bytes": { "type": "number", "description": "文档大小（字节）" },
                    "last_modified": { "type": "string", "description": "最后修改日期 (ISO 8601 格式)" },
                    "etag": { "type": "string", "description": "S3的ETag" },
                    "chunk_count": { "type": "number", "description": "文档在向量存储中的分块数量 (如果已索引)" }
                  },
                  "required": ["size_bytes", "last_modified", "etag"],
                  "additionalProperties": false
                }
              },
              "required": ["s3_key", "content", "metadata"],
              "additionalProperties": false
            }
          }
        ]
      }
    }
  }
}

请将上述JSON配置添加到您的MCP客户端的配置文件中，然后重启客户端。您将能够在LLM客户端中看到并调用'search_documentation'、'refresh_index'和'get_full_document'这些工具。

基本使用方法

启动服务器： 按照上述安装步骤，使用Docker或从源代码运行服务器。
配置MCP客户端： 将提供的MCP服务器配置信息添加到您的LLM客户端（如Cursor, Claude Desktop）。
调用工具： 在您的LLM客户端中，当您与LLM交互时，LLM将能够识别并自动调用这些工具，例如：
- 搜索文档： 当您提出与文档内容相关的问题时，LLM可能会自动调用'search_documentation'工具来查找答案。
  - LLM提示示例：“请帮我从文档中查找如何配置S3？”
- 刷新索引： 当您需要更新文档内容或S3中的文档发生变化时，可以手动调用'refresh_index'工具。
  - LLM提示示例：“刷新文档索引。” 或 “进行一次完整索引刷新。”
- 获取完整文档： 如果搜索结果指向某个文档，您想查看其完整内容，LLM可能会调用'get_full_document'。
  - LLM提示示例：“获取'docs/user_guide.md'的完整内容。”

关键词

信息