はじめに

May 1, 2026 · View on GitHub

はじめに

spec-driven-presentation-maker をローカル利用から AWS デプロイまで、段階的にセットアップする手順を説明します。

🤖 手動で読み進める必要はありません。 このリポジトリには AGENTS.md と CLAUDE.md を同梱しています。お使いのコーディングエージェント（Claude Code, Codex CLI, Cursor, Kiro, VS Code の GitHub Copilot 等）に、例えば「このリポジトリをセットアップして」「AWS にデプロイして」「Layer 2 として Claude Desktop から使えるようにして」と話しかけてください。エージェントが AGENTS.md を読み取り、適切なレイヤーとコマンドを自動で選んで進めます。

🚀 AWS へのデプロイだけを行いたい場合: 推奨デプロイ手順を参照してください。CloudShell または任意のローカル Linux/macOS から scripts/deploy.sh を実行するだけで、CDK/Docker のローカルインストールなしに Layer 3/4 をデプロイできます。本ページは、Layer 1〜2 のローカル利用や、ローカル CDK を使った開発・デバッグ向けの手順を含みます。

どのレイヤーを使うべきか

Layer 1 — SKILL.md 対応のコーディングエージェント（Claude Code, Codex CLI, Cursor, Kiro, VS Code の GitHub Copilot 等）から使う。Python のみ、MCP や AWS は不要。
Layer 2 — ローカル MCP クライアント（Claude Desktop, Claude Cowork 等）から使う。ローカル stdio MCP 接続、AWS は不要。
Layer 3 — リモート MCP のみ対応のクライアント（Claude.ai Web 版など、ローカルプロセスを起動できないクライアント）から使う。AWS デプロイが必要。
Layer 4 — 同梱のブラウザ Web UI を使う。AWS フルスタックデプロイ。

前提条件

すべてのレイヤーで共通:

Python 3.10 以上
uv パッケージマネージャー

Layer 3〜4 を ローカル CDK で直接デプロイする場合 は追加で以下が必要です（CloudShell デプロイを使う場合は不要）:

AWS アカウント（CDK ブートストラップ済み: cdk bootstrap aws://ACCOUNT_ID/REGION）
Node.js 18 以上
Docker または Finch（コンテナビルド用）
AWS CLI（適切な認証情報を設定済み）

Layer 1: Kiro CLI スキル

最もシンプルな使い方です。skill/ ディレクトリを Kiro CLI のスキルディレクトリにコピーするだけで動作します。

# 依存関係のインストール
cd skill
uv sync

# アイコンのダウンロード（任意、推奨）
uv run python3 scripts/download_aws_icons.py
uv run python3 scripts/download_material_icons.py

# 動作確認
uv run python3 scripts/pptx_builder.py examples

エンジン、リファレンス（デザインパターン・ワークフロー・ガイド）、サンプルテンプレート（dark/light）、SKILL.md がすべて含まれています。

Layer 2: ローカル MCP サーバー

spec-driven-presentation-maker を MCP 対応の任意のクライアントに接続します。AWS アカウントは不要です。

サーバーの起動

cd mcp-local
uv sync
uv run python server.py

MCP クライアントの設定

クライアントの MCP 設定ファイル（claude_desktop_config.json、.vscode/mcp.json 等）に以下を追加します。

{
  "mcpServers": {
    "spec-driven-presentation-maker": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-local", "python", "server.py"]
    }
  }
}

動作確認

エージェントに「プレゼンテーションを作って」と依頼してください。以下のワークフローが自動的に実行されます。

MCP Server Instructions からワークフローファイルを読み取り
トピック・対象者・目的についてヒアリング
ブリーフィング → アウトライン → アートディレクションを設計し、specs/ に永続化
スライドを 1 枚ずつ構築
PPTX を生成し、プレビューを表示

利用可能なツールの一覧はアーキテクチャ — MCP ツール一覧を参照してください。

Layer 3: リモート MCP サーバー（AWS）

spec-driven-presentation-maker を Amazon Bedrock AgentCore Runtime 上のリモート MCP サーバーとしてデプロイします。

💡 AWS へのデプロイは推奨デプロイ手順を推奨します。 scripts/deploy.sh は CloudShell と任意のローカル Linux/macOS から実行でき、CodeBuild 経由でデプロイされるため CDK/Docker のローカルインストールが不要です。本ページ以降の手順はローカル CDK を直接使う開発・デバッグ向けフローです。

設定

cd infra
npm ci
cp config.example.yaml config.yaml

config.yaml を編集して、デプロイするスタックを選択します。

Layer 3 — MCP Server のみ（最小構成）

stacks:
  data: true           # 必須 — DynamoDB + S3
  runtime: true        # 必須 — AgentCore Runtime MCP Server
  agent: false
  webUi: false

features:
  enableInvocationLogging: false  # Bedrock Model Invocation Logging（任意）

デプロイ

# Docker Desktop 使用時
npx cdk deploy --all

# Finch 使用時（Docker Desktop なし）
CDK_DOCKER=finch npx cdk deploy --all

# CI/CD 環境（対話なし）
CDK_DOCKER=finch npx cdk deploy --all --require-approval never

デプロイには 15〜30 分程度かかります。

モデル ID の変更

デフォルトでは global.anthropic.claude-sonnet-4-6 が使用されます。別のモデルを使う場合は infra/config.yaml を編集:

model:
  modelId: "global.anthropic.claude-opus-4-6-v1"

またはデプロイ時にオーバーライド:

npx cdk deploy --all --context modelId=global.anthropic.claude-opus-4-6-v1

デプロイされるスタック（Layer 3）

スタック	リソース
SdpmData	Amazon DynamoDB テーブル、S3 バケット（pptx + リソース）、リファレンスファイルを S3 にデプロイ
SdpmRuntime	Amazon Bedrock AgentCore Runtime エンドポイント、ECR リポジトリ + Docker イメージ、Amazon Cognito M2M 認証

テンプレートの登録

CDK はテンプレートファイルを S3 にデプロイしますが、list_templates で表示するには Amazon DynamoDB への登録が必要です。詳細はカスタムテンプレート — テンプレートの登録（Layer 3）を参照してください。

デプロイの確認

OAuth トークンの取得

TOKEN=$(curl -s -X POST \
  "https://<CognitoDomain>.auth.<region>.amazoncognito.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<M2MClientId>:<M2MClientSecret>" \
  -d "grant_type=client_credentials&scope=sdpm/invoke" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

CognitoDomain、M2MClientId、M2MClientSecret は CDK 出力から取得してください。

tools/list の呼び出し

ENCODED_ARN=$(python3 -c "import urllib.parse; print(urllib.parse.quote('<RuntimeArn>', safe=''))")

curl -X POST \
  "https://bedrock-agentcore.<region>.amazonaws.com/runtimes/${ENCODED_ARN}/invocations?qualifier=DEFAULT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

レスポンスにツール一覧が表示されれば成功です。

Layer 4: フルスタック（AWS）

💡 推奨: Layer 4 のデプロイは推奨デプロイ手順を利用してください（CloudShell と任意のローカル Linux/macOS で動作）。./scripts/deploy.sh --region us-east-1 を実行するだけで、CDK/Docker のローカルインストールは不要です。

config.yaml で agent と webUi を有効にしてデプロイすると、以下が追加されます。

Strands Agent（Amazon Bedrock AgentCore Runtime 上）
React Web UI（チャットインターフェース + デッキプレビュー）
JWT Bearer 認証（デフォルト Amazon Cognito、任意の OIDC IdP に対応）

設定

stacks:
  data: true
  runtime: true
  agent: true          # Strands Agent（AgentCore Runtime 上）
  webUi: true          # React Web UI（S3 + CloudFront）

features:
  enableInvocationLogging: false

npx cdk deploy --all

デプロイされるスタック（Layer 4 追加分）

スタック	リソース
SdpmAuth	Amazon Cognito User Pool、ホスト UI
SdpmAgent	Strands Agent（Amazon Bedrock AgentCore Runtime 上）、ECR イメージ
SdpmWebUi	S3 バケット、Amazon CloudFront ディストリビューション、Amazon API Gateway、Lambda

認証オプション

デフォルト: Amazon Cognito User Pool

agent または webUi を有効にすると、CDK が Amazon Cognito User Pool（ホスト UI 付き）を自動作成します。ユーザーは Web UI からサインインし、JWT がスタック全体に伝播されます。

認証・認可モデルの設計詳細はアーキテクチャ — 認証・認可モデルを参照してください。

外部 OIDC IdP

自社の IdP（Entra ID、Auth0、Okta 等）を使う場合:

AuthStack をスキップするか、Amazon Cognito の Federation 機能で外部 IdP を接続
config.yaml に oidcDiscoveryUrl と allowedClients を設定
Runtime の customJwtAuthorizer が OIDC 準拠の任意の発行者からの JWT を検証

デプロイ後のエンドポイント確認

デプロイスクリプトのログ監視が途中で中断した場合や、後からエンドポイントを確認したい場合は以下を実行してください。

bash scripts/show_endpoints.sh

デプロイ済みの CloudFormation スタックから CloudFront URL と Cognito サインアップ URL を表示します。

Web UI の更新

Web UI のコードを変更した場合、フル CDK デプロイなしで更新できます。

cd web-ui && npm run build && cd ..
bash scripts/deploy_webui.sh

aws-exports.json（認証情報・API エンドポイント等）は CDK の Custom Resource が管理しています。スタック構成を変更した場合は npx cdk deploy SdpmWebUi を実行してください。

オプション機能

WAF IP アドレス制限

config.yaml で waf.allowedIpV4AddressRanges および/または waf.allowedIpV6AddressRanges を設定すると、CloudFront と API Gateway へのアクセスを IP アドレスで制限できます。

waf:
  allowedIpV4AddressRanges:
    - "10.0.0.0/8"
    - "192.168.0.0/16"
  allowedIpV6AddressRanges:
    - "2001:db8::/32"

設定すると、CDK は以下を作成します:

SdpmCloudFrontWaf スタック（us-east-1、WAFv2 CLOUDFRONT スコープの要件）— CloudFront に関連付け
リージョナル WAF（デプロイリージョン）— API Gateway に関連付け

デフォルトアクションは Block で、指定された IP 範囲のみアクセスが許可されます。waf セクションを省略した場合、WAF リソースは作成されません。

⚠️ IPv6 に関する注意: allowedIpV4AddressRanges のみ指定し allowedIpV6AddressRanges を省略した場合、IPv6 によるアクセスはすべてブロックされます。最近のブラウザは IPv6 を優先的に使用するため、IPv4 アドレスが許可されていても Web UI が「Loading authentication configuration...」のまま停止することがあります。デュアルスタック環境では必ず IPv4 と IPv6 の両方を指定してください。

セマンティックスライド検索

Amazon Bedrock Knowledge Bases と Amazon S3 Vectors を用いた、デッキ横断のセマンティック検索を標準機能として提供します。追加の設定は不要です。

カスタムテンプレート・アセット

独自の .pptx テンプレートやアイコンの追加方法はカスタムテンプレートとアセットを参照してください。

注意事項

コスト

コストの詳細はコスト試算を参照してください。開発・検証が終わったら npx cdk destroy --all でリソースを削除してください。

データ保持

DataStack の Amazon DynamoDB テーブルと S3 バケットは RemovalPolicy.RETAIN が設定されています。cdk destroy してもデータは削除されません。手動で削除する必要があります。

トラブルシューティング

Docker ビルドが Finch で失敗する

export CDK_DOCKER=finch

ECR 権限エラーでデプロイが失敗する

Amazon Bedrock AgentCore Runtime が ECR からイメージを取得する際に権限エラーが発生する場合があります。通常は再デプロイで解決します。

npx cdk deploy --all

cd web-ui && npm run build && cd ..
bash scripts/deploy_webui.sh

はじめに

どのレイヤーを使うべきか

前提条件

サーバーの起動

動作確認

設定

デプロイ

テンプレートの登録

デプロイの確認

設定

認証オプション

デプロイ後のエンドポイント確認

オプション機能

セマンティックスライド検索

カスタムテンプレート・アセット

注意事項

コスト

データ保持

トラブルシューティング

関連ドキュメント