Serverless MCP

无服务器MCP

使用AWS Lambda、CloudFront和Cognito身份验证的模型上下文协议（MCP）的无服务器实现。该项目为在云中托管MCP服务器提供了一个完整的基础设施，包括OAuth 2.0身份验证、通过JSON-RPC 2.0消息格式的服务器发送事件进行实时流式传输以及可扩展的无服务器架构。该实现包括符合RFC的OAuth 2.0支持，包括OAuth 2.0授权服务器元数据（RFC 8414）、OAuth 2.0动态客户端注册协议（RFC 7591）和OAuth 2.0受保护资源元数据（RFC 9728）。具有与官方模型上下文协议TypeScript SDK兼容的自定义传输实现。

特性

• MCP协议实现：通过工具和资源全面支持模型上下文协议
• 无服务器架构：AWS Lambda功能与CloudFront分发
• OAuth 2.0身份验证：使用AWS Cognito进行安全身份验证
• 实时流媒体：服务器发送事件（SSE）支持实时通信
• 会话管理：有状态和无状态会话处理
• 自定义域名：SSL证书和Route 53 DNS配置
• GitHub操作部署：基于OIDC的CI/CD管道

建筑

该项目由两个主要的CDK堆栈组成：

1. 无服务器McpStack：核心基础设施，包括Lambda函数、CloudFront分发、Cognito用户池和DynamoDB表
2. GitHubOidcStack：GitHub Actions OIDC安全部署提供商

serverless-mcp architecture

先决条件

• Node.js 22
• pnpm>=10.12
• 配置了适当权限的AWS CLI
• 在Route 53托管区域注册的域名

安装

1. 克隆存储库：

git clone https://github.com/hteek/serverless-mcp.git
cd serverless-mcp

1. 安装依赖项：

pnpm install

1. 在中配置您的域设置 config/default.ts:

export default {
  domainName: 'your-domain.com',
  github: {
    owner: 'your-github-username',
    repo: 'your-repo-name',
  },
  hostedZoneId: 'YOUR_ROUTE53_HOSTED_ZONE_ID',
  project: 'your-project-name',
};

发展

构建和测试

# Build the project
pnpm build

# Watch for changes during development
pnpm watch

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with UI
pnpm test:ui

代码质量

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code
pnpm format

# Check formatting
pnpm format:check

部署

先决条件

1. 确保您的AWS凭据已配置
2. 验证您的域是否已注册，以及托管区域ID是否正确
3. 构建项目： pnpm build

手动部署

# Deploy both stacks
pnpm cdk deploy --all

# Deploy specific stack
pnpm cdk deploy serverless-mcp
pnpm cdk deploy serverless-mcp-github-oidc

# Preview changes
pnpm cdk diff

# Generate CloudFormation templates
pnpm cdk synth

GitHub操作部署

该项目包括三个用于自动部署的GitHub Actions工作流：

1.持续集成和部署(ci.yml)

触发：推到 main 分支和拉取请求

工作:

• CI管道：对所有推送和PR运行构建、lint和测试
• 自动化部署：在将更改推送到时部署到AWS main

环境：用途 development 环境与 AWS_ACCOUNT 变量

2.手动部署(manual-deploy.yml)

触发：通过GitHub UI手动调度工作流

用法：用于不更改代码的即席部署

3.可重用的部署工作流(deploy.yml)

目的：其他工作流使用的共享部署逻辑

特性:

• 使用AWS进行OIDC身份验证
• 安装依赖项并构建项目
• 使用CDK部署，无需批准

初始设置

1. 部署GitHub OIDC堆栈 （一次性设置）：

pnpm cdk deploy serverless-mcp-github-oidc

1. 配置GitHub环境:

- 转到您的GitHub存储库→ 设置→ 环境 - 创建一个 development 环境 - 添加环境变量： AWS_ACCOUNT 使用您的AWS帐户ID

1. 验证部署:

- GitHub OIDC堆栈创建了一个IAM角色： github-actions-role - 此角色具有部署CDK所需的权限 - GitHub secrets中不需要长期的AWS凭据

部署程序

自动部署:

1. 将更改推送到 main 分支
2. CI工作流运行：构建→ lint → test → 部署
3. 部署使用OIDC承担AWS角色
4. CDK部署 serverless-mcp 堆栈

手动部署:

1. 转到GitHub存储库中的“操作”选项卡
2. 选择“手动部署”工作流
3. 点击“运行工作流” main 分支

监控部署

• GitHub操作：在“操作”选项卡中查看工作流运行情况
• AWS 云形成：检查AWS控制台中的堆栈状态
• 云监控：监控Lambda函数日志和指标

用法

MCP服务器端点

部署后，您的MCP服务器将在以下位置可用：

• 主要终点: https://your-domain.com/mcp
• 认证: https://auth.your-domain.com

可用的MCP工具

服务器实现了以下AWS成本资源管理器工具：

• 获取日期：获取当前日期以帮助进行相对日期查询

  {
    "name": "get_today_date"
  }

• get_dimension_values：获取AWS成本资源管理器维度（服务、区域等）的可用值

  {
    "name": "get_dimension_values", 
    "arguments": {
      "dimensionKey": "SERVICE",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31"
    }
  }

• get_tag_values：获取特定标记键的可用值

  {
    "name": "get_tag_values",
    "arguments": {
      "tagKey": "Environment", 
      "startDate": "2024-01-01",
      "endDate": "2024-01-31"
    }
  }

• get_cost_and_usage：通过过滤和分组检索AWS成本和使用数据

  {
    "name": "get_cost_and_usage",
    "arguments": {
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "granularity": "MONTHLY",
      "groupBy": [{"Type": "DIMENSION", "Key": "SERVICE"}]
    }
  }

• get_cost_forecast：根据历史使用模式生成成本预测

  {
    "name": "get_cost_forecast",
    "arguments": {
      "startDate": "2024-02-01", 
      "endDate": "2024-02-29",
      "metric": "UNBLENDED_COST"
    }
  }

• get_cost_和_usage_比较：比较两个时间段的成本

  {
    "name": "get_cost_and_usage_comparisons",
    "arguments": {
      "baseStartDate": "2024-01-01",
      "baseEndDate": "2024-01-31", 
      "comparisonStartDate": "2024-02-01",
      "comparisonEndDate": "2024-02-29"
    }
  }

• get_cost_comparison_drivers：分析各时期成本变化的驱动因素

  {
    "name": "get_cost_comparison_drivers",
    "arguments": {
      "baseStartDate": "2024-01-01",
      "baseEndDate": "2024-01-31",
      "comparisonStartDate": "2024-02-01", 
      "comparisonEndDate": "2024-02-29"
    }
  }

可用MCP资源

• 问候：动态问候资源

- 模板： greeting://[name] - 例子： greeting://world 返回“你好，世界！”

客户端连接

使用任何兼容MCP的客户端连接到您的MCP服务器：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPTransport('https://your-domain.com/mcp');

const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

配置

环境特定设置

在中创建特定于环境的配置文件 config/ 目录：

• config/development.ts
• config/production.ts
• config/staging.ts

CDK上下文

修改 cdk.json 以调整CDK特征标志和行为。

监控与调试

• CloudWatch日志：Lambda函数日志会自动发送到CloudWatch
• AWS X射线：已启用分布式跟踪以进行性能监控
• 指标：使用AWS Lambda Powertools收集自定义指标

安全

• 认证：使用AWS Cognito的OAuth 2.0
• 超文本传输安全协议：所有流量均使用SSL/TLS加密
• 国际机械师协会：最低权限访问策略
• 会话管理：通过验证确保会话处理的安全

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/new-feature
3. 进行更改并添加测试
4. 运行linting和测试： pnpm lint && pnpm test
5. 提交您的更改： git commit
6. 推送并创建拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

1. 检查 文档 用于发展指导
2. 在GitHub上打开一个问题
3. 查看CloudWatch日志以获取调试信息

有用的命令

• pnpm build -将TypeScript编译为JavaScript
• pnpm watch -观察变化并编译
• pnpm test -运行Vitest单元测试
• pnpm cdk deploy -将基础设施部署到AWS
• pnpm cdk diff -将部署的堆栈与当前状态进行比较
• pnpm cdk synth -生成CloudFormation模板
• pnpm cdk destroy -删除所有AWS资源