# Amazon Ads Simulator MCP

A read-only MCP server for inspecting ad-bid recommendations and comparing explicit business assumptions. Eight tools connect a small TypeScript rules engine to an AI client. The default demo uses four fictional ad targets and needs no account, API key or database.

This portfolio edition contains a reproducible sample of the analysis workflow. It does not connect to Amazon Ads, change bids or demonstrate measured advertising gains.

## Try it

Requires Node.js 22 or later and npm. CI verifies Node.js 24 LTS.

```sh
npm ci
npm run demo
npm test
npm run build
npm start
```

`npm run demo` prints a baseline and a conservative scenario using only in-memory fixtures. The server listens on `http://127.0.0.1:3001`; `GET /health` identifies the data source and `POST /mcp` accepts Streamable HTTP MCP requests. Configure an MCP client with that local endpoint.

Example prompts after connecting: “Explain the decrease recommendation for the fictional sample target” and “Compare the baseline with a 5% maximum increase and a 10% maximum decrease.”

## Tools

| Tool | Purpose |
|---|---|
| `get_dataset_manifest` | Identify sample versus explicitly configured data and row counts |
| `get_current_config` | Inspect the active decision thresholds |
| `get_simulation_summary` | Summarize recommendations and cost ratios |
| `get_backtest_summary` | Explain imported evaluation summaries |
| `list_recommendations` | Filter recommendations by action and evidence level |
| `run_scenario` | Recalculate recommendations and assumption-based forecasts |
| `explain_variable` | Describe the meaning of an input |
| `explain_recommendation` | Explain a row's threshold decision |

## How the calculation works

Rows must meet minimum spend, click and impression thresholds. Eligible rows with no sales can receive a capped bid decrease; rows below or above the target advertising-cost-of-sales bands receive a capped increase or decrease. All other rows are held. Confidence labels reflect evidence-volume rules, not statistical confidence intervals.

Forecast spend and ad sales use user-controlled elasticity assumptions. A conversion-rate adjustment applies to every row, including held bids. A zero total-revenue denominator produces an unavailable ratio rather than infinity. The unused traffic-elasticity input from the earlier implementation is omitted.

The included backtest figures are synthetic. The service reads externally generated evaluation summaries; it is not a historical bid replay engine, a causal experiment or a trained sales predictor.

## Structure

```text
src/app.ts         MCP tools and HTTP application
src/engine.ts      Recommendation rules and scenario arithmetic
src/fixtures.ts    Fictional demonstration records
src/data.ts        Explicit sample, file and database sources
src/access.ts      Authentication boundary for configured data
src/db.ts          Optional PostgreSQL storage adapter
migrations/       Optional database schema
scripts/          Offline demo and explicit database utilities
test/             Rule, data-boundary and HTTP behavior tests
```

## Optional local data and PostgreSQL

Sample mode is the default and ignores ambient `DATABASE_URL` and `SIM_DATA_DIR` settings. To use your own files, explicitly set `SIM_DATA_SOURCE=files`, `SIM_DATA_DIR` and a locally generated `MCP_ACCESS_TOKEN` of at least 32 characters. Files use the schemas in `src/types.ts` and the names `bid_simulation_targeting_current_results.json` and `bid_simulation_backtest_results.json`.

For PostgreSQL, set `SIM_DATA_SOURCE=database`, `DATABASE_URL` and the same token requirement. `npm run db:migrate` and `npm run db:import` are explicit database-write utilities; the HTTP MCP tools remain read-only. The import utility also requires `SIM_DATA_DIR`. These commands are not part of the demo or CI.

Send `Authorization: Bearer <your locally generated token>` for every HTTP request when a token is configured. Missing or short tokens prevent non-sample startup. TLS certificate verification is required for remote PostgreSQL; `PGSSLMODE=disable` is accepted only for loopback hosts. Use HTTPS in front of any remotely served authenticated endpoint.

Keep your data files and credentials outside version control. This repository includes no real campaign exports, account identifiers or deployment configuration. The service does not automatically load a dotenv file or local AI-client credentials. Raw adapter errors, local paths and database identifiers are excluded from HTTP error/manifest responses.

## Validation and limits

`npm test` checks recommendation boundaries, zero-sales behavior, bid caps, denominator handling, default-data isolation, bearer authentication and real MCP calls against a loopback server. `npm run build` performs the TypeScript build. Optional PostgreSQL connectivity is not covered by the offline test suite.

## Licensing and attribution

No new source-code license is granted with this portfolio edition. Dependency licenses remain with their respective authors. Amazon and Amazon Ads are referenced descriptively; this project is not affiliated with Amazon.