Market Mirror

---
name: market-mirror
description: Analyze real ad data, research markets, survey simulated buyers, and test campaigns, pricing, sales pitches, and product journeys through MarketMirror MCP tools or the local CLI.
---

# MarketMirror

MarketMirror is your agent's marketing research and simulation lab. Analyze observed campaign performance, research customer feedback, survey and interview simulated buyers, compare campaigns and pricing, rehearse sales conversations, and test actual product URLs with synthetic visitors. Use the bundled MCP tools in any compatible agent, or `scripts/mm.sh cli ...` when MCP is unavailable. `doctor` checks the local engine; `setup` installs it if needed. `mm.sh home` shows the engine path. A checkout can be used directly with `MARKET_MIRROR_HOME` set to its absolute path.

## Bring your agent's data

When the calling agent has authorized advertising, analytics, CRM, or survey tools, use those tools to fetch relevant records. Pass exported CSV/JSON to `actuals_import` or `ads_import`; `ideas` also accepts ad rows directly from a connected ads tool. `ad_patterns` labels a library of real ads (yours or, with the owner's permission, competitors' from the Meta Ad Library) on seven creative dimensions; report its 60+ day shares as observational real-ad patterns, never as performance, and keep its simulated rows apart; with `vision` it reads each ad's image or video first. Give feed-test creatives their real `image` or `video` so the simulated buyers react to the picture, not a description, and use `creative_check` for a pre-flight look (what it shows, brand and CTA visibility, platform checks, measured aspect ratio); describe those checks as a model's reading, not an attention or recall measurement. Retain the source, reporting period, market, metric definitions, and currency. Report missing access or fields and use supplied exports where available. MarketMirror does not automatically connect accounts or expand the agent's permissions. When the host has official ads, analytics or CRM servers connected (Meta Ads, Google Ads, GA4, TikTok Ads, HubSpot, Klaviyo, Shopify), the `pull_real_results` prompt is the recipe: fetch the real results with those tools, keep the date range, market and currency, normalise them through `actuals_import`, then `backtest` or `holdout_backtest`. Never change an ad account; a winning variant becomes a paused draft only after the owner approves it explicitly. Run files are also MCP resources (`marketmirror://runs/<run>/<file>`), and hosts with MCP Apps show the dashboard inline after `results`. Hosts that support MCP tasks get long tools as tasks to poll instead of `job_status`; hosts with elicitation show the user the planned people and a rough cost before a `market_test` spends, and the user's answer decides whether it runs. Report that cost as a rough estimate. When the host has official ads, analytics or CRM servers connected (Meta Ads, Google Ads, GA4, TikTok Ads, HubSpot, Klaviyo, Shopify), the `pull_real_results` prompt is the recipe: fetch the real results with those tools, keep the date range, market and currency, normalise them through `actuals_import`, then `backtest` or `holdout_backtest`. Never change an ad account; a winning variant becomes a paused draft only after the owner approves it explicitly. Run files are also MCP resources (`marketmirror://runs/<run>/<file>`), and hosts with MCP Apps show the dashboard inline after `results`. Its surveys interview simulated personas; imported human survey responses remain separate real evidence. With the owner's permission, `intake` turns their own customer material (call transcripts, reviews, NPS verbatims, CRM notes) into grounded personas: contact details are removed locally, quotes stay verbatim and unstated facts stay empty. Show the owner `intake.md` before the run, and describe grounded people as a small, self-selected real sample next to the synthetic audience. After a run, `ask_buyers` lets the owner question one saved persona or hold a moderated focus group; quote the private before/after verdicts and the conformity flag rather than the group's apparent consensus, and present it as qualitative exploration.

For a real product URL, use `website_test` on prepared personas. The optional browser extra drives isolated Chromium sessions; agents can inspect the product, use the cart, reach signup or checkout, or leave. Supply named DOM checks and `goal_check` to verify outcomes independently. Account submission needs explicit opt-in and owned test identities; never submit payments or orders. Start with 1–3 visitors and review screenshots, traces, deliberate departures and execution failures separately. See `docs/WEBSITE_TESTING.md` in the engine checkout. Observed actions are synthetic visitor behavior, not measured human conversion.

## Workflow

1. `understand` product documents or an existing project. Read the resulting `product_profile.json`, including unknowns. `research` public feedback; retain cited URL, date, market and quality, and state blocked sources.
2. `actuals_import` existing ads, email, website, CRM and survey CSV/JSON exports. Map columns explicitly and resolve validation errors. The old `ads_import` tool remains available for ad-specific seed files and benchmarks.
3. `campaign_plan` takes a profile or project, goal, budget and optional channels. Review audiences, positioning, funnel metrics, allocations, proof gaps and the runnable `test_specs`. The plan is a draft; supplied claims need verification.
4. `run_test` evaluates a relevant spec on prepared simulated buyers. For a controlled scenario comparison, use `study` with one simulation and the same seed list across variants. Poll `job_status`; finished cells resume on rerun. Search and organic content and referrals use a concept survey, lifecycle messages use the inbox engine, and sales outreach uses pitch rehearsal. Their simulated outcomes are not actual channel performance.
5. `backtest` past ads and `holdout_backtest` independent real experiments. The latter compares the persona estimate against a no-persona training-mean baseline. An uncalibrated `predict` result is directional. A predictive claim needs held-out evidence that beats the baseline; otherwise label the conclusion exploratory.
6. Open `results` and the saved dashboard, check the evidence and report paths, then recommend the next small real randomized test. Every exported run has `real_check.md` and `real_check.csv` next to the dashboard (the "Check with real people" download): the questions that decided the verdict, who to ask, how many, and a blank answers sheet. Hand them to the owner; when the answers are back, run `calibrate --real real_check.csv`. If the evidence grade says most people are in markets the models represent less well, say so and suggest grounding with local customer data (`intake`) or a small real test in that market. Record audience, exposure, assignment, outcome, date, market and source. MarketMirror does not send campaigns or change ad accounts.

## Setup and access

`bash scripts/mm.sh setup` installs the engine with `uv`; `bash scripts/mm.sh doctor` checks it. Choose an API-key or local-model provider, the documented eligible-user Sign in with ChatGPT option when configured, or a local `codex exec` / Claude CLI gateway. Run the backend with `bash scripts/mm.sh start`. The MCP server defaults to stdio: `bash scripts/mm.sh mcp`. To serve authenticated loopback MCP, provide a private bearer-token file: `bash scripts/mm.sh mcp --http --port 5061 --token-file /private/path/token`. Never commit or print tokens or API keys.

Use `provider_setup` with `action:list` for official provider guides, `action:status` for masked configuration, and `action:check` for model discovery without an inference call. For hosted keys, direct the user to `mm.sh configure` in their own terminal (hidden input), or use a pre-existing environment variable through `key_env`. API keys must never be supplied in chat or tool arguments. Ollama and LM Studio support local use without a hosted API key; confirm the selected local model supports tools and structured output on a small fixture.

Large simulations can consume substantial model calls. Review the intended audience and estimated work before running, and suggest a hard cap: `max_spend_usd` in the `market_test` config stops new model calls once the estimated spend (token usage at list prices) reaches it, keeps the partial results, and reports `spend_cap` (spent, limit, whether it was reached) in the result and in `spend_cap.json`. Call it an estimate, not an invoice: calls already running finish, so spend can go slightly past the cap. One capped run at a time per server; if a capped run was killed, `cli spend-cap --clear` lifts its cap. To show someone results before they install anything, point to the example gallery (https://darkworldcoder.github.io/market-mirror/gallery/). Report measured calls, time and costs separately from estimates. Do not call simulated buyer comments real customer quotes. For focused workflows, use the bundled `research`, `planning`, `testing`, and `evidence-review` skills.