关键词

RAG系统混合搜索LLM工具上下文服务OpenSearch集成Claude Desktop集成

项目简介

RAGent MCP服务器是 RAGent 工具的一部分，它将RAGent的核心混合搜索功能（结合BM25关键词搜索和向量语义搜索）封装成符合Model Context Protocol (MCP) 标准的工具，提供给像Claude Desktop这样的LLM客户端使用。LLM客户端可以通过调用这些工具来获取上下文信息，从而增强其生成能力。

主要功能点

  • MCP协议兼容性: 完全遵循JSON-RPC 2.0协议和Model Context Protocol (MCP) SDK v0.4.0标准，确保与各种LLM客户端的无缝集成。
  • 混合搜索工具: 暴露 'ragent-hybrid_search' 工具，允许LLM客户端执行强大的文档搜索，结合了亚马逊OpenSearch的BM25搜索和向量语义搜索能力，并支持多种结果融合策略。
  • 多传输协议支持: 支持HTTP和Server-Sent Events (SSE) 两种传输协议，为客户端提供灵活的通信方式。
  • 灵活的认证机制: 支持IP地址白名单、OpenID Connect (OIDC) 认证，以及“同时需要”或“任选其一”的组合认证模式，保障服务器安全。
  • 上下文感知: 通过检索与查询相关的文档片段作为上下文，显著提升LLM的回答质量。
  • 可定制化: 允许通过环境变量配置服务器端口、认证方式、默认搜索参数等。

安装步骤

RAGent 是一个Go语言项目，安装前请确保您的系统已安装Go 1.25.0或更高版本。

  1. 克隆仓库: 
    git clone https://github.com/ca-srg/ragent.git
cd ragent
  2. 安装依赖: 
    go mod download
  3. 编译: 
    go build -o ragent
    您还可以选择将 'ragent' 可执行文件移动到 '/usr/local/bin/' 目录，以便在任何位置直接运行。

服务器配置

MCP服务器的配置主要通过环境变量完成。以下是MCP客户端连接服务器所需关注的关键配置信息。

MCP客户端通常需要一个JSON格式的配置，包含服务器的名称、启动命令（command）及其参数（args）。由于RAGent MCP服务器是独立运行的，其启动命令即是 'ragent mcp-server'，参数取决于您希望启用的功能。

MCP客户端配置示例 (JSON格式，例如用于Claude Desktop):

{
  "mcpServers": {
    "ragent-mcp": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "-H", "Content-Type: application/json",
        "-H", "Authorization: Bearer YOUR_JWT_TOKEN", // 如果启用了OIDC认证，请替换为您的JWT Token
        "-d", "@-",
        "http://localhost:8080/mcp" // 替换为您的服务器地址和端口
      ],
      "env": {}
    }
  }
}

配置说明:

  • 服务器名称: 'ragent-mcp' (您可以自定义)。
  • 'command': 'curl'。这表示MCP客户端将通过'curl'命令与您的MCP服务器进行HTTP通信。
  • 'args': 'curl'命令的参数。
    • '-X POST': 指定HTTP方法为POST，因为MCP使用JSON-RPC协议，通常通过POST请求发送。
    • '-H "Content-Type: application/json"': 设置请求头，表明请求体是JSON格式。
    • '-H "Authorization: Bearer YOUR_JWT_TOKEN"': 如果您的MCP服务器配置了OIDC认证，此项是必需的。 'YOUR_JWT_TOKEN' 需要替换为从OIDC提供商获取的有效JWT令牌。如果仅使用IP认证，此项可以省略。
    • '-d @-': 告诉'curl'从标准输入读取请求体。MCP客户端会将JSON-RPC请求通过标准输入传递给'curl'。
    • 'http://localhost:8080/mcp': 这是MCP服务器的实际访问地址。 请务必将其替换为您的RAGent MCP服务器实际运行的IP地址或域名，以及端口号。'/mcp'是RAGent MCP服务器处理MCP请求的默认路径。

重要环境变量（在启动RAGent MCP服务器前配置）: 您需要创建 '.env' 文件或直接在环境中设置以下变量：

  • 'AWS_REGION': AWS区域，用于OpenSearch和Bedrock服务。
  • 'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY': AWS凭证，如果使用IAM角色可省略。
  • 'OPENSEARCH_ENDPOINT': 您的OpenSearch集群的URL。
  • 'OPENSEARCH_INDEX': 用于存储RAG文档的OpenSearch索引名称。
  • 'MCP_SERVER_HOST': MCP服务器监听的IP地址 (例如 'localhost' 或 '0.0.0.0')。
  • 'MCP_SERVER_PORT': MCP服务器监听的端口 (例如 '8080')。
  • 'MCP_IP_AUTH_ENABLED': 'true' 或 'false'，是否启用IP认证。
  • 'MCP_ALLOWED_IPS': 允许访问服务器的IP地址列表，用逗号分隔 (例如 '127.0.0.1,::1,192.168.1.0/24')。
  • 'OIDC_ISSUER', 'OIDC_CLIENT_ID', 'OIDC_CLIENT_SECRET': 如果启用OIDC认证，需要配置这些变量。

基本使用方法

  1. 准备Markdown文档: 将您的Markdown文件放置在 'markdown/' 目录下（默认）。

    mkdir markdown
cp /path/to/your/documents/*.md markdown/

  2. 向量化文档: 使用 'vectorize' 命令将Markdown文档转换为向量，并存储到Amazon S3 Vectors和OpenSearch中。这是RAG系统的数据准备步骤。

    ./ragent vectorize

  3. 启动MCP服务器: 运行 'mcp-server' 命令启动RAGent MCP服务器。您可以选择认证方式，例如仅IP认证：

    ./ragent mcp-server --auth-method ip

    如果您启用了OIDC认证，可以使用 '--auth-method oidc' 或 'both'/'either'，并确保OIDC环境变量已设置。启动后，服务器会在指定端口监听，例如 'http://localhost:8080'。

  4. 与MCP客户端集成: 将上述“MCP客户端配置示例”中的JSON配置添加到您的MCP客户端（例如Claude Desktop）中。请务必将 'http://localhost:8080/mcp' 替换为您的RAGent MCP服务器实际可访问的地址。如果启用了OIDC，请确保您的'Authorization'头中包含有效的JWT Token。

    启动客户端后，您的LLM应用即可通过调用 'ragent-hybrid_search' 工具来获取上下文信息。

信息

分类

AI与计算

访问项目