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