shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

serverless-mcp

一个基于AWS Lambda、CloudFront和Cognito认证的无服务器MCP协议实现项目，提供完整的云端MCP服务器基础设施，支持OAuth 2.0认证、实时流传输和可扩展架构。

article

README

🚀 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 提供程序。

serverless-mcp 架构

📦 安装指南

前提条件

  • 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',
};

💻 使用示例

基础用法

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
  1. 配置 GitHub 环境：
    • 进入 GitHub 仓库 → 设置 → 环境。
    • 创建 development 环境。
    • 添加环境变量：AWS_ACCOUNT 并设置为你的 AWS 账户 ID。
  2. 验证部署：
    • 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 文件。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client