Serverless MCP

🚀 Serverless MCP

Serverless MCP 是一个基于 AWS Lambda、CloudFront 和 Cognito 认证的 Model Context Protocol (MCP) 无服务器实现方案。该项目借助 OAuth 2.0 认证，通过 Server-Sent Events 实现实时流式传输，并采用 JSON-RPC 2.0 消息格式，为在云端托管 MCP 服务器提供了完整的基础设施，同时具备可扩展的无服务器架构。此实现支持符合 RFC 标准的 OAuth 2.0，涵盖 OAuth 2.0 授权服务器元数据（RFC 8414）、OAuth 2.0 动态客户端注册协议（RFC 7591）和 OAuth 2.0 受保护资源元数据（RFC 9728），还拥有与官方 Model Context Protocol TypeScript SDK 兼容的自定义传输实现。

✨ 主要特性

• MCP 协议实现：全面支持 Model Context Protocol，提供相关工具和资源。
• 无服务器架构：采用 AWS Lambda 函数和 CloudFront 分发服务。
• OAuth 2.0 认证：利用 AWS Cognito 实现安全认证。
• 实时流式传输：支持 Server-Sent Events (SSE) 进行实时通信。
• 会话管理：具备有状态和无状态会话处理能力。
• 自定义域名：支持 SSL 证书和 Route 53 DNS 配置。
• GitHub Actions 部署：基于 OIDC 的 CI/CD 管道。

🏗️ 架构

项目包含两个主要的 CDK 堆栈：

1. ServerlessMcpStack：核心基础设施，包括 Lambda 函数、CloudFront 分发、Cognito 用户池和 DynamoDB 表。
2. GitHubOidcStack：用于安全部署的 GitHub Actions OIDC 提供程序。

📦 安装指南

前提条件

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

安装步骤

1. 克隆仓库：

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

2. 安装依赖：

pnpm install

3. 在 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',
};

💻 使用示例

基础用法

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);

高级用法

本项目提供了多个 AWS Cost Explorer 工具的使用示例，以下是部分工具的调用示例：

get_today_date

获取当前日期，用于相对日期查询：

{
  "name": "get_today_date"
}

get_dimension_values

获取 AWS Cost Explorer 维度（如 SERVICE、REGION 等）的可用值：

{
  "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"
  }
}

📚 详细文档

配置

特定环境设置

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

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

CDK 上下文

修改 cdk.json 以调整 CDK 功能标志和行为。

监控与调试

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

安全

• 认证：采用 OAuth 2.0 和 AWS Cognito 进行认证。
• HTTPS：所有流量通过 SSL/TLS 加密。
• IAM：使用最小权限访问策略。
• 会话管理：安全的会话处理和验证。

贡献

1. 分叉仓库。
2. 创建功能分支：git checkout -b feature/new-feature。
3. 进行更改并添加测试。
4. 运行代码检查和测试：pnpm lint && pnpm test。
5. 提交更改：git commit。
6. 推送并创建拉取请求。

支持

若遇到问题或有疑问：

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 资源。

🔧 技术细节

部署

前提条件

1. 确保已配置 AWS 凭证。
2. 验证域名已注册且托管区域 ID 正确。
3. 构建项目：pnpm build。

手动部署

# 部署两个堆栈
pnpm cdk deploy --all

# 部署特定堆栈
pnpm cdk deploy serverless-mcp
pnpm cdk deploy serverless-mcp-github-oidc

# 预览更改
pnpm cdk diff

# 生成 CloudFormation 模板
pnpm cdk synth

GitHub Actions 部署

本项目包含三个 GitHub Actions 工作流用于自动化部署：

1. 持续集成和部署 (ci.yml)
   • 触发条件：推送到 main 分支和拉取请求。
   • 作业：
     • CI 管道：在所有推送和 PR 上运行构建、代码检查和测试。
     • 自动部署：当更改推送到 main 时部署到 AWS。
   • 环境：使用 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

2. 配置 GitHub 环境：
   • 进入 GitHub 仓库 → 设置 → 环境。
   • 创建 development 环境。
   • 添加环境变量：AWS_ACCOUNT 并设置为你的 AWS 账户 ID。
3. 验证部署：
   • GitHub OIDC 堆栈会创建一个 IAM 角色：github-actions-role。
   • 该角色具备 CDK 部署所需的权限。
   • 无需在 GitHub 密钥中使用长期有效的 AWS 凭证。

部署流程

自动部署

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

手动部署

1. 进入 GitHub 仓库的 Actions 标签页。
2. 选择“manual deploy”工作流。
3. 在 main 分支上点击“Run workflow”。

监控部署

• GitHub Actions：在 Actions 标签页查看工作流运行情况。
• AWS CloudFormation：在 AWS 控制台检查堆栈状态。
• CloudWatch：监控 Lambda 函数日志和指标。

使用

MCP 服务器端点

部署后，MCP 服务器将在以下地址可用：

• 主端点：https://your-domain.com/mcp
• 认证：https://auth.your-domain.com

可用 MCP 资源

• greeting：动态问候资源
  • 模板：greeting://[name]
  • 示例：greeting://world 返回 "Hello, 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);

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。