MCP Lambda SAM

使用 AWS Lambda 和 SAM 实现的 Model Context Protocol (MCP)。

概述

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

1. 系统配置（管理）：

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

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

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

架构

Mermaid 图表

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

graph TD
  Client --> MCP[/"MCP Lambda\n(/sse & /message)"/]
  MCP -->|read/write| SessionTable[(Session Table)]
  MCP -->|query| RegistrationTable[(Registration Table)]
  MCP -->|invoke| RegisteredLambda["Registered Lambda Tool"]

  Admin[Administrator] --> RegistrationLambda[/"Registration Lambda\n(/register)"/]
  RegistrationLambda -->|write| RegistrationTable

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

系统配置指南（管理员）

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

部署

npx @markvp/mcp-lambda-sam deploy

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

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

权限概述

要访问 MCP 端点，用户和客户端必须具有调用相关 Function URLs 的 IAM 权限。

• 管理员：必须允许调用 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": "Example tool",
    "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 ...', // Must be AWS SigV4 signed
  }
});

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

示例 cURL 用于 SSE

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

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

1. 发送命令：

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)

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

• 前往 SAR 控制台
• 搜索 Mark Van Proctor 的 mcp-lambda-sam
• 单击 Deploy
• 设置参数：
  • 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-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';

// Usage example
deploy();

4. 本地开发和部署

安装包：

npm install @markvp/mcp-lambda-sam

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

npm run deploy

开发

# Install dependencies
npm install

# Lint
npm run lint

# Run tests
npm test

# Build
npm run build

# Deploy
npm run deploy

发布到 SAR

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

1. 打包应用程序：

npm run package:sar

1. 发布到 SAR：

npm run publish:sar

1. 将应用程序设为公开（一次性设置）：
   • 前往 AWS 控制台 > 无服务器应用程序存储库
   • 选择应用程序
   • 点击“共享”并选择“公开”
   • 应用以下共享策略：

   {
       "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. 创建一个新的拉取请求