Serverless MCP

🚀 Serverless MCP

このプロジェクトは、AWS Lambda、CloudFront、Cognito認証を使用した、Model Context Protocol (MCP) のサーバーレス実装です。OAuth 2.0認証付きでMCPサーバーをクラウド上でホストするための完全なインフラストラクチャを提供します。JSON-RPC 2.0メッセージ形式でServer-Sent Eventsを介したリアルタイムストリーミングと、スケーラブルなサーバーレスアーキテクチャを備えています。この実装には、OAuth 2.0 Authorization Server Metadata (RFC 8414)、OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591)、およびOAuth 2.0 Protected Resource Metadata (RFC 9728) をサポートするRFC準拠のOAuth 2.0が含まれています。公式のModel Context Protocol TypeScript SDKと互換性のあるカスタムトランスポート実装を特徴としています。

✨ 主な機能

• MCPプロトコル実装：Model Context Protocolをツールとリソースで完全にサポート
• サーバーレスアーキテクチャ：CloudFront配信を伴うAWS Lambda関数
• OAuth 2.0認証：AWS Cognitoを使用したセキュアな認証
• リアルタイムストリーミング：ライブ通信のためのServer-Sent Events (SSE) サポート
• セッション管理：ステートフルおよびステートレスなセッションハンドリング
• カスタムドメイン：SSL証明書とRoute 53 DNS設定
• GitHub Actionsデプロイメント：OIDCベースのCI/CDパイプライン

📦 インストール

前提条件

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

高度な使用法

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

📚 ドキュメント

アーキテクチャ

このプロジェクトは2つの主要なCDKスタックで構成されています：

1. ServerlessMcpStack：Lambda関数、CloudFront配信、Cognitoユーザープール、およびDynamoDBテーブルを含むコアインフラストラクチャ
2. GitHubOidcStack：安全なデプロイメントのためのGitHub Actions OIDCプロバイダー

開発

ビルドとテスト

# プロジェクトをビルドする
pnpm build

# 開発中に変更を監視する
pnpm watch

# テストを実行する
pnpm test

# ウォッチモードでテストを実行する
pnpm test:watch

# UI付きでテストを実行する
pnpm test:ui

コード品質

# コードをリントする
pnpm lint

# リントエラーを修正する
pnpm lint:fix

# コードをフォーマットする
pnpm format

# フォーマットをチェックする
pnpm format:check

デプロイメント

前提条件

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デプロイメント

このプロジェクトには、自動デプロイメントのための3つのGitHub Actionsワークフローが含まれています：

1. 継続的インテグレーションとデプロイメント (ci.yml)
   • トリガー：main ブランチへのプッシュとプルリクエスト
   • ジョブ：
     • CIパイプライン：すべてのプッシュとPRでビルド、リント、およびテストを実行します。
     • 自動デプロイメント：main ブランチに変更がプッシュされたときにAWSにデプロイします。
   • 環境：AWS_ACCOUNT 変数を持つ development 環境を使用します。
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リポジトリに移動し、Settings → Environments をクリックします。
   • 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ツール

サーバーは以下の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"
  }
}

• 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_and_usage_comparisons：2つの期間のコストを比較します。

{
  "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：動的な挨拶リソース
  • テンプレート：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);

🔧 技術詳細

構成

環境固有の設定

config/ ディレクトリに環境固有の構成ファイルを作成します：

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

CDKコンテキスト

cdk.json を変更して、CDKの機能フラグと動作を調整します。

監視とデバッグ

• CloudWatchログ：Lambda関数のログは自動的にCloudWatchに送信されます。
• AWS X-Ray：パフォーマンス監視のために分散トレーシングが有効になっています。
• メトリクス：AWS Lambda Powertoolsを使用してカスタムメトリクスが収集されます。

セキュリティ

• 認証：AWS Cognitoを使用したOAuth 2.0
• HTTPS：すべてのトラフィックがSSL/TLSで暗号化されています。
• IAM：最小限の権限アクセスポリシー
• セッション管理：検証付きの安全なセッションハンドリング

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature/new-feature
3. 変更を加え、テストを追加します。
4. リントとテストを実行します：pnpm lint && pnpm test
5. 変更をコミットします：git commit
6. プッシュしてプルリクエストを作成します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。

🛠️ サポート

問題や質問については：

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リソースを削除します。