# Run a sandbox campaign — AdBuyMCP

Start locally, inspect the contracts and exercise a complete campaign without supplier credentials or real spend.

## Start the isolated demo

The repository runs without AI, payment or supplier credentials. Its deterministic sandbox is a way to evaluate the buying workflow; simulated delivery does not establish supplier access or audience availability.

Use the repository demo script so the dashboard is built for the API port it will call. The default demo serves the API on port 4737 and the dashboard on port 3737. Use a separate terminal for MCP.

~~~bash
pnpm install
./scripts/demo.sh

# Separate terminal, from the repository root:
CHORUS_API_URL=http://localhost:4737 pnpm --filter @adp/mcp start:http
~~~

## Inspect before acting

Read platform identity and the public tool contracts first. These requests neither create a campaign nor reserve funds. API paths include /api/v1; the MCP server is a separate process.

~~~bash
curl --fail http://localhost:4737/api/v1/meta
curl --fail http://localhost:4737/api/v1/openapi.json
curl --fail http://localhost:4200/capabilities
~~~

## Create a persona through the API

Local AUTH_MODE=disabled uses the seeded development advertiser. Public deployments require an authenticated tenant identity; never expose development authentication on a public host.

The extracted persona keeps unrepresented constraints visible. Preserve the returned persona ID and inspect its compiled targeting before planning.

~~~bash
curl --fail-with-body http://localhost:4737/api/v1/personas/extract \
  -H 'Content-Type: application/json' \
  -d '{"nlBrief":"UK adults interested in hiking in Manchester"}'
~~~

## Try the MCP SDK draft example

This executable example connects over stdio to the actual MCP server and local API, checks that suppliers are sandbox-only, and creates a persona and draft plan. It does not approve, fund or launch a campaign.

~~~bash
CHORUS_API_URL=http://localhost:4737 pnpm --filter @adp/mcp example:sandbox adbuymcp
~~~

## Complete the buyer journey

- Create a plan with the persona, GBP budget, permitted channels and flight dates. Review modeled reach, native targeting gaps and supplier readiness.
- Upload real creative bytes, or review a separate AI production quote. Select same-channel creative and check the campaign readiness response.
- Review and approve the exact campaign action. MCP agents must prepare an action, obtain human approval, create the execution step and use the returned step ID and digest.
- Submit the retained booking request key or stage a supported native campaign. A booking waits for a human-recorded supplier outcome; a staged native hierarchy needs separate review and resume authority.
- Read delivery and measurement, request a stop, and reconcile the final outcome. A timeout or overdue booking does not prove acceptance, cancellation or released funds.

## Executable end-to-end MCP example

This repository test drives the actual MCP SDK and HTTP API through all three products: persona, plan, approvals, creative upload, wallet, booking and replay, supplier confirmation, delivery, measurement and stop.

It creates an isolated database and test identities, and runs only sandbox suppliers. The fixture human deliberately provides approvals; this is not a way for a production agent to grant itself authority.

~~~bash
pnpm build
pnpm --filter @adp/api exec vitest run src/mcp-buyer-journey.integration.test.ts --maxWorkers=2
~~~