Serverless Mcp

Serverless Mcp

开发 JavaScript

🚀 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
  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 文件。

默认排序 时间排序

0 个评论

« 上一篇
Cloud Run Mcp
下一篇 »
Clever Cloud
  • 0 关注
  • 0 收藏，30 浏览
  • system 提出于 2025-10-05 20:36

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »