# 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](https://github.com/yoonsoo-park/cape-fear-surf-guide).
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

```text
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.

## Local development

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

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

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

```text
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](UPSTREAM.md) for the exact reuse boundary.