Getting Started

May 27, 2026 · View on GitHub

Getting Started

Step-by-step instructions for setting up spec-driven-presentation-maker, from local usage to AWS deployment.

🤖 You don't need to read this page manually. This repo ships with AGENTS.md and CLAUDE.md. Just tell your coding agent (Claude Code, Codex CLI, Cursor, Kiro, GitHub Copilot in VS Code, etc.) what you want — for example, "Set up this repo," "Deploy it to AWS," or "Wire it up so I can use it from Claude Desktop as Layer 2." The agent will read AGENTS.md, pick the right layer, and run the right commands for you.

🚀 Deploying to AWS only? Use the One-Click Deploy — just sign in to the AWS Console, click the Launch Stack button, and fill in the parameters. For advanced customization (external IdP, WAF, config.yaml), you can also use CloudShell deploy. This page covers Layer 1–2 local usage and direct-CDK workflows for development and debugging.

Which Layer Do I Need?

Layer 1 — Use from a SKILL.md-compatible coding agent (Claude Code, Codex CLI, Cursor, Kiro, GitHub Copilot in VS Code, etc.). Python only, no MCP or AWS.
Layer 2 — Use from a local MCP client (Claude Desktop, Claude Cowork, etc.). Local stdio MCP, no AWS.
Layer 3 — Use from a remote-only MCP client (Claude.ai web, etc. — clients that cannot spawn local processes). AWS deployment required.
Layer 4 — Use the included browser Web UI. AWS full-stack deployment.

Prerequisites

Common to all layers:

Python 3.10+
uv package manager

Additional requirements for deploying Layer 3–4 with local CDK directly (not needed when using the CloudShell deploy path):

AWS Account (CDK bootstrapped: cdk bootstrap aws://ACCOUNT_ID/REGION)
Node.js 18+
Docker or Finch (for container builds)
AWS CLI with appropriate credentials configured

Layer 1: Kiro CLI Skill

The simplest way to use spec-driven-presentation-maker. Copy the skill/ directory to your Kiro CLI skills directory.

# Install dependencies
cd skill
uv sync

# Download icons (optional, recommended)
uv run python3 scripts/download_aws_icons.py
uv run python3 scripts/download_material_icons.py

# Verify
uv run python3 scripts/pptx_builder.py examples

The engine, references (design patterns, workflows, guides), sample templates (dark/light), and SKILL.md are all included.

Layer 2: Local MCP Server

Connect spec-driven-presentation-maker to any MCP-compatible client. No AWS account required.

Start the Server

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

Configure Your MCP Client

Add to your client's MCP configuration file (claude_desktop_config.json, .vscode/mcp.json, etc.):

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

Verify

Ask your agent to "create a presentation." The following workflow runs automatically:

Reads workflow files via MCP Server Instructions
Interviews you about topic, audience, and purpose
Designs briefing → outline → art direction, persisted to specs/
Builds slides one by one
Generates PPTX and shows a preview

For the full tool list, see Architecture — MCP Tool Reference.

Layer 3: Remote MCP Server (AWS)

Deploy spec-driven-presentation-maker as a remote MCP server on Amazon Bedrock AgentCore Runtime.

💡 The Recommended Deploy Guide is the recommended path for AWS deployments. scripts/deploy.sh runs from CloudShell and from any local Linux/macOS environment, and builds via CodeBuild — so you don't need CDK or Docker installed locally. The instructions below cover the direct local CDK workflow, mainly used for development and debugging.

Configuration

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

Edit config.yaml to select which stacks to deploy.

Layer 3 — MCP Server Only (Minimum)

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

features:
  enableInvocationLogging: false  # Bedrock Model Invocation Logging (optional)

Deploy

# With Docker Desktop
npx cdk deploy --all

# With Finch (no Docker Desktop)
CDK_DOCKER=finch npx cdk deploy --all

# Non-interactive (CI/CD)
CDK_DOCKER=finch npx cdk deploy --all --require-approval never

Deployment takes approximately 15–30 minutes.

Changing the Model ID

The default model is global.anthropic.claude-sonnet-4-6. To use a different model, edit infra/config.yaml:

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

Or override at deploy time:

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

Deployed Stacks (Layer 3)

Stack	Resources
SdpmData	Amazon DynamoDB table, S3 buckets (pptx + resources), reference files deployed to S3
SdpmRuntime	Amazon Bedrock AgentCore Runtime endpoint, ECR repository + Docker image, Amazon Cognito M2M auth

Template Registration

CDK deploys template files to S3, but Amazon DynamoDB registration is required for list_templates to work. See Custom Templates — Registering Templates (Layer 3) for details.

Verify Deployment

Get an OAuth Token

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'])")

Find CognitoDomain, M2MClientId, and M2MClientSecret in the CDK outputs.

Call 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}'

A tool list in the response confirms success.

Layer 4: Full Stack (AWS)

💡 Recommended path: Deploy Layer 4 via the Recommended Deploy Guide (works from CloudShell and any local Linux/macOS). Just run ./scripts/deploy.sh --region us-east-1 — no local CDK/Docker needed.

Enable agent and webUi in config.yaml to add:

Strands Agent on Amazon Bedrock AgentCore Runtime
React Web UI (chat interface + deck preview)
JWT Bearer authentication (Amazon Cognito default, any OIDC IdP supported)

Configuration

stacks:
  data: true
  runtime: true
  agent: true          # Strands Agent on AgentCore Runtime
  webUi: true          # React Web UI (S3 + CloudFront)

features:
  enableInvocationLogging: false

npx cdk deploy --all

Deployed Stacks (Layer 4 additions)

Stack	Resources
SdpmAuth	Amazon Cognito User Pool, hosted UI
SdpmAgent	Strands Agent on Amazon Bedrock AgentCore Runtime, ECR image
SdpmWebUi	S3 bucket, Amazon CloudFront distribution, Amazon API Gateway, Lambda

Authentication Options

Default: Amazon Cognito User Pool

When agent or webUi is enabled, CDK automatically creates a Amazon Cognito User Pool with hosted UI. Users sign in via the web UI, and the JWT is propagated through the stack.

For authentication and authorization model details, see Architecture — Authentication and Authorization Model.

External OIDC IdP

To use your own IdP (Entra ID, Auth0, Okta, etc.):

Skip the AuthStack or configure your IdP as a Amazon Cognito federation source
Set oidcDiscoveryUrl and allowedClients in config.yaml
The Runtime's customJwtAuthorizer validates JWTs from any OIDC-compliant issuer

Checking Endpoints After Deployment

If the deploy script's log monitoring was interrupted, or you need to check the endpoints later, run:

bash scripts/show_endpoints.sh

This displays the CloudFront URL and Cognito sign-up URL from the deployed CloudFormation stacks.

Updating the Web UI

To update the Web UI without a full CDK deployment:

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

aws-exports.json (auth info, API endpoints, etc.) is managed by a CDK Custom Resource. If you change the stack configuration, run npx cdk deploy SdpmWebUi.

Optional Features

WAF IP Address Restriction

Set waf.allowedIpV4AddressRanges and/or waf.allowedIpV6AddressRanges in config.yaml to restrict access to CloudFront and API Gateway by IP address.

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

When configured, CDK creates:

SdpmCloudFrontWaf stack in us-east-1 (WAFv2 CLOUDFRONT scope requirement) — attached to CloudFront
Regional WAF in the deploy region — attached to API Gateway

Default action is Block — only the listed IP ranges are allowed. When the waf section is omitted, no WAF resources are created.

⚠️ IPv6 Note: If you specify only allowedIpV4AddressRanges without allowedIpV6AddressRanges, all IPv6 access is blocked. Modern browsers often prefer IPv6 when available, which can cause the Web UI to hang on "Loading authentication configuration..." even if your IPv4 address is allowed. Always specify both IPv4 and IPv6 ranges if your network uses dual-stack.

Semantic Slide Search

Cross-deck semantic search is provided out of the box, backed by Amazon Bedrock Knowledge Bases and Amazon S3 Vectors. No extra configuration is needed.

Custom Templates and Assets

For adding custom .pptx templates and icons, see Custom Templates and Assets.

Important Notes

Cost

See Cost Estimates for details. Delete resources with npx cdk destroy --all when done with development/testing.

Data Retention

DataStack's Amazon DynamoDB table and S3 buckets have RemovalPolicy.RETAIN. Data is not deleted by cdk destroy — manual deletion is required.

Troubleshooting

Docker build fails with Finch

export CDK_DOCKER=finch

ECR permission error during deploy

Amazon Bedrock AgentCore Runtime may encounter permission errors when pulling ECR images. This typically resolves on re-deploy:

npx cdk deploy --all

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

Architecture — 4-layer design, data flow, auth model
Custom Templates — Adding templates and assets
Connecting Agents — MCP client connection guide