# Connect StoreYog to Alexa+

StoreYog exposes one real MCP server at `/mcp`, using the official v1 TypeScript SDK and MCP 2025-11-25 Streamable HTTP. The local simulator consumes that same endpoint. Simulator cards are local web UI; this prototype does not register MCP Apps visual resources for actual Echo Show devices.

## 1. Host the server

Run `npm install && npm run dev (Node 22+)`, or use Docker from the repository root:

```sh
docker build --target mcp -t storeyog-mcp .
docker run --rm --env-file .env -v storeyog-data:/app/.runtime -p 3101:3101 storeyog-mcp
```

On Linux/Docker, lab hostnames must resolve inside the container and be reachable on your LAN. Set the speech/model URLs to routable IP addresses if necessary. Bind a stable public HTTPS hostname to port 3101 through your lab reverse proxy. For an ephemeral development tunnel:

```sh
cloudflared tunnel --url http://localhost:3101
```

Keep that terminal open and append `/mcp` to its HTTPS URL. Only tunnel the MCP service, not the simulator or its microphone/reset routes. Tool execution performs no upstream HTTP calls; measure the public route too because tunnel/network overhead counts toward the 500 ms requirement.

```sh
curl http://localhost:3101/health
MCP_SERVER_URL=https://YOUR-TUNNEL.trycloudflare.com/mcp MCP_API_KEY='<STORE_KEY>' npm run smoke
```

The smoke script calls all four tools, including reconciliation and a draft reorder. It never confirms an order. Reset after testing with `npm run reset-demo`.

## 2. Install the Alexa AI CLI

Verify every step against the current official [development environment setup](https://www.developer.amazon.com/docs/alexaplus/add-ons/set-up-your-development-environment) and [MCP QuickStart](https://www.developer.amazon.com/docs/alexaplus/add-ons/mcp-toolkit-quickstart). Access to Amazon's tooling registry may require onboarding/allowlisting. The current guide specifies Node 24+ for the CLI, while this app supports Node 22+.

After your AWS/CodeArtifact access is configured following the setup guide, authenticate the scoped tooling registry and install:

```sh
aws codeartifact login --tool npm --domain alexa-ai --repository npm-packages \
  --domain-owner 372468808636 --region us-west-2 --namespace @alexa-ai --profile alexa-ai
npm install -g @alexa-ai/cli
alexa-ai --version
alexa-ai configure
```

The AWS profile must be configured for Amazon's granted role access; the code here does not create accounts, assume roles, or change npm configuration for you. `alexa-ai configure --no-browser` is available for a headless host.

## 3. Scaffold, add metadata, deploy

In a separate working directory outside this application's source:

```sh
alexa-ai new mcp --name "StoreYog" --locale en-US \
  --mcp-server-url https://YOUR-PUBLIC-HOST/mcp
cd storeyog
```

Use the actual directory printed by the CLI if it differs. Edit `addon-package/addon.json` with the metadata ideas in [addon-metadata.json](addon-metadata.json), a real privacy policy and terms URL, and the required media assets. This metadata file is inspiration, not a complete deployable manifest. The brief requests five example phrases; the current QuickStart allows 3–4, so select four when filling the manifest.

```sh
alexa-ai deploy
```

Record the returned add-on ID and version. After changing tool descriptions or schemas, update your hosted application, rerun `npm run smoke` against its public URL, update metadata if needed, and run `alexa-ai deploy` again from the add-on project. Use the current CLI help if a deployment schema changes.

## 4. Authentication readiness

The server now includes authorization code OAuth with PKCE S256, protected-resource and authorization-server metadata, exact callback registration, scoped/expiring bearer tokens, rotating refresh tokens and revocation. It uses the official SDK OAuth handlers and Amazon's documented 401 discovery behavior. The public ingress rejects private store API keys and does not mount the console or simulator.

Follow [server deployment and account-linking instructions](SERVER_DEPLOYMENT.md) to configure the public HTTPS issuer/resource and register the exact Alexa callback URI. The private simulator continues using its existing store-scoped API key. Merchant consent uses the store key to identify the store; a production identity-provider login can replace that prototype sign-in later. TLS, developer account access and actual Alexa onboarding/mobile tests are still separate required steps; passing local OAuth tests does not establish certification or Alexa eligibility.

## 5. Test with Alexa+

Follow [Test Your MCP Add-ons](https://www.developer.amazon.com/docs/alexaplus/add-ons/mcp-toolkit-test-add-ons) and the linked current web simulator / physical-device instructions. First validate `tools/list`, all four tools, repeated reconciliation, draft confirmation, and public latency in the MCP Inspector. Deploy the add-on, open Amazon's developer simulator for the returned development-stage add-on, and test a complete conversation.

On a phone, sign into the Alexa app with the same eligible developer/test account, ensure Alexa+ is enabled in a supported locale/marketplace, and enable/select your development add-on using the controls supplied by the current developer console/app. Say “Alexa, ask StoreYog to reconcile my inventory” then approve the exact draft with “yes.” Availability of development add-ons in the mobile app depends on your program access and app version; use Amazon's simulator and supported physical-device routing if the app does not expose it. Do not claim a phone test succeeded until verified with that account/device.

The tool description instructs Alexa to obtain a fresh yes. The local simulator also enforces confirmation in application code. External MCP hosts must enforce their own trusted confirmation experience; a store API key cannot independently prove an owner spoke.