MCP Lambda SAM

使用AWS Lambda和SAM实现模型上下文协议（MCP）。

概述

该项目提供了一个无服务器的MCP实现，具有两个不同的接口：

1. 系统配置（管理）：

   • 注册MCP工具、资源和提示
   • IAM权限管理
   • 基础设施设置和配置

2. 系统使用（客户端）：

   • 建立SSE连接
   • 发送命令
   • 接收流式响应

架构

Mermaid图表

您可以使用以下Mermaid语法可视化系统：

graph TD
  客户端 --> MCP[/"MCP Lambda\n(/sse & /message)"/]
  MCP -->|读/写| SessionTable[(会话表)]
  MCP -->|查询| RegistrationTable[(注册表)]
  MCP -->|调用| RegisteredLambda["已注册的Lambda工具"]

  管理员[管理员] --> RegistrationLambda[/"注册Lambda\n(/register)"/]
  RegistrationLambda -->|写入| RegistrationTable

• MCP Lambda 在启动时和处理请求时从注册表中读取注册信息。
• 它使用会话表来持久化会话状态。
• 它根据注册表中存储的ARN动态调用已注册的Lambda工具。

系统配置指南（管理员）

本节适用于需要配置和管理MCP服务器的系统管理员。

部署

npx @markvp/mcp-lambda-sam deploy

该命令将交互式地提示进行管理员配置：

• 栈名称（用于多个实例）
• AWS区域
• VPC配置（可选）

权限概述

要访问MCP端点，用户和客户端必须具有IAM权限以调用相关的函数URL。

• 管理员：必须允许调用mcp-registration函数URL
• 客户端：必须允许调用mcp函数URL

您可以通过IAM策略或aws lambda add-permission（见下文）授予访问权限。

通过AWS CLI分配权限

要授予调用注册函数URL的权限：

aws lambda add-permission \
  --function-name <registration-function-name> \
  --statement-id allow-registration \
  --action lambda:InvokeFunctionUrl \
  --principal "*" \
  --function-url-auth-type IAM

要授予调用MCP函数URL（SSE和消息）的权限：

aws lambda add-permission \
  --function-name <mcp-function-name> \
  --statement-id allow-mcp \
  --action lambda:InvokeFunctionUrl \
  --principal "*" \
  --function-url-auth-type IAM

将<registration-function-name>和<mcp-function-name>替换为实际的Lambda函数名。

注册API

使用这些端点来管理MCP工具、资源和提示：

注册新工具

awscurl -X POST ${REGISTRATION_URL}/register \
  --region ap-southeast-2 \
  --service lambda \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool",
    "name": "example",
    "description": "示例工具",
    "lambdaArn": "arn:aws:lambda:region:account:function:name",
    "parameters": {
      "input": "string"
    }
  }'

更新注册

awscurl -X PUT ${REGISTRATION_URL}/register/{id} \
  --region ap-southeast-2 \
  --service lambda \
  -d '...'

删除注册

awscurl -X DELETE ${REGISTRATION_URL}/register/{id} \
  --region ap-southeast-2 \
  --service lambda

列出注册

awscurl ${REGISTRATION_URL}/register \
  --region ap-southeast-2 \
  --service lambda

所需IAM权限

对于管理员

管理员需要这些权限来管理注册：

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "lambda:InvokeFunctionUrl",
    "Resource": "arn:aws:lambda:${region}:${account}:function:${stack-id}-mcp-registration",
    "Condition": {
      "StringEquals": {
        "lambda:FunctionUrlAuthType": "AWS_IAM"
      }
    }
  }]
}

系统使用指南（客户端）

本节适用于希望使用MCP服务器的客户端。

所需IAM权限

客户端需要这些权限来使用MCP服务器：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "lambda:InvokeFunctionUrl",
            "Resource": [
                "arn:aws:lambda:${region}:${account}:function:${stack-id}-mcp",
            ],
            "Condition": {
                "StringEquals": {
                    "lambda:FunctionUrlAuthType": "AWS_IAM"
                }
            }
        }
    ]
}

连接到服务器

1. 建立SSE连接：

const sse = new EventSource(SSE_URL, {
  headers: { 
    Authorization: 'AWS4-HMAC-SHA256 ...', // 必须是AWS SigV4签名
  }
});

sse.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

SSE示例cURL

awscurl -X GET "${MCP_URL}/sse" \
  --region ap-southeast-2 \
  --service lambda

第一个事件将包含一个sessionId。在发送消息时使用它。

2. 发送命令：

awscurl -X POST "${MCP_URL}/message?sessionId=session-123" \
  --region ap-southeast-2 \
  --service lambda \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "example",
    "params": {
      "input": "hello"
    }
  }'

错误处理

常见客户端错误

• 401：无效/缺少AWS凭证
• 403：权限不足
• 404：无效的会话ID
• 429：超出速率限制

故障排除

1. 连接问题：

   • 验证AWS凭证
   • 检查IAM权限
   • 确保网络连接

2. 命令执行错误：

   • 验证会话ID是否有效
   • 检查命令格式是否与工具注册匹配
   • 确保参数符合模式

要求

• 已安装并配置了AWS CLI
• 已安装AWS SAM CLI
• Node.js 20.x或更高版本
• 具有创建权限的AWS账户：
  • Lambda函数
  • DynamoDB表
  • IAM角色
  • SQS队列

AWS SAM CLI 设置

要使用AWS SAM CLI本地部署此应用程序或部署到AWS：

1. 安装AWS SAM CLI：https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html
2. 确保它在您的PATH中可用：

   sam --version
   

3. 构建并部署应用程序：

   sam build
   sam deploy --guided
   

4. 按照提示配置栈名称、区域、功能和参数覆盖。

您可以不带--guided重新运行sam deploy以使用保存的配置。

安装

您可以采用四种方式安装和部署此应用程序：

1. 使用AWS Serverless Application Repository (SAR)

最简单的部署MCP服务器的方式是通过AWS Serverless Application Repository (SAR)：

• 转到SAR控制台
• 搜索Mark Van Proctor的mcp-lambda-sam
• 单击部署
• 设置您的参数：
  • StackIdentifier：此MCP服务器实例的唯一ID
  • VpcEnabled：如果在VPC中部署，则设置为true
  • VpcId和SubnetIds：仅当VpcEnabled为true时提供
• 按照提示进行部署

或者，您也可以通过AWS CLI部署：

aws serverlessrepo create-cloud-formation-change-set \
  --application-id arn:aws:serverlessrepo:ap-southeast-2:522814717816:applications/mcp-l
lambda-sam \
  --stack-name your-stack-name \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides '[{"name":"StackIdentifier","value":"your-stack-id"}]'

2. 使用npx (CLI)

npx @markvp/mcp-lambda-sam deploy

该命令将交互式地提示进行管理员配置：

• 栈名称（用于多个实例）
• AWS区域
• VPC配置（可选）

3. 使用安装进行编程使用

安装包：

npm install @markvp/mcp-lambda-sam

安装包后，您可以编程使用它：

import { deploy } from '@markvp/mcp-lambda-sam';

// 使用示例
deploy();

4. 本地开发和部署

安装包：

npm install @markvp/mcp-lambda-sam

在进行开发更改后，可以手动部署：

npm run deploy

开发

# 安装依赖
npm install

# 代码检查
npm run lint

# 运行测试
npm test

# 构建
npm run build

# 部署
npm run deploy

发布到SAR

如果您正在为此项目做出贡献，并且需要将更新发布到SAR：

1. 打包应用程序：

npm run package:sar

2. 发布到SAR：

npm run publish:sar

3. 将应用程序设为公开（一次性设置）：
   • 转到AWS控制台 > Serverless Application Repository
   • 选择应用程序
   • 单击“分享”并选择“公开”
   • 应用以下共享策略：

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": "*",
               "Action": "serverlessrepo:CreateCloudFormationTemplate",
               "Resource": "arn:aws:serverlessrepo:${region}:${account-id}:applications/mcp-lambda-sam"
           }
       ]
   }
   

许可证

MIT

贡献

1. 分叉仓库
2. 创建您的功能分支
3. 提交更改
4. 推送到分支
5. 创建新的拉取请求