Rag MCP Server

RAG MCP服务器（Lambda+OpenSearch无服务器）

该项目实现了一个RAG（检索增强生成）服务器，该服务器被设计为MCP（模型上下文协议）工具，在AWS上使用无服务器架构部署。

它使用AWS Lambda进行计算，使用API网关（HTTP API）进行请求接口，使用OpenSearch Serverless进行矢量存储/搜索，使用OpenAI进行嵌入和生成，使用AWS S3进行持久原始文档存储。

基础设施使用AWS Cloud Development Kit（CDK）和Python进行管理。

先决条件

在开始之前，请确保已安装以下内容：

• Node.js和npm： AWS CDK需要。 (下载)
• AWS CDK工具包： 通过npm全局安装： npm install -g aws-cdk
• AWS-CLI： 已安装并配置。这就是CDK和Makefile与您的AWS帐户交互的方式。

- 配置： 您需要配置凭据，通常通过以下方式： - IAM身份中心（SSO）：运行 aws configure sso 或 aws sso login这是推荐的现代方法。 - IAM用户：运行 aws configure 并提供访问密钥ID和秘密访问密钥（出于安全考虑不太推荐）。 - 请参阅 AWS CLI配置指南. - 重要提示： 确保您配置的AWS配置文件（或默认配置文件）具有足够的权限（请参阅“设置”部分）。

• python 版本3.9或更高（与Lambda运行时匹配）。
• 匹普： 通常包含在Python中。用于管理Python依赖关系。
• 制造商： 使用Makefile自动化目标所必需的。（通常预装在Linux/macOS上；可能需要在Windows上安装）。

项目结构

/
├── Makefile             # Automation commands (build, deploy, test, etc.)
├── pyproject.toml       # Application dependencies & project metadata
├── pytest.ini           # Pytest configuration (ensures tests find modules)
├── .env.example         # Example environment variables for local testing/config
├── README.md            # This file
├── src/                 # Application source code (Lambda handler, services, utils)
├── stack/               # CDK Stack definition (Python)
├── infrastructure/      # AWS CDK app definition and config
│   ├── app.py           # CDK App entrypoint
│   ├── cdk.json         # CDK configuration
└── tests/               # Application and infrastructure tests
    ├── test_lambda_handler.py
    └── test_infrastructure.py
└── example_payloads/    # Example JSON payloads for API requests
    ├── payload_add.json
    ├── payload_query.json
    └── payload_list.json

设置和配置

1. 安装依赖关系： 从项目根目录安装Python依赖项。

   make deps

1. AWS凭据和权限： （确保部署AdministratorAccess或同等工具）。

1. 在AWS Secrets Manager中创建机密（目标区域）：

- OpenAI API密钥秘密： - 姓名： AI/MCP_SERVERS/RAG_SERVER （或更新 stack/rag_mpc_stack.py) - 类型： 其他类型的秘密 - 密钥/值： 添加一个密钥 OPENAI_API_KEY 与你的 sk-... 键作为值。 - 应用程序API密钥机密： - 为什么？ 对已部署的API的客户端请求进行身份验证。 - 姓名： App/RagMcp/ApiKey （或更新 stack/rag_mpc_stack.py) - 类型： 其他类型的秘密 - 机密值： 选择 纯文本 并输入您的客户端应用程序（代理人工智能框架）将使用的强随机API密钥值。（例如生成UUID或使用密码生成器）。做 _不_ 将其存储为键/值对，只存储键字符串本身。

1. 环境变量（本地使用）： （测试/部署不需要）。

通过Makefile进行部署和管理

这 Makefile 为管理应用程序生命周期提供了方便的目标。如果需要，您可以使用环境变量覆盖默认的AWS区域和配置文件（例如。， AWS_REGION=us-east-1 make deploy).

典型工作流程：

1. make deps
2. make bootstrap
3. 创造两个秘密 AWS机密管理器中的（OpenAI密钥、应用程序API密钥）。
4. make deploy
5. make invoke / make logs /通过其API端点（包括API密钥）使用应用程序。
6. make destroy

生成文件目标：

• make build：构建Lambda部署包（从安装依赖项 pyproject.toml 以及复制 src/)进入 build/lambda_package/ 目录。这会自动发生，作为 make deploy 和 make test.

• make bootstrap：（每个AWS帐户/区域运行一次）引导AWS环境以进行CDK部署。

- 为什么？: CDK需要特定的AWS资源（如S3存储桶）来存储部署资产和管理部署。自举创建了这些共享资源。

  # Example using the default region from Makefile/AWS config
  make bootstrap
  # Example overriding region
  make bootstrap AWS_REGION=us-east-1

• make deploy：构建Lambda包并部署整个堆栈(RagMcpStack)使用 cdk deploy.

- 先决条件： 有效的AWS凭据、Secrets Manager中正确配置的OpenAI Secret以及目标区域的CDK引导已完成。 - 流程： CDK将堆栈定义合成到CloudFormation模板中并进行部署。这将创建/更新所有必要的AWS资源。这可能需要几分钟的时间，尤其是第一次或创建/更新OpenSearch资源时。 - 输出： 成功完成后，API网关端点URL将显示在堆栈输出中。

  make deploy
  # Example overriding region and profile
  make deploy AWS_REGION=us-east-1 AWS_PROFILE=my-dev-profile

• make test：构建包（如果需要），并使用以下命令运行单元和基础设施测试 pytest.

• make logs：实时跟踪部署的Lambda函数的CloudWatch日志。需要成功部署堆栈。按Ctrl+C停止。

• make destroy：销毁CDK堆栈通过CloudFormation创建的所有AWS资源。请谨慎使用，因为这是不可逆转的。

• make clean：删除本地生成工件(build/, cdk.out等等）。不会影响已部署的AWS资源。

• make invoke：显示示例 curl 用于与部署的API交互的命令。

- 首先，设置API_KEY和API_URL环境变量，如命令输出所示。 - 然后，运行示例 curl 命令。 - 请注意，POST请求使用来自 example_payloads/ 目录。 - 示例部署URL（来自上次成功部署）： https://9h8ob953ge.execute-api.eu-west-3.amazonaws.com/ （注意：始终使用以下网址 make invoke 输出或CloudFormation输出 _当前的_ 部署）。

架构概述

1. API网关（HTTP API）： 接收传入的HTTP请求 /mcp （GET用于发现，POST用于执行）。
2. Lambda函数： 处理来自API网关的请求。解析MCP调用，获取机密，生成嵌入（使用OpenAI），与OpenSearch Serverless和S3交互，并可能调用OpenAI进行生成。
3. OpenSearch无服务器： 存储文档嵌入和元数据。为RAG检索步骤提供k-NN向量搜索功能。
4. S3铲斗： 存储添加文档的原始文本内容。
5. 保密经理： 安全地存储OpenAI API密钥。
6. 国际机械师协会： 定义Lambda函数访问其他AWS服务（S3、Secrets Manager、OpenSearch、CloudWatch Logs）的权限。
7. 云观察： 从Lambda函数收集日志。

开发说明

• 测试： 使用 make test 使用模拟的AWS/OpenAI/OpenSearch依赖关系运行单元测试。真正的端到端测试通常涉及部署到开发AWS环境。
• 依赖关系： 将Python依赖项添加到 pyproject.toml 然后跑 make deps.
• 基础设施： 通过编辑修改AWS资源 stack/rag_mpc_stack.py.
• 应用逻辑： 通过编辑Lambda中的文件来修改Lambda行为 src/ 目录。

运行示例脚本

Python脚本示例(example.py)演示了如何与已部署的API进行交互：

1. 部署堆栈： 确保堆栈已部署(make deploy).

1. 设置环境变量： 您需要提供已部署的API URL和应用程序API密钥作为环境变量。你可以用 make invoke 或来自CloudFormation堆栈输出。

   # Get the URL (example)
   export API_URL=$(aws cloudformation describe-stacks --stack-name RagMcpStack --query "Stacks[0].Outputs[?OutputKey=='ApiGatewayEndpoint'].OutputValue" --output text --profile  --region )

   # Set your key (replace with the actual key from Secrets Manager)
   export API_KEY=""

1. 运行脚本：

   python example.py

该脚本将调用发现端点，添加两个文档，列出文档，并执行查询，打印请求和响应。 _注：_ 脚本要求 requests 图书馆(pip install requests 如果你没有它，尽管它应该通过安装 make deps).

常见故障排除提示

• ExpiredToken / InvalidClientTokenId 错误： 刷新AWS凭据(aws sso login).
• 部署未能提及Secrets Manager： 检查：

- CDK中的秘密名称与AWS完全匹配。 - 秘密存在于 _同一地区_ 作为部署。 - 机密值的格式正确（OpenAI密钥需要 OPENAI_API_KEY 字段，应用程序API密钥应为纯文本）。 - 部署者凭据具有 secretsmanager:GetSecretValue 许可。

• 部署失败，出现IAM错误： 检查部署程序权限。
• API网关返回401未授权： 确保客户端在中发送正确的API密钥值 X-API-Key 头球
• API网关返回5xx错误： 检查Lambda日志(make logs).