Cape Fear Alexa+ Surf Guide

A simulated Alexa+ experience that turns a natural-language surf-planning question into calls to the Cape Fear Surf Guide MCP server. It is not an Amazon product or an official Alexa+ client.

The browser has no MCP credential. A short-lived AWS Lambda host uses Amazon Bedrock tool use to select one of two MCP tools over Streamable HTTP 2025-11-25:

1. find_surf_windows retrieves live evidence and returns an immutable decision.

2. explain_surf_window replays the stored decision by window_id; it does not retrieve live conditions again.

The MCP service's deterministic Python policy owns every recommendation and veto. The Bedrock host is only a conversational tool caller and explainer.

Architecture

Browser (text, optional browser speech recognition)
  -> CloudFront / static UI
  -> API Gateway + simulator Lambda
  -> Bedrock Nova tool-use host
  -> MCP 2025-11-25 client
  -> Cape Fear MCP API Gateway
  -> AgentCore / Strands retrieval -> deterministic policy

docs/architecture.md separates the logical safety boundary from the deployed AWS request path. The static site stays available after expiry and shows a closed-demo state; the API Lambda is then disabled independently by its least-privilege circuit-breaker Lambda.

The browser keeps only a short local transcript and the most recent window_id. The Lambda stores no conversation memory, request body, API key, or raw voice audio. Browser speech recognition is optional and may be processed by the browser vendor; text entry remains fully supported.

Related MCP server: delivery-intelligence-mcp

Local development

Python 3.11+ is required for the Lambda package. No API key is committed.

python -m pytest
python -m http.server 8080 --directory web

For a live local backend, set these environment variables outside this repo:

CAPE_FEAR_MCP_URL=https://example.execute-api.us-east-1.amazonaws.com/mcp
CAPE_FEAR_MCP_API_KEY_SECRET_ARN=arn:aws:secretsmanager:...
BEDROCK_MODEL_ID=us.amazon.nova-lite-v1:0

Use infra/simulator.yaml only after approving the AWS account, region, budget email, ExposureId, PublicUntilUtc, MCP endpoint and secret ARN. It creates a bounded judge-demo environment; deployment is intentionally not automatic.

To create the versioned private Lambda artifact locally, use python scripts/package_lambda.py --output dist/simulator.zip. Upload that zip to the approved private artifact bucket and supply its bucket/key to the template. The script never uploads anything.

The simulator remains fail-closed until the separately acknowledged scripts/open_exposure.py creates a one-time DynamoDB permit record. See the deployment runbook for that operational step.

Safety boundary

This is a planning aid, not a guarantee that ocean activity is safe. Check posted flags, lifeguards, and local officials before entering the water.

The host rejects a final answer that lacks a tool-backed immutable decision. It never turns missing evidence into a recommendation, and never changes decision.state, time windows, vetoes, or source timestamps from the MCP result.

Existing-project attribution

This project is a significant follow-on to Cape Fear Surf Guide. It reuses the public live MCP service and its deterministic safety core under the upstream MIT license. New work in this repository includes the standard 2025-11-25 MCP host client, Bedrock conversational host, browser simulator, voice fallback, public-demo controls, tests, and deployment documentation.

See UPSTREAM.md for the exact reuse boundary.