内容
# MCP 在 AWS 上的部署模式，使用示例数学 MCP 服务器
一个示例 MCP 服务器，演示在 AWS 上使用不同部署方法，并具有全面的身份验证选项。
## 目录
- [概述](#概述)
- [项目结构](#项目结构)
- [配置管理](#配置管理)
- [部署方法](#部署方法)
- [使用 SigV4/IAM 身份验证的 AgentCore](#1-使用sigv4iam身份验证的agentcore)
- [使用 OAuth 身份验证的 AgentCore](#2-使用oauth身份验证的agentcore)
- [无服务器 Lambda](#3-无服务器lambda)
- [ECS 容器部署](#4-ecs容器部署)
- [EKS Kubernetes 部署](#5-eks-kubernetes-部署)
- [使用 MCP Inspector 进行测试](#使用mcp-inspector进行测试)
- [比较表格](#比较表格)
- [故障排除](#故障排除)
---
## 概述
该项目演示了 MCP 服务器在 AWS 上的不同部署模式：
1. **Amazon Bedrock AgentCore 与 IAM SigV4** - 生产就绪，具有 AWS Identity and Access Management (IAM) 身份验证
2. **Amazon Bedrock AgentCore 与 OAuth** - 基于用户的身份验证，使用 Amazon Cognito JWT 令牌
3. **无服务器 AWS Lambda** - 经济高效的自动扩展部署
4. **Amazon Elastic Container Service (ECS) 容器** - 容器化部署，具有应用程序负载均衡器
5. **Amazon Elastic Kubernetes Service (EKS) Kubernetes** - Kubernetes 部署，具有 Amazon API Gateway 和 SigV4 身份验证
---
## 项目结构
```
maths/
├── deploy-agentcore-iam/ # 使用 IAM Sigv4 身份验证的 AgentCore 部署
│ ├── .env.example # 配置模板
│ ├── infrastructure/ # 部署脚本
│ └── src/ # MCP 服务器实现
├── deploy-agentcore-oauth/ # 使用 OAuth 的 AgentCore 部署
│ ├── .env.example # 配置模板
│ ├── infrastructure/ # 部署脚本和 OAuth 配置
│ ├── get-access-token.py # 获取 Cognito 访问令牌的脚本
│ └── src/ # MCP 服务器实现
├── deploy-ecs/ # ECS 容器部署
│ ├── .env.example # 配置模板
│ ├── infrastructure/ # CloudFormation 模板
│ └── src/ # MCP 服务器实现
├── deploy-eks/ # EKS Kubernetes 部署
│ ├── deployment/ # 3 步部署脚本
│ ├── infrastructure/ # CloudFormation 模板
│ ├── k8s/ # Kubernetes 清单
│ └── src/ # MCP 服务器实现
├── deploy-serverless/ # 无服务器 Lambda 部署
│ ├── .env.example # 配置模板
│ ├── infrastructure/ # CloudFormation + 部署脚本
│ └── src/ # Lambda 函数 + MCP 服务器
└── mcp-inspector/ # 所有部署的测试工具
├── agentcore-proxy-sigv4.py # 使用 IAM SigV4 测试 AgentCore
├── agentcore-proxy-oauth.py # 使用 JWT Bearer Token 测试 AgentCore
└── serverless-proxy.py # 测试无服务器部署
```
---
## 配置管理
### 设置配置
```bash
# 对于使用 SigV4/IAM 的 AgentCore
cd deploy-agentcore
cp .env.example .env
# 使用您的配置创建 .env
# 对于使用 OAuth 的 AgentCore
cd deploy-agentcore-oauth
cp .env.example .env
# 使用您的配置创建 .env
# 对于无服务器
cd deploy-serverless
cp .env.example .env
# 使用您的配置创建 .env
```
---
## 部署方法
### 1. 使用 IAM SigV4 身份验证的 Amazon Bedrock AgentCore
**用例：** 使用 AWS IAM 身份验证的生产部署
**配置** (`deploy-agentcore-iam/.env`):
```bash
# AgentCore 配置
AGENT_NAME=maths_mcp_agentcore
REGION=ap-southeast-2
AGENT_RUNTIME_ARN=arn:aws:bedrock-agentcore:region:account:runtime/agent-name
# Amazon Cognito 配置（可选，用于令牌生成）
COGNITO_USER_POOL_ID=your-region_XXXXXXXXX
COGNITO_CLIENT_ID=your-client-id
COGNITO_CLIENT_SECRET=your-client-secret
COGNITO_REGION=your-region
COGNITO_USERNAME=your-email@example.com
COGNITO_PASSWORD=YourSecurePassword
```
**部署：**
```bash
cd deploy-agentcore-iam/infrastructure
./deploy.sh
```
**发生的情况：**
- 从 `.env` 加载配置
- 使用 AWS IAM 凭证（IAM SigV4 签名）
- 不需要 JWT 令牌
- 部署到 Amazon Bedrock AgentCore
**使用 MCP Inspector 测试：**
```bash
cd mcp-inspector
npx @modelcontextprotocol/inspector python3 agentcore-proxy-sigv4.py
```
---
### 2. 使用 OAuth/Cognito 身份验证的 Amazon Bedrock AgentCore
**用例：** 使用 JWT 令牌的基于用户的身份验证
**配置** (`deploy-agentcore-oauth/.env`):
```bash
# AgentCore 配置
AGENT_NAME=maths_mcp_agentcore_oauth
REGION=ap-southeast-2
# OAuth 配置
OAUTH_DISCOVERY_URL=https://cognito-idp.region.amazonaws.com/pool-id/.well-known/openid-configuration
OAUTH_CLIENT_ID=your-client-id
# Amazon Cognito 配置
COGNITO_USER_POOL_ID=your-region_XXXXXXXXX
COGNITO_CLIENT_ID=your-client-id
COGNITO_CLIENT_SECRET=your-client-secret
COGNITO_REGION=your-region
COGNITO_USERNAME=your-email@example.com
COGNITO_PASSWORD=YourSecurePassword
```
**部署：**
```bash
cd deploy-agentcore-oauth/infrastructure
./deploy.sh
```
**发生的情况：**
- 从 `.env` 加载 `OAUTH_DISCOVERY_URL` 和 `OAUTH_CLIENT_ID`
- 配置 Amazon Bedrock AgentCore 使用 OAuth 身份验证
- 需要 JWT 令牌进行访问
- [AWS AgentCore OAuth 文档](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html)：
- `client_id`：必须与 `allowedClients` 之一匹配（必需）
- `aud`：如果指定，必须与 `allowedAudience` 匹配（可选）
**通过删除 `allowedAudience`，Amazon Cognito ACCESS 令牌（具有 `client_id` 但没有 `aud`）工作正常！**
**获取访问令牌：**
```bash
cd deploy-agentcore-oauth
python3 get-access-token.py
# 从输出中复制 ACCESS TOKEN
```
**使用 MCP Inspector 测试：**
```bash
cd mcp-inspector
export BEARER_TOKEN="your-access-token-here"
npx @modelcontextprotocol/inspector python3 agentcore-proxy-oauth.py
or
npx @modelcontextprotocol/inspector ./02-start-oauth-proxy.sh agentcore-proxy-oauth.py
```
---
### 3. 无服务器（AWS Lambda + Amazon API Gateway）
**配置** (`deploy-serverless/.env`):
```bash
# 部署配置
STACK_NAME=maths-mcp-server
REGION=ap-southeast-2
STAGE=dev
USER_POOL_NAME=maths-mcp-users
APP_CLIENT_NAME=maths-mcp-client
# 用于测试的 Amazon Cognito 用户凭证
COGNITO_USERNAME=your-email@example.com
COGNITO_PASSWORD=YourSecurePassword123!
# Amazon Cognito 配置（来自 AWS CloudFormation 输出）
COGNITO_USER_POOL_ID=your-region_XXXXXXXXX
COGNITO_CLIENT_ID=your-client-id
COGNITO_REGION=your-region
```
**部署：**
```bash
cd deploy-serverless/infrastructure
./deploy.sh
```
**发生的情况：**
- 从 `.env` 加载所有配置
- 使用 [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) 创建基础设施
- 创建具有配置名称的 Amazon Cognito 用户池
- 部署 AWS Lambda 函数与 Amazon API Gateway
**使用 MCP Inspector 测试：**
```bash
cd mcp-inspector
./start-serverless-proxy.sh
or
npx @modelcontextprotocol/inspector ./03-start-lambda-proxy.sh agentcore-lambda-proxy.py
```
---
### 4. Amazon ECS 容器部署
**用例：** 使用 [Application Load Balancer (ALB)](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) 的容器化部署
**配置** (`deploy-ecs/.env`):
```bash
# Amazon ECS 配置
CLUSTER_NAME=maths-mcp-ecs
SERVICE_NAME=maths-mcp-service
TASK_FAMILY=maths-mcp-task
REGION=us-west-2
# 容器配置
IMAGE_NAME=maths-mcp-server
ECR_REPOSITORY=maths-mcp-server
CONTAINER_PORT=8000
# 负载均衡器配置
ALB_NAME=maths-mcp-alb
TARGET_GROUP_NAME=maths-mcp-targets
```
**部署：**
```bash
cd deploy-ecs/infrastructure
./deploy.sh
```
**发生的情况：**
- 创建具有 [AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html) 任务的 Amazon ECS 集群
- 构建并将 Docker 镜像推送到 [Amazon Elastic Container Registry (ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)
- 设置应用程序负载均衡器
- 配置自动缩放和健康检查
**测试：**
```bash
# 健康检查
curl http://YOUR_ALB_URL/health
# MCP 端点
curl -X POST http://YOUR_ALB_URL/mcp \
-H "Content-Type: application/json" \
-d '{"method":"tools/list","id":1}'
```
---
### 5. Amazon EKS Kubernetes 部署
**用例：** 使用 Amazon API Gateway 和 [SigV4](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html) 身份验证的生产 Kubernetes 部署
**架构：**
```
Internet → Amazon API Gateway (IAM SigV4) → VPC Link → Internal ALB → EKS Pods (MCP Server)
```
**配置** (`deploy-eks/.env`):
```bash
# Amazon EKS 配置
CLUSTER_NAME=maths-mcp-eks
REGION=us-west-2
NAMESPACE=mcp-server
# 容器配置
IMAGE_NAME=maths-mcp-server
ECR_REPOSITORY=maths-mcp-server
REPLICAS=2
# 部署脚本自动配置
VPC_ID=
ECR_URI=
INTERNAL_ALB_URL=
API_GATEWAY_URL=
```
**部署（3 步过程）：**
```bash
cd deploy-eks/deployment
# 步骤 1：部署 EKS 基础设施
./01-deploy-infrastructure.sh
# 步骤 2：部署 MCP 服务器工作负载
./02-deploy-workload.sh
# 步骤 3：部署具有身份验证的 API Gateway
./03-deploy-api-gateway.sh
```
**发生的情况：**
- **步骤 1**：创建 Amazon EKS 集群、[Amazon Virtual Private Cloud (VPC)](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) 和 AWS Load Balancer Controller
- **步骤 2**：构建 Docker 镜像，将其部署到 Kubernetes，使用内部 ALB
- **步骤 3**：创建具有 VPC Link 和 IAM SigV4 身份验证的 Amazon API Gateway
**测试：**
```bash
# 健康端点（无需身份验证）
curl https://YOUR_API_GATEWAY_URL/health
# MCP 端点（需要 SigV4 身份验证）
cd deploy-eks/deployment
python3 test-api.py
```
**清理：**
```bash
cd deploy-eks/deployment
./cleanup.sh
```
---
## 使用 MCP Inspector 进行测试
所有三种部署都可以使用 MCP Inspector 进行测试。
### 先决条件
```bash
npm install -g @modelcontextprotocol/inspector
pip install mcp httpx boto3 python-dotenv botocore
```
### 测试命令
| 部署 | 命令 | 身份验证方法 | 需要令牌 |
|------------|---------|-------------|--------------|
| **AgentCore [SigV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)** | `npx @modelcontextprotocol/inspector python3 agentcore-proxy-sigv4.py` | AWS IAM | 否 |
| **AgentCore OAuth** | `npx @modelcontextprotocol/inspector ./02-start-oauth-proxy.sh agentcore-proxy-oauth.py` | Amazon Cognito JWT | 访问令牌 |
| **ECS 容器** | `curl http://ALB_URL/health` | 无 | 否 |
| **EKS Kubernetes** | `cd mcp-inspector && ./05-start-eks-proxy.sh` | AWS SigV4 | 否 |
| **无服务器** | `npx @modelcontextprotocol/inspector ./03-start-lambda-proxy.sh` | Amazon Cognito | ID 令牌 |
## 比较表格
| 功能 | AgentCore (SigV4) | AgentCore (OAuth) | ECS 容器 | EKS Kubernetes | 无服务器 (Lambda) |
|---------|-------------------|-------------------|---------------|----------------|---------------------|
| **身份验证** | [AWS IAM (SigV4)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html) | Amazon Cognito JWT | 无 (ALB) | SigV4 + 公共健康 | Amazon Cognito 用户池 |
| **配置** | `.env` 文件 | `.env` 文件 | `.env` 文件 | `.env` 文件 | `.env` 文件 |
| **设置复杂度** | 中等 | 中高 | 中等 | 高 | 高 |
| **成本模型** | 按运行时小时付费 | 按运行时小时付费 | 支付运行容器费用 | 支付 EKS + EC2 实例费用 | 按请求付费 |
| **冷启动** | 否 | 否 | 否 | 否 | 是（~500ms） |
| **可扩展性** | 手动 | 手动 | 自动扩展 | Kubernetes HPA | 自动 |
| **安全性** | 基于 IAM | 基于 JWT | 基于网络 | Amazon API Gateway + IAM | Amazon API Gateway + Cognito |
| **最佳用途** | 生产环境使用 IAM | 基于用户的应用程序 | 简单的容器化应用程序 | 企业 Kubernetes | 成本敏感，负载变动 |
| **基础设施** | 托管服务 | 托管服务 | ECS + ALB | EKS + ALB + API Gateway | Lambda + API Gateway |
---
## 开发工作流
### 对 MCP 服务器进行更改
1. 编辑 `src/` 文件夹中的服务器代码
2. 重新部署：
```bash
cd <部署文件夹>/infrastructure
./deploy.sh
```
3. 使用适当的代理脚本测试 MCP Inspector
### 测试不同的身份验证方法
1. **IAM SigV4** - 最适合使用您的 AWS 凭证进行测试
2. **JWT Bearer Token Authentication** - 最适合测试基于用户的身份验证流程
3. **无服务器** - 最适合测试 API Gateway 集成
---
## 其他资源
- [Amazon Bedrock AgentCore 文档](https://docs.aws.amazon.com/bedrock-agentcore/)
- [Model Context Protocol (MCP) 规范](https://modelcontextprotocol.io/)
- [MCP Inspector 文档](https://github.com/modelcontextprotocol/inspector)
- [Amazon Cognito 用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)
- [AWS Signature Version 4 (SigV4)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html)
- [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)
---
## 故障排除
### Amazon Bedrock AgentCore 部署问题
**错误：** 代理未找到
```bash
# 检查代理状态
cd deploy-agentcore-iam/infrastructure
agentcore status --agent maths_mcp_agentcore
```
**错误：** 无效的 OAuth 令牌
```bash
# 获取新鲜的访问令牌
cd deploy-agentcore-oauth
python3 get-access-token.py
```
**错误：**.env 文件未找到
```bash
# 复制模板并配置
cp .env.example .env
# 编辑 .env 并输入您的值
```
### Amazon ECS 部署问题
**错误：** 任务启动失败
```bash
# 检查 ECS 任务日志
aws ecs describe-tasks --cluster CLUSTER_NAME --tasks TASK_ARN
aws logs get-log-events --log-group-name /ecs/maths-mcp-task
```
**错误：** ALB 健康检查失败
```bash
# 检查目标组健康
aws elbv2 describe-target-health --target-group-arn TARGET_GROUP_ARN
```
**错误：** ECR 推送失败
```bash
# 登录到 Amazon ECR
aws ecr get-login-password --region REGION | docker login --username AWS --password-stdin ACCOUNT.dkr.ecr.REGION.amazonaws.com
```
### Amazon EKS 部署问题
**错误：** 集群未找到
```bash
# 检查集群状态
aws eks describe-cluster --name CLUSTER_NAME --region REGION
```
**错误：** Pod 未启动
```bash
# 检查 Pod 状态和日志
kubectl get pods -n mcp-server
kubectl logs -f deployment/maths-mcp-server -n mcp-server
```
**错误：** ALB 未创建
```bash
# 检查 ingress 状态
kubectl describe ingress maths-mcp-server-internal -n mcp-server
```
**错误：** Amazon API Gateway 失败
```bash
# 附加 IAM 策略到您的用户/角色
aws iam attach-user-policy --user-name USERNAME --policy-arn POLICY_ARN
```
### 无服务器部署问题
**错误：** 堆栈已存在
```bash
# 脚本自动处理更新
cd deploy-serverless/infrastructure
./deploy.sh
```
**错误：** Lambda 包太大
```bash
# 检查包大小（应小于 50MB）
cd deploy-serverless/infrastructure
du -sm build/
```
### MCP Inspector 问题
**错误：** 连接被拒绝
- 确保部署已完成且代理已就绪
- 检查 `.env` 文件是否包含正确的 `AGENT_RUNTIME_ARN`
- 验证 AWS 凭证是否已配置
**错误：** 令牌过期（OAuth）
```bash
# 获取新的访问令牌
cd deploy-agentcore-oauth
python3 get-access-token.py
```
**错误：** 模块未找到
```bash
# 安装依赖项
pip install mcp httpx boto3 python-dotenv botocore
```
---
## 贡献
在添加新功能时：
1. 更新所有部署方法以保持一致性
2. 在 mcp-inspector 中添加相应的测试
3. 使用此 README 更新新的配置要求
4. 更新 `.env.example` 模板
参见 [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) 获取更多信息。
## 执照
本库使用 MIT-0 执照。参见 LICENSE 文件。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器