marketmirror 0.4.2__tar.gz

marketmirror-0.4.2/.gitignore

@@ -0,0 +1,2 @@
+src/marketmirror/_server/
+dist/

marketmirror-0.4.2/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: marketmirror
+Version: 0.4.2
+Summary: MCP server that tests ads, prices, emails and sales pitches on simulated buyers and returns a go / iterate / no-go report.
+Project-URL: Homepage, https://github.com/DarkWorldCoder/market-mirror
+Project-URL: Demo, https://darkworldcoder.github.io/market-mirror/demo/
+Project-URL: Issues, https://github.com/DarkWorldCoder/market-mirror/issues
+Author: Ayush Niroula
+License-Expression: AGPL-3.0-only
+Keywords: ad-testing,agents,llm,market-research,marketing,mcp,mcp-server,simulation,synthetic-users
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# MarketMirror MCP server
+
+<!-- mcp-name: io.github.DarkWorldCoder/market-mirror -->
+
+MarketMirror tests marketing and sales decisions on simulated buyers before you spend money on real ones. It builds
+interviewed buyer personas, shows them your ads in simulated social feeds, runs a buyer survey and a sales-pitch
+rehearsal, and writes a go / iterate / no-go report with an offline HTML dashboard. Results are simulated and labelled
+as such; `backtest` and `calibrate` compare them with your real ad and survey results.
+
+This package is the MCP server (Python standard library only). Add it to any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "market-mirror": { "command": "uvx", "args": ["marketmirror"] }
+  }
+}
+```
+
+Then ask your agent to run `doctor`, and `setup` to install the MarketMirror engine (Git, Bash and
+[uv](https://docs.astral.sh/uv/) required; Linux, macOS or WSL). Choose a model provider in your own terminal with the
+engine's `./mm configure`; never paste API keys into a chat.
+
+- Repository, docs and full install guide: https://github.com/DarkWorldCoder/market-mirror
+- Live demo (a 2,999-person simulated run, no install): https://darkworldcoder.github.io/market-mirror/demo/
+- License: AGPL-3.0

marketmirror-0.4.2/README.md

@@ -0,0 +1,26 @@
+# MarketMirror MCP server
+
+<!-- mcp-name: io.github.DarkWorldCoder/market-mirror -->
+
+MarketMirror tests marketing and sales decisions on simulated buyers before you spend money on real ones. It builds
+interviewed buyer personas, shows them your ads in simulated social feeds, runs a buyer survey and a sales-pitch
+rehearsal, and writes a go / iterate / no-go report with an offline HTML dashboard. Results are simulated and labelled
+as such; `backtest` and `calibrate` compare them with your real ad and survey results.
+
+This package is the MCP server (Python standard library only). Add it to any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "market-mirror": { "command": "uvx", "args": ["marketmirror"] }
+  }
+}
+```
+
+Then ask your agent to run `doctor`, and `setup` to install the MarketMirror engine (Git, Bash and
+[uv](https://docs.astral.sh/uv/) required; Linux, macOS or WSL). Choose a model provider in your own terminal with the
+engine's `./mm configure`; never paste API keys into a chat.
+
+- Repository, docs and full install guide: https://github.com/DarkWorldCoder/market-mirror
+- Live demo (a 2,999-person simulated run, no install): https://darkworldcoder.github.io/market-mirror/demo/
+- License: AGPL-3.0

marketmirror-0.4.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "marketmirror"
+version = "0.4.2"
+description = "MCP server that tests ads, prices, emails and sales pitches on simulated buyers and returns a go / iterate / no-go report."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "AGPL-3.0-only"
+authors = [{ name = "Ayush Niroula" }]
+keywords = ["mcp", "mcp-server", "marketing", "market-research", "synthetic-users", "simulation", "ad-testing", "llm", "agents"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: POSIX",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Office/Business",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/DarkWorldCoder/market-mirror"
+Demo = "https://darkworldcoder.github.io/market-mirror/demo/"
+Issues = "https://github.com/DarkWorldCoder/market-mirror/issues"
+
+[project.scripts]
+marketmirror = "marketmirror.cli:main"
+marketmirror-mcp = "marketmirror.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/marketmirror"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/marketmirror/_server" = "marketmirror/_server"
+
+[tool.hatch.build.targets.sdist.force-include]
+"src/marketmirror/_server" = "src/marketmirror/_server"

marketmirror-0.4.2/src/marketmirror/__init__.py

@@ -0,0 +1 @@
+"""MarketMirror MCP server, packaged for uvx/pip. The server itself lives in plugin/skills/market-mirror/scripts."""

marketmirror-0.4.2/src/marketmirror/_server/job_worker.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Detached MCP job worker that persists a terminal status after server restarts."""
+
+import json
+import os
+import subprocess
+import sys
+import time
+
+
+def write(path, data):
+    temp = path + ".tmp"
+    with open(temp, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False)
+    os.replace(temp, path)
+
+
+def main():
+    mm, meta_path, out_path, log_path, *args = sys.argv[1:]
+    with open(meta_path, encoding="utf-8") as f:
+        meta = json.load(f)
+    try:
+        with open(out_path, "w", encoding="utf-8") as out, open(log_path, "w", encoding="utf-8") as log:
+            code = subprocess.run(["bash", mm, *args], stdout=out, stderr=log).returncode
+    except Exception as e:
+        with open(log_path, "a", encoding="utf-8") as log:
+            log.write(f"job worker failed: {type(e).__name__}: {e}\n")
+        code = 1
+    meta.update({"status": "done" if code == 0 else "failed", "exit_code": code,
+                 "finished": time.time(), "elapsed_s": round(time.time() - meta["started"], 2)})
+    write(meta_path, meta)
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

marketmirror-0.4.2/src/marketmirror/_server/mcp_server.py

@@ -0,0 +1,716 @@
+#!/usr/bin/env python3
+"""
+MarketMirror MCP server (stdio or authenticated loopback HTTP, stdlib only).
+
+Exposes MarketMirror as tools for any MCP client. It wraps mm.sh,
+so it works before the engine is installed: call `setup` first. Long work (setup, market tests,
+surveys, feed tests) runs as background jobs; poll `job_status`.
+
+Register (Claude Code):  claude mcp add market-mirror -- python3 /path/to/mcp_server.py
+The plugin registers it automatically.
+"""
+
+from __future__ import annotations
+
+import json
+import argparse
+import hmac
+import os
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Dict, List, Optional
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+MM = os.path.join(HERE, "mm.sh")
+PROTOCOL = "2025-03-26"
+SUPPORTED_PROTOCOLS = {"2024-11-05", "2025-03-26", "2025-06-18"}
+JOBS: Dict[str, Dict[str, Any]] = {}
+LIVE: Dict[str, Any] = {}
+
+
+def sh(args: List[str], timeout: float = 120) -> Dict[str, Any]:
+    try:
+        p = subprocess.run(["bash", MM, *args], capture_output=True, text=True, timeout=timeout)
+        return {"ok": p.returncode == 0, "stdout": p.stdout[-20000:], "stderr": p.stderr[-6000:]}
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "stdout": "", "stderr": f"timed out after {timeout}s"}
+
+
+def _cli_result(result: Dict[str, Any]) -> Dict[str, Any]:
+    try:
+        data = json.loads(result.get("stdout") or "{}")
+    except ValueError:
+        data = {"message": (result.get("stdout") or "")[-4000:]}
+    if not result["ok"]:
+        raise ValueError(data.get("error") or result.get("stderr") or "CLI command failed")
+    return data
+
+
+def home() -> str:
+    return sh(["home"])["stdout"].strip()
+
+
+def job(args: List[str], label: str) -> Dict[str, Any]:
+    jid = uuid.uuid4().hex[:10]
+    logdir = os.path.join(os.path.expanduser("~"), ".market-mirror", "jobs")
+    os.makedirs(logdir, exist_ok=True)
+    log_path = os.path.join(logdir, f"{jid}.log")
+    out_path = os.path.join(logdir, f"{jid}.out")
+    meta_path = os.path.join(logdir, f"{jid}.json")
+    started = time.time()
+    with open(meta_path, "w", encoding="utf-8") as f:
+        json.dump({"id": jid, "label": label, "args": args, "log": log_path, "out": out_path,
+                   "started": started, "status": "running"}, f)
+    proc = subprocess.Popen([sys.executable, os.path.join(HERE, "job_worker.py"), MM, meta_path, out_path, log_path, *args],
+                            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    JOBS[jid] = {"id": jid, "label": label, "args": args, "proc": proc, "log": log_path, "out": out_path,
+                 "started": started, "meta": meta_path}
+    return {"job_id": jid, "label": label, "status": "running",
+            "log_path": log_path, "result_path": out_path,
+            "hint": "Poll job_status with this job_id. Progress lines appear in the log tail."}
+
+
+def job_status(job_id: str, tail: int = 25) -> Dict[str, Any]:
+    j = JOBS.get(job_id)
+    if not j:
+        meta = os.path.join(os.path.expanduser("~"), ".market-mirror", "jobs", f"{job_id}.json")
+        try:
+            with open(meta, encoding="utf-8") as f:
+                j = json.load(f)
+        except (OSError, ValueError):
+            return {"error": f"unknown job {job_id}"}
+    else:
+        try:
+            with open(j["meta"], encoding="utf-8") as f:
+                j = {**j, **json.load(f)}
+        except (OSError, ValueError):
+            pass
+    status = j.get("status", "running")
+    if status == "running" and j.get("proc") is not None and j["proc"].poll() is not None:
+        status = "done" if j["proc"].returncode == 0 else "failed"
+    try:
+        with open(j["log"], encoding="utf-8", errors="replace") as f:
+            log = f.read().splitlines()[-tail:]
+    except OSError:
+        log = []
+    res: Dict[str, Any] = {"job_id": job_id, "label": j["label"], "elapsed_s": j.get("elapsed_s", round(time.time() - j["started"])),
+                           "status": status, "log_tail": log, "log_path": j["log"], "result_path": j["out"]}
+    if status != "running":
+        try:
+            with open(j["out"], encoding="utf-8", errors="replace") as f:
+                out = f.read().strip()
+        except OSError:
+            out = ""
+        try:
+            res["result"] = json.loads(out.splitlines()[-1]) if out else None
+        except (ValueError, IndexError):
+            res["result"] = out[-4000:]
+    return res
+
+
+def results(run: str) -> Dict[str, Any]:
+    run_dir = run if os.path.isabs(run) else os.path.join(home(), "mirofish_runs", run)
+    website = os.path.join(run_dir, "website_test.json")
+    if os.path.exists(website) and not os.path.exists(os.path.join(run_dir, "summary.json")):
+        with open(website, encoding="utf-8") as source:
+            data = json.load(source)
+        return {k: data.get(k) for k in ("status", "url", "goal", "summary", "milestones", "files", "interpretation", "limits")}
+    path = os.path.join(run_dir, "summary.json")
+    if not os.path.exists(path):
+        return {"error": f"no summary.json in {run_dir} yet"}
+    s = json.load(open(path, encoding="utf-8"))
+    mk = s.get("marketing") or {}
+    out = {"dashboard": os.path.join(run_dir, "dashboard.html"), "decision": s.get("decision"),
+           "report_md": os.path.join(run_dir, "market_report.md") if os.path.exists(os.path.join(run_dir, "market_report.md")) else None,
+           "action_plan": (json.load(open(os.path.join(run_dir, "market_report.json"), encoding="utf-8")).get("action_plan")
+                           if os.path.exists(os.path.join(run_dir, "market_report.json")) else None),
+           "verdicts": mk.get("verdicts"), "overall": mk.get("overall"), "playbook": mk.get("playbook"),
+           "by_segment": mk.get("by_segment"), "objections": mk.get("objections"),
+           "messages": mk.get("messages_ranked"), "pricing": mk.get("pricing"),
+           "files": sorted(f for f in os.listdir(run_dir) if f.endswith((".csv", ".json", ".md", ".html")))}
+    if os.path.exists(website):
+        with open(website, encoding="utf-8") as source:
+            data = json.load(source)
+        out["website_test"] = {k: data.get(k) for k in ("status", "summary", "milestones", "files", "interpretation")}
+    ft = os.path.join(run_dir, "feed_test.json")
+    if os.path.exists(ft):
+        ftj = json.load(open(ft, encoding="utf-8"))
+        summ = ftj.get("summary") or {}
+        ms = ftj.get("multi_seed") or {}
+        if ms:
+            out["feed_test_seeds"] = {"n": ms.get("n"), "winner_agreement": ms.get("winner_agreement"),
+                                      "usage": ms.get("usage"), "spread": ms.get("spread")}
+        out["feed_test"] = {cid: {k: v for k, v in m.items() if k in (
+            "impressions", "noticed", "thumb_stop", "ctr", "expected_ctr", "engagement_rate", "hide_rate", "landing", "projection")}
+            for cid, m in (summ.get("per_creative") or {}).items()}
+        out["feed_test_ranked"] = summ.get("ranked")
+    pj = os.path.join(run_dir, "pitch.json")
+    if os.path.exists(pj):
+        pt = json.load(open(pj, encoding="utf-8"))
+        out["pitch"] = {k: pt.get(k) for k in ("answered", "pitch_score", "verdict_before", "verdict_after", "fixes", "hot_leads")}
+        out["pitch"]["objections"] = [{k: o.get(k) for k in ("type", "share", "rebuttal_success")} for o in pt.get("objections") or []]
+    ij = os.path.join(run_dir, "ideas.json")
+    if os.path.exists(ij):
+        it = json.load(open(ij, encoding="utf-8"))
+        out["ideas"] = [{k: i.get(k) for k in ("title", "type", "priority", "hypothesis", "metric", "how_to_test")} for i in it.get("ideas") or []]
+        out["ideas_md"] = os.path.join(run_dir, "ideas.md")
+    return out
+
+
+def list_runs() -> List[Dict[str, Any]]:
+    root = os.path.join(home(), "mirofish_runs")
+    out = []
+    for name in sorted(os.listdir(root)) if os.path.isdir(root) else []:
+        p = os.path.join(root, name, "summary.json")
+        if os.path.exists(p):
+            s = json.load(open(p, encoding="utf-8"))
+            out.append({"run": name, "title": (s.get("project_name") or name), "decision": (s.get("decision") or {}).get("decision"),
+                        "agents": s.get("agents"), "generated_at": s.get("generated_at")})
+    return out
+
+
+def start_live(run: Optional[str]) -> Dict[str, Any]:
+    p = LIVE.get("proc")
+    if p and p.poll() is None:
+        return {"url": "http://127.0.0.1:5050/", "status": "already running"}
+    args = ["live"] + (["--run-dir", os.path.join("mirofish_runs", run)] if run else [])
+    LIVE["proc"] = subprocess.Popen(["bash", MM, *args], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    time.sleep(1.5)
+    return {"url": "http://127.0.0.1:5050/", "status": "started",
+            "hint": "Open the URL in a browser (in the Claude desktop app, the browser pane)."}
+
+
+def write_config(cfg: Dict[str, Any]) -> str:
+    name = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in str(cfg.get("name") or "market_test"))
+    d = os.path.join(home(), "scenarios", name)
+    os.makedirs(d, exist_ok=True)
+    path = os.path.join(d, "market_test.json")
+    json.dump(cfg, open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
+    return path
+
+
+TOOLS = [
+    {"name": "website_test", "description": "Run prepared synthetic visitors on a real website URL. Actions and screenshots are observed; only supplied DOM checks verify goals. Cart changes are enabled by cart/checkout goals; signup submission requires explicit test data and opt-in. No payments/orders. Background job: poll job_status.",
+     "inputSchema": {"type": "object", "properties": {"simulation_id": {"type": "string"},
+        "spec": {"type": "object", "properties": {"url": {"type": "string"}, "goal": {"type": "string"},
+                 "task": {"type": "string"}, "checks": {"type": "array", "items": {"type": "object"}},
+                 "goal_check": {"type": "string"}, "max_personas": {"type": "integer", "minimum": 1, "maximum": 20},
+                 "max_steps": {"type": "integer", "minimum": 1, "maximum": 30},
+                 "device": {"type": "string", "enum": ["mobile", "desktop"]},
+                 "headless": {"type": "boolean"}, "record_video": {"type": "boolean"},
+                 "record_trace": {"type": "boolean", "description": "Opt-in raw trace may contain test credentials and network data"},
+                 "max_recoveries": {"type": "integer", "minimum": 0, "maximum": 5},
+                 "observation_mode": {"type": "string", "enum": ["compact", "full"]},
+                 "observation_text_chars": {"type": "integer", "minimum": 1000, "maximum": 10000},
+                 "max_model_calls": {"type": "integer", "minimum": 1, "maximum": 600},
+                 "max_input_tokens": {"type": "integer", "minimum": 1, "maximum": 100000000},
+                 "max_elapsed_s": {"type": "number", "exclusiveMinimum": 0, "maximum": 86400},
+                 "loop_limit": {"type": "integer", "minimum": 2, "maximum": 10},
+                 "allow_cart": {"type": "boolean"}, "allow_signup_submit": {"type": "boolean"},
+                 "test_data": {"type": "object", "description": "Owned test identity only. Multiple signup visitors need an email template containing {visitor}. Never provider API keys."}}, "required": ["url"]},
+        "out": {"type": "string"}}, "required": ["simulation_id", "spec"]}},
+    {"name": "provider_setup", "description": "List provider choices and official key guides, inspect masked local settings, configure a local model or an existing key environment variable, or discover available models. Never paste an API key into tool arguments. ChatGPT/CLI login choices return local login commands.",
+     "inputSchema": {"type": "object", "properties": {"action": {"type": "string", "enum": ["list", "status", "configure", "check"]},
+                       "provider": {"type": "string", "enum": ["ollama", "lmstudio", "anthropic", "openai", "compatible", "siwc", "codex", "claude"]},
+                       "model": {"type": "string"}, "base_url": {"type": "string"}, "key_env": {"type": "string", "description": "Environment variable NAME only; never the key itself"}}, "required": ["action"]}},
+    {"name": "doctor", "description": "Check MarketMirror: engine installed, Python deps, API key configured (never shown), backend running.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "setup", "description": "Install or update the MarketMirror engine (git clone + uv sync). Background job; poll job_status. Needs git and uv.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "start_backend", "description": "Start the MarketMirror backend (port 5001). Configure an API-key, eligible ChatGPT sign-in, local CLI gateway, or local-model provider first.",
+     "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "market_test", "description": (
+        "All-in-one market test. Config keys: name, title, seeds (absolute paths to documents), requirement (text), "
+        "personas (persona spec object or absolute path) or auto_personas (int), creatives (feed-test object with creatives, "
+        "landing, benchmarks), seeds_n (int, repeat the feed test with N seeds and report ranges), rounds (int), survey {offer, goal, messages (list), split, pricing}, panel {analysts, brief}, "
+        "report (bool), simulation_id (reuse), approve_spend (bool). Without approve_spend it stops after creating the "
+        "personas so you can show them to the user; then call again with simulation_id and approve_spend true. Background job."),
+     "inputSchema": {"type": "object", "properties": {"config": {"type": "object"}}, "required": ["config"]}},
+    {"name": "job_status", "description": "Status, log tail and final result of a background job.",
+     "inputSchema": {"type": "object", "properties": {"job_id": {"type": "string"}}, "required": ["job_id"]}},
+    {"name": "results", "description": "Key results of a run: decision, verdicts, segments, objections, messages, pricing, feed-test metrics, ROI projections, files.",
+     "inputSchema": {"type": "object", "properties": {"run": {"type": "string", "description": "run name under mirofish_runs or absolute path"}}, "required": ["run"]}},
+    {"name": "list_runs", "description": "List previous runs with their decision.", "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "start_live", "description": "Serve the live dashboard at http://127.0.0.1:5050/ (newest run, or a given run).",
+     "inputSchema": {"type": "object", "properties": {"run": {"type": "string"}}}},
+    {"name": "ads_import", "description": "Turn a Meta/Google Ads export (CSV or JSON, absolute path) into a seed Markdown file plus benchmarks JSON.",
+     "inputSchema": {"type": "object", "properties": {"file": {"type": "string"}, "out": {"type": "string", "description": "absolute path of the seed .md to write"}}, "required": ["file", "out"]}},
+    {"name": "campaign_plan", "description": "Save an evidence-led campaign plan and runnable test specs from a profile or existing project. No campaign is sent.",
+     "inputSchema": {"type": "object", "properties": {"profile": {"type": "object"}, "profile_file": {"type": "string"},
+                     "project": {"type": "string"}, "research": {"type": "object"}, "research_file": {"type": "string"},
+                     "goal": {"type": "string"}, "budget": {"type": "object"}, "channels": {"type": "array", "items": {"type": "string"}},
+                     "out": {"type": "string"}}, "required": ["goal", "budget"]}},
+    {"name": "actuals_import", "description": "Normalize a local ads, email, website, CRM or survey CSV/JSON export, retaining provenance and row-level validation errors.",
+     "inputSchema": {"type": "object", "properties": {"file": {"type": "string"}, "source_type": {"type": "string", "enum": ["ads", "email", "website", "crm", "survey"]},
+                     "mapping": {"type": "object", "additionalProperties": {"type": "string"}}, "source": {"type": "string"},
+                     "market": {"type": "string"}, "date": {"type": "string"}, "quality": {"type": "string"},
+                     "out": {"type": "string"}}, "required": ["file", "source_type"]}},
+    {"name": "holdout_backtest", "description": "Evaluate independent held-out real experiments against a training-mean no-persona baseline.",
+     "inputSchema": {"type": "object", "properties": {"pairs": {"type": "array", "items": {"type": "object"}},
+                     "out": {"type": "string"}}, "required": ["pairs"]}},
+    {"name": "backtest", "description": "Score a run's feed test against real ad results (from ads_import): rank correlation, winner match, calibration.",
+     "inputSchema": {"type": "object", "properties": {"run": {"type": "string"}, "actuals": {"type": "string"}, "map": {"type": "array", "items": {"type": "string"}}}, "required": ["run", "actuals"]}},
+    {"name": "understand", "description": (
+        "Step one for any product: read the user's documents (absolute paths to .md/.txt), a landing page URL and/or an ads "
+        "export into one product profile (what it is, for whom, pricing, offer, proofs, differentiators, competitors, channels, "
+        "likely objections, brand voice, KPIs, unknowns). Every later step uses it. Synchronous, one Claude call. Writes "
+        "product_profile.json; pass `project` instead of docs to profile an existing project (also seeds the market map before "
+        "the graph build)."),
+     "inputSchema": {"type": "object", "properties": {"docs": {"type": "array", "items": {"type": "string"}}, "url": {"type": "string"},
+                                                      "ads_file": {"type": "string"}, "project": {"type": "string"}, "name": {"type": "string"},
+                                                      "out": {"type": "string"}}}},
+    {"name": "quickstart", "description": (
+        "Easiest start. Answer a few questions and get a ready scenario folder (brief, personas, two template captions per "
+        "platform, messages, launch calendar, pitch) plus the simulated people (stops before any paid rounds). Keys: brand, "
+        "product (what, for whom, price), buyers (who and where), platforms (comma list), tests (ads, messages, price, launch, "
+        "pitch), budget ('300 USD'), size (small|medium|large), past_ads (absolute path, optional), docs (paths, optional). "
+        "Background job; poll job_status. The result names the files to edit and the exact next command."),
+     "inputSchema": {"type": "object", "properties": {"answers": {"type": "object"}, "no_run": {"type": "boolean"},
+                                                      "from_docs": {"type": "array", "items": {"type": "string"}, "description": "documents to understand first; prefills the answers"},
+                                                      "url": {"type": "string"}}, "required": ["answers"]}},
+    {"name": "pitch", "description": (
+        "Sales rehearsal: pitch a script to every simulated buyer of a simulation (its environment must be alive: run market_test "
+        "with rounds first, or start it), collect objections and the questions they ask back, then answer with rebuttals "
+        "({objection_type: text, '*': generic}). Scores the pitch, each rebuttal, and every person (lead score). Background job."),
+     "inputSchema": {"type": "object", "properties": {"simulation_id": {"type": "string"}, "run": {"type": "string"},
+                                                      "script": {"type": "string"}, "rebuttals": {"type": "object"},
+                                                      "product": {"type": "string"}, "channel": {"type": "string"},
+                                                      "segment": {"type": "string"}}, "required": ["simulation_id", "script"]}},
+    {"name": "ideas", "description": (
+        "Next test ideas from real data: pass ad rows you fetched from a connected ads tool (Meta/Google/TikTok: name, campaign, "
+        "spend, impressions, clicks, conversions, country...) and/or an export file path, plus a previous run (its objections, "
+        "audiences and decision). Returns prioritised experiments, each citing its evidence, with the MarketMirror config to "
+        "simulate it first. Writes ideas.json/.md into the run folder and adds a 'Test ideas' section to the dashboard."),
+     "inputSchema": {"type": "object", "properties": {"rows": {"type": "array", "items": {"type": "object"}}, "ads_file": {"type": "string"},
+                                                      "run": {"type": "string"}, "brand": {"type": "string"}, "brief": {"type": "string"},
+                                                      "n": {"type": "integer"}}}},
+    {"name": "push_context", "description": (
+        "While a simulation is running (or before it starts), push what people are saying today into every persona card from the next "
+        "round on: a news item, a competitor's move, a real thread you just read with your browser, a price change. Each update is "
+        "one or two sentences; the runner re-reads the file every round. Use it to ground the rounds in live reality."),
+     "inputSchema": {"type": "object", "properties": {"simulation_id": {"type": "string"}, "text": {"type": "string"}, "round": {"type": "integer"},
+                                                      "source": {"type": "string"}}, "required": ["simulation_id", "text"]}},
+    {"name": "research", "description": (
+        "What real people say about a product, category or competitor, from public keyless sources: Hacker News stories and "
+        "comments, App Store listings and recent reviews for a country storefront (in, ph, ke, us...), Reddit public search when "
+        "it answers (it often blocks non-browser clients; the result says so, then use your own browser tools and add what you find "
+        "as seed files), and any page URLs. Writes research.md (themes with quotes and links), research.json and voices.json (short "
+        "real quotes the personas and feeds draw on) under scenarios/<query>/research. Run it before planning personas."),
+     "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}, "sources": {"type": "string"}, "country": {"type": "string"},
+                                                      "subreddits": {"type": "array", "items": {"type": "string"}}, "urls": {"type": "array", "items": {"type": "string"}},
+                                                      "out": {"type": "string"}}, "required": ["query"]}},
+    {"name": "predict", "description": (
+        "Predictions with intervals for a run: CTR per ad, cost per lead, would-convert overall and per audience, email click rates, "
+        "each scaled by the real-vs-simulated results stored so far (from backtest and calibrate) and labelled with its basis "
+        "('calibrated on N real results' or 'uncalibrated prior'); optional targets (e.g. {ctr: 2, cpl: 10}) give a probability of "
+        "success. Also a 30/60/90-day adoption forecast from the best ad, its landing conversion and the word of mouth seen in the rounds."),
+     "inputSchema": {"type": "object", "properties": {"run": {"type": "string"}, "brand": {"type": "string"}, "targets": {"type": "object"},
+                                                      "spend": {"type": "number"}, "days": {"type": "integer"}}, "required": ["run"]}},
+    {"name": "study", "description": (
+        "Several scenarios x several seeds on the same simulated people, one defended conclusion. spec: {name, base (a market_test "
+        "config object: creatives, survey, pitch, emails, rounds...), simulation_id (the people to reuse), scenarios: [{name, overrides}], "
+        "seeds: [1,2,3], steps: [feed_test, rounds, survey, pitch, email_test]}. Writes study_summary.json (per-scenario mean, spread and "
+        "95% interval of every metric, deltas, winner stability, decision agreement matrix, conclusion with confidence), study_report.md "
+        "and study.html under mirofish_runs/<name>/. Finished cells are reused on rerun. Background job."),
+     "inputSchema": {"type": "object", "properties": {"spec": {"type": "object"}, "out": {"type": "string"}}, "required": ["spec"]}},
+    {"name": "run_test", "description": (
+        "Test anything from one spec on a prepared simulation: type = ad | message | price | offer | positioning | naming | landing | "
+        "launch | pitch | email | creator_post | channel_mix; variants = the things to compare (ad creatives, message lines, prices, "
+        "offer wordings, names, landing pages, launch posts with rounds, pitch scripts, emails); audience {segments, countries}; "
+        "metric (default per type); budget {amount, cpm, currency}; rounds (launch). Returns one result shape for every type: each "
+        "variant's metric with a 95% margin, the winner, the lift, whether it is clear or a tie, and how to read it. Background job."),
+     "inputSchema": {"type": "object", "properties": {"simulation_id": {"type": "string"}, "spec": {"type": "object"}, "brand": {"type": "string"},
+                                                      "run": {"type": "string"}}, "required": ["simulation_id", "spec"]}},
+    {"name": "email_test", "description": (
+        "Email campaign test on the simulated people's inboxes: pass emails [{id, from_name, subject, preheader, body, cta, "
+        "send_time (morning|midday|evening|night), segments?, sequence?: [{delay_days, subject, body}]}] plus optional list_size and "
+        "benchmarks {cost_per_send, lead_value, close_rate, deal_value}. Each person gets a realistic inbox for the day; an "
+        "attention gate decides opens, Claude decides skim/read/click/reply/unsubscribe/spam with honest odds. Returns open, click, "
+        "click-to-open, unsubscribe and spam rates per variant and audience, subject-line ranking, sequence funnel, projection from "
+        "list size to leads and revenue, spam-word warnings. Needs a prepared simulation (simulation_id). Background job."),
+     "inputSchema": {"type": "object", "properties": {"simulation_id": {"type": "string"}, "run": {"type": "string"},
+                                                      "emails": {"type": "array", "items": {"type": "object"}}, "list_size": {"type": "integer"},
+                                                      "benchmarks": {"type": "object"}}, "required": ["simulation_id", "emails"]}},
+    {"name": "calibrate", "description": (
+        "Check a run's simulated survey against real answers (absolute path to a CSV with segment,country,gender,age,y where y is "
+        "yes/maybe/no or 0-1; 50-300 rows is enough): covariate overlap, per-audience calibration, a trust / correct / walk-away "
+        "verdict and an AIPW-corrected rate. Writes calibration.json into the run folder."),
+     "inputSchema": {"type": "object", "properties": {"run": {"type": "string"}, "real_csv": {"type": "string"},
+                                                      "field": {"type": "string"}, "by": {"type": "string"},
+                                                      "map": {"type": "array", "items": {"type": "string"}}}, "required": ["run", "real_csv"]}},
+    {"name": "cli", "description": "Advanced: run any MarketMirror CLI command as a background job, e.g. ['survey','--simulation','sim_x','--offer','...']. See CLAUDE.md in the engine.",
+     "inputSchema": {"type": "object", "properties": {"args": {"type": "array", "items": {"type": "string"}}}, "required": ["args"]}},
+]
+
+
+def call(name: str, a: Dict[str, Any]) -> Any:
+    if name == "website_test":
+        directory = os.path.join(home(), "scenarios", "_website_tests")
+        os.makedirs(directory, exist_ok=True)
+        path = os.path.join(directory, uuid.uuid4().hex[:12] + ".json")
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as output:
+            json.dump(a["spec"], output, ensure_ascii=False)
+        args = ["cli", "website-test", "--simulation", a["simulation_id"], "--spec", "@" + path]
+        if a.get("out"):
+            args += ["--out", str(a["out"])]
+        return job(args, "website-test")
+    if name == "provider_setup":
+        args = ["provider", a["action"]]
+        for key in ("provider", "model", "base_url", "key_env"):
+            if a.get(key):
+                args += ["--" + key.replace("_", "-"), str(a[key])]
+        return _cli_result(sh(args, timeout=30))
+    if name == "doctor":
+        r = sh(["doctor"])
+        return {"ok": r["ok"], "diagnostics": (r["stderr"] + r["stdout"]).strip()}
+    if name == "setup":
+        return job(["setup"], "setup")
+    if name == "start_backend":
+        r = sh(["start"], timeout=300)
+        return _cli_result(r)
+    if name == "market_test":
+        path = write_config(a["config"])
+        return {**job(["cli", "market-test", path], "market-test"), "config": path}
+    if name == "job_status":
+        return job_status(a["job_id"])
+    if name == "results":
+        return results(a["run"])
+    if name == "list_runs":
+        return list_runs()
+    if name == "start_live":
+        return start_live(a.get("run"))
+    if name == "ads_import":
+        r = sh(["cli", "ads-import", a["file"], "--out", a["out"]], timeout=300)
+        return _cli_result(r)
+    if name == "campaign_plan":
+        if not (a.get("profile") or a.get("profile_file") or a.get("project")):
+            raise ValueError("profile, profile_file, or project is required")
+        d = os.path.join(home(), "scenarios", "_plans")
+        os.makedirs(d, exist_ok=True)
+        args = ["cli", "campaign-plan", "--goal", str(a["goal"]), "--budget", str(a["budget"]["amount"]),
+                "--currency", str(a["budget"].get("currency") or "USD")]
+        if a.get("profile"):
+            p = os.path.join(d, f"profile_{uuid.uuid4().hex[:8]}.json")
+            with open(p, "w", encoding="utf-8") as f:
+                json.dump(a["profile"], f, ensure_ascii=False)
+            args += ["--profile", p]
+        elif a.get("profile_file"):
+            args += ["--profile", str(a["profile_file"])]
+        else:
+            args += ["--project", str(a["project"])]
+        if a.get("research"):
+            p = os.path.join(d, f"research_{uuid.uuid4().hex[:8]}.json")
+            with open(p, "w", encoding="utf-8") as f:
+                json.dump(a["research"], f, ensure_ascii=False)
+            args += ["--research", p]
+        elif a.get("research_file"):
+            args += ["--research", str(a["research_file"])]
+        if a.get("channels"):
+            args += ["--channels", *[str(c) for c in a["channels"]]]
+        if a["budget"].get("period"):
+            args += ["--period", str(a["budget"]["period"])]
+        args += ["--out", str(a.get("out") or os.path.join(d, "campaign_plan.json"))]
+        r = sh(args, timeout=300)
+        return _cli_result(r)
+    if name == "actuals_import":
+        args = ["cli", "actuals-import", str(a["file"]), "--source-type", str(a["source_type"])]
+        if a.get("mapping"):
+            args += ["--map", *[f"{k}={v}" for k, v in a["mapping"].items()]]
+        for key in ("source", "market", "date", "quality", "out"):
+            if a.get(key):
+                args += ["--" + key, str(a[key])]
+        return _cli_result(sh(args, timeout=300))
+    if name == "holdout_backtest":
+        d = os.path.join(home(), "scenarios", "_backtests")
+        os.makedirs(d, exist_ok=True)
+        path = os.path.join(d, f"pairs_{uuid.uuid4().hex[:8]}.json")
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(a["pairs"], f, ensure_ascii=False)
+        args = ["cli", "holdout-backtest", "--pairs", path]
+        if a.get("out"):
+            args += ["--out", str(a["out"])]
+        return _cli_result(sh(args, timeout=60))
+    if name == "backtest":
+        run_dir = a["run"] if os.path.isabs(a["run"]) else os.path.join("mirofish_runs", a["run"])
+        r = sh(["cli", "backtest", "--run-dir", run_dir, "--actuals", a["actuals"], *(["--map", *a["map"]] if a.get("map") else [])], timeout=300)
+        return _cli_result(r)
+    if name == "understand":
+        d = os.path.join(home(), "scenarios", "_profiles")
+        os.makedirs(d, exist_ok=True)
+        out = a.get("out") or os.path.join(d, f"profile_{uuid.uuid4().hex[:6]}.json")
+        args = ["cli", "understand", "--out", out]
+        if a.get("project"):
+            args += ["--project", a["project"]]
+        if a.get("docs"):
+            args += ["--docs", *[str(x) for x in a["docs"]]]
+        for k in ("url", "name"):
+            if a.get(k):
+                args += ["--" + k, str(a[k])]
+        if a.get("ads_file"):
+            args += ["--ads", a["ads_file"]]
+        r = sh(args, timeout=400)
+        return _cli_result(r)
+    if name == "quickstart":
+        d = os.path.join(home(), "scenarios", "_quickstart")
+        os.makedirs(d, exist_ok=True)
+        path = os.path.join(d, f"answers_{uuid.uuid4().hex[:6]}.json")
+        json.dump(a["answers"], open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
+        args = ["cli", "quickstart", "--answers", "@" + path] + (["--no-run"] if a.get("no_run") else [])
+        if a.get("from_docs"):
+            args += ["--from-docs", *[str(x) for x in a["from_docs"]]]
+        if a.get("url"):
+            args += ["--url", str(a["url"])]
+        return {**job(args, "quickstart"), "answers": path}
+    if name == "pitch":
+        run_dir = a.get("run")
+        run_dir = (run_dir if os.path.isabs(run_dir) else os.path.join("mirofish_runs", run_dir)) if run_dir else None
+        d = os.path.join(home(), "scenarios", "_pitch")
+        os.makedirs(d, exist_ok=True)
+        sp = os.path.join(d, f"pitch_{uuid.uuid4().hex[:6]}.md")
+        open(sp, "w", encoding="utf-8").write(a["script"])
+        args = ["cli", "pitch", "--simulation", a["simulation_id"], "--script", "@" + sp]
+        if a.get("rebuttals"):
+            rp = sp.replace("pitch_", "rebuttals_").replace(".md", ".json")
+            json.dump(a["rebuttals"], open(rp, "w", encoding="utf-8"), ensure_ascii=False)
+            args += ["--rebuttals", "@" + rp]
+        for k in ("product", "channel", "segment"):
+            if a.get(k):
+                args += ["--" + k, str(a[k])]
+        if run_dir:
+            args += ["--run-dir", run_dir]
+        return job(args, "pitch")
+    if name == "ideas":
+        run_dir = a.get("run")
+        run_dir = (run_dir if os.path.isabs(run_dir) else os.path.join("mirofish_runs", run_dir)) if run_dir else None
+        args = ["cli", "ideas"]
+        if a.get("rows"):
+            d = os.path.join(home(), "scenarios", "_ideas")
+            os.makedirs(d, exist_ok=True)
+            rp = os.path.join(d, f"rows_{uuid.uuid4().hex[:6]}.json")
+            json.dump(a["rows"], open(rp, "w", encoding="utf-8"), ensure_ascii=False)
+            args += ["--rows", "@" + rp]
+        if a.get("ads_file"):
+            args += ["--ads", a["ads_file"]]
+        if run_dir:
+            args += ["--run-dir", run_dir]
+        for k in ("brand", "brief"):
+            if a.get(k):
+                args += ["--" + k, str(a[k])]
+        if a.get("n"):
+            args += ["--n", str(int(a["n"]))]
+        r = sh(args, timeout=400)
+        return _cli_result(r)
+    if name == "push_context":
+        args = ["cli", "context", "--simulation", a["simulation_id"], "--text", a["text"]]
+        if a.get("round") is not None:
+            args += ["--round", str(int(a["round"]))]
+        if a.get("source"):
+            args += ["--source", str(a["source"])]
+        r = sh(args, timeout=60)
+        return _cli_result(r)
+    if name == "research":
+        args = ["cli", "research", "--query", a["query"]]
+        if a.get("sources"):
+            args += ["--sources", str(a["sources"])]
+        if a.get("country"):
+            args += ["--country", str(a["country"])]
+        if a.get("subreddits"):
+            args += ["--subreddit", *[str(x) for x in a["subreddits"]]]
+        if a.get("urls"):
+            args += ["--url", *[str(x) for x in a["urls"]]]
+        if a.get("out"):
+            args += ["--out", str(a["out"])]
+        r = sh(args, timeout=400)
+        return _cli_result(r)
+    if name == "predict":
+        run_dir = a["run"] if os.path.isabs(a["run"]) else os.path.join("mirofish_runs", a["run"])
+        args = ["cli", "predict", "--run-dir", run_dir]
+        if a.get("brand"):
+            args += ["--brand", str(a["brand"])]
+        if a.get("targets"):
+            args += ["--target", *[f"{k}={v}" for k, v in a["targets"].items()]]
+        if a.get("spend"):
+            args += ["--spend", str(a["spend"])]
+        if a.get("days"):
+            args += ["--days", str(int(a["days"]))]
+        r = sh(args, timeout=300)
+        return _cli_result(r)
+    if name == "study":
+        d = os.path.join(home(), "scenarios", "_studies")
+        os.makedirs(d, exist_ok=True)
+        sp = os.path.join(d, f"study_{uuid.uuid4().hex[:6]}.json")
+        json.dump(a["spec"], open(sp, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
+        args = ["cli", "study", "--spec", sp]
+        if a.get("out"):
+            args += ["--out", a["out"]]
+        return job(args, "study")
+    if name == "run_test":
+        run_dir = a.get("run")
+        run_dir = (run_dir if os.path.isabs(run_dir) else os.path.join("mirofish_runs", run_dir)) if run_dir else None
+        d = os.path.join(home(), "scenarios", "_tests")
+        os.makedirs(d, exist_ok=True)
+        sp = os.path.join(d, f"test_{uuid.uuid4().hex[:6]}.json")
+        json.dump(a["spec"], open(sp, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
+        args = ["cli", "test", "--simulation", a["simulation_id"], "--spec", "@" + sp]
+        if a.get("brand"):
+            args += ["--brand", str(a["brand"])]
+        if run_dir:
+            args += ["--run-dir", run_dir]
+        return job(args, f"test {a['spec'].get('type', '')}")
+    if name == "email_test":
+        run_dir = a.get("run")
+        run_dir = (run_dir if os.path.isabs(run_dir) else os.path.join("mirofish_runs", run_dir)) if run_dir else None
+        d = os.path.join(home(), "scenarios", "_emails")
+        os.makedirs(d, exist_ok=True)
+        ep = os.path.join(d, f"emails_{uuid.uuid4().hex[:6]}.json")
+        json.dump({"emails": a["emails"], "list_size": a.get("list_size"), "benchmarks": a.get("benchmarks")}, open(ep, "w", encoding="utf-8"), ensure_ascii=False)
+        args = ["cli", "emailtest", "--simulation", a["simulation_id"], "--emails", "@" + ep]
+        if a.get("list_size"):
+            args += ["--list-size", str(int(a["list_size"]))]
+        if run_dir:
+            args += ["--run-dir", run_dir]
+        return job(args, "email-test")
+    if name == "calibrate":
+        run_dir = a["run"] if os.path.isabs(a["run"]) else os.path.join("mirofish_runs", a["run"])
+        args = ["cli", "calibrate", "--run-dir", run_dir, "--real", a["real_csv"]]
+        for k in ("field", "by"):
+            if a.get(k):
+                args += ["--" + k, str(a[k])]
+        if a.get("map"):
+            args += ["--map", *[str(x) for x in a["map"]]]
+        r = sh(args, timeout=300)
+        return _cli_result(r)
+    if name == "cli":
+        return job(["cli", *[str(x) for x in a["args"]]], "cli " + " ".join(map(str, a["args"][:2])))
+    raise ValueError(f"unknown tool {name}")
+
+
+def reply(msg_id: Any, result: Any = None, error: Optional[Dict[str, Any]] = None) -> None:
+    out = {"jsonrpc": "2.0", "id": msg_id, **({"error": error} if error else {"result": result})}
+    sys.stdout.write(json.dumps(out, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def dispatch(msg: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    method, mid = msg.get("method"), msg.get("id")
+    if mid is None:
+        return None  # notification
+    if method == "initialize":
+        requested = (msg.get("params") or {}).get("protocolVersion")
+        result = {"protocolVersion": requested if requested in SUPPORTED_PROTOCOLS else PROTOCOL,
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": "market-mirror", "version": "0.4.0"},
+                    "instructions": "MarketMirror tests marketing and sales decisions on simulated buyers. Start with doctor; "
+                                    "run setup if the engine is missing; use market_test for everything; show the user the "
+                                    "personas before approving spend; report results as simulated directions with their margins."}
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = {"tools": TOOLS}
+    elif method == "tools/call":
+        p = msg.get("params") or {}
+        try:
+            res = call(p.get("name"), p.get("arguments") or {})
+            text = res if isinstance(res, str) else json.dumps(res, ensure_ascii=False, indent=2, default=str)
+            result = {"content": [{"type": "text", "text": text}], "isError": False}
+            if isinstance(res, (dict, list)):
+                result["structuredContent"] = res
+        except Exception as e:  # noqa: BLE001 - surfaced to the client as a tool error
+            result = {"content": [{"type": "text", "text": f"{type(e).__name__}: {e}"}], "isError": True,
+                      "structuredContent": {"error": str(e), "error_type": type(e).__name__}}
+    else:
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"method not found: {method}"}}
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def handle(msg: Dict[str, Any]) -> None:
+    out = dispatch(msg)
+    if out is not None:
+        sys.stdout.write(json.dumps(out, ensure_ascii=False) + "\n")
+        sys.stdout.flush()
+
+
+def serve_http(port: int, token: str) -> None:
+    """Stateless MCP Streamable HTTP on authenticated loopback only."""
+    if not token or len(token) < 24:
+        raise ValueError("MCP bearer token must contain at least 24 characters")
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_POST(self):
+            if self.path != "/mcp":
+                self.send_error(404)
+                return
+            given = self.headers.get("Authorization", "")
+            if not hmac.compare_digest(given, "Bearer " + token):
+                self.send_response(401)
+                self.send_header("WWW-Authenticate", "Bearer")
+                self.end_headers()
+                return
+            origin = self.headers.get("Origin", "")
+            if origin and not (origin.startswith("http://127.0.0.1:") or origin.startswith("http://localhost:")):
+                self.send_error(403)
+                return
+            try:
+                size = int(self.headers.get("Content-Length", "0"))
+                if size <= 0 or size > 1_000_000:
+                    raise ValueError("invalid request size")
+                body = json.loads(self.rfile.read(size))
+                if not isinstance(body, dict):
+                    raise ValueError("JSON-RPC request must be an object")
+                out = dispatch(body)
+            except (ValueError, UnicodeDecodeError) as e:
+                self.send_error(400, str(e))
+                return
+            if out is None:
+                self.send_response(202)
+                self.end_headers()
+                return
+            payload = json.dumps(out, ensure_ascii=False).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+
+        def do_GET(self):
+            self.send_error(405)
+
+        def log_message(self, fmt, *args):
+            print(fmt % args, file=sys.stderr)
+
+    ThreadingHTTPServer(("127.0.0.1", port), Handler).serve_forever()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="MarketMirror MCP server")
+    parser.add_argument("--http", action="store_true", help="serve authenticated MCP over loopback HTTP")
+    parser.add_argument("--port", type=int, default=5061)
+    parser.add_argument("--token-file", help="file containing a bearer token (required for --http)")
+    opts = parser.parse_args()
+    if opts.http:
+        if not opts.token_file:
+            parser.error("--http requires --token-file")
+        with open(opts.token_file, encoding="utf-8") as f:
+            token = f.read().strip()
+        serve_http(opts.port, token)
+        return
+    lock = threading.Lock()
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            continue
+        with lock:
+            handle(msg)
+
+
+if __name__ == "__main__":
+    main()

marketmirror-0.4.2/src/marketmirror/_server/mm.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# mm.sh - MarketMirror helper for agents: simulated buyers, ad/message/price tests (MiroFish engine).
+#
+#   mm.sh setup                 clone or update the engine, install Python deps, create .env
+#   mm.sh doctor                check repo, deps, API key (never printed) and backend
+#   mm.sh configure             choose local models, hosted API, or a login gateway (hidden key input)
+#   mm.sh provider ACTION       list/status/check/configure provider settings; use --key-env for agent setup
+#   mm.sh agent-config          print portable MCP config (--client codex|claude|cursor|gemini|generic)
+#   mm.sh start | stop [--port N] [--env-file F]   start or stop a backend (default port 5001; other ports keep
+#                               their data in backend/uploads-<port>, so several backends run side by side)
+#   mm.sh scenario NAME FILE... copy documents into <home>/scenarios/NAME/ and print that folder
+#   mm.sh cli ARGS...           run the MiroFish CLI from the engine folder (see its --help)
+#   mm.sh live [ARGS...]        serve the live dashboard on http://127.0.0.1:5050/ (foreground)
+#   mm.sh gateway login|start|stop|status [claude|codex|gemini|antigravity|chatgpt|siwc|multi] [--port N] [--model M]
+#                               local login gateway (default port 5055, writes .env); --port N runs another one
+#                               side by side and writes .env.<backend> for a backend started with --env-file
+#   mm.sh home                  print the engine folder
+#   mm.sh mcp                   run the MCP server (stdio) exposing all of this as agent tools
+#
+# Environment: MARKET_MIRROR_HOME (default ~/.market-mirror/engine; MIROFISH_HOME also accepted),
+#              MARKET_MIRROR_REPO (default https://github.com/DarkWorldCoder/market-mirror.git)
+set -euo pipefail
+
+REPO_URL="${MARKET_MIRROR_REPO:-${MIROFISH_REPO:-https://github.com/DarkWorldCoder/market-mirror.git}}"
+HOME_DIR="${MARKET_MIRROR_HOME:-${MIROFISH_HOME:-}}"
+if [ -z "$HOME_DIR" ]; then
+  registry="${MARKET_MIRROR_CONFIG_DIR:-$HOME/.market-mirror}/engine.json"
+  HOME_DIR=$(python3 - "$registry" <<'PY'
+import json,sys
+from pathlib import Path
+try:
+    candidate = Path(json.loads(Path(sys.argv[1]).read_text())["path"])
+    if candidate.is_absolute() and (candidate / "backend/claude_cli/mirofish.py").is_file():
+        print(candidate)
+except (OSError, ValueError, KeyError, TypeError):
+    pass
+PY
+  )
+  HOME_DIR="${HOME_DIR:-$HOME/.market-mirror/engine}"
+fi
+PY="$HOME_DIR/backend/.venv/bin/python"
+CLI="$HOME_DIR/backend/claude_cli/mirofish.py"
+
+say() { printf '%s\n' "$*" >&2; }
+die() { say "error: $*"; exit 1; }
+
+key_status() {
+  # Reports whether a key is configured without ever reading it into a variable or printing it.
+  local env="$HOME_DIR/.env"
+  # hosted OpenAI-compatible providers (API_PROVIDERS in backend/app/utils/model_pool.py)
+  local hosted="DEEPSEEK MOONSHOT KIMI MISTRAL XAI GROK GROQ TOGETHER FIREWORKS OPENROUTER DASHSCOPE QWEN ZAI ZHIPU CEREBRAS MINIMAX"
+  if [ -n "${ANTHROPIC_API_KEY:-}" ] || [ -n "${GEMINI_API_KEY:-}" ] || [ -n "${GOOGLE_API_KEY:-}" ] || [ -n "${OPENAI_API_KEY:-}" ] || [ -n "${LLM_API_KEY:-}" ]; then echo "set (environment)"; return; fi
+  local name; for name in $hosted; do
+    name="${name}_API_KEY"
+    if [ -n "${!name:-}" ]; then echo "set (environment)"; return; fi
+  done
+  [ -f "$env" ] || { echo "missing (.env not created)"; return; }
+  if grep -Eq "^(${hosted// /|})_API_KEY=[[:space:]]*[\"']?[^\"'[:space:]]" "$env"; then echo "set (.env)"; return; fi
+  if grep -Eq '^LLM_API_KEY=[[:space:]]*("|'"'"')?(your_api_key_here)?("|'"'"')?[[:space:]]*$' "$env" \
+     || ! grep -Eq '^LLM_API_KEY=' "$env"; then
+    echo "missing (edit LLM_API_KEY in $env)"
+  else
+    echo "set (.env)"
+  fi
+}
+
+backend_up() { curl -fsS -m 3 "${MIROFISH_URL:-http://localhost:5001}/health" >/dev/null 2>&1; }
+
+doctor() {
+  local ok=1
+  [ -d "$HOME_DIR/.git" ] && say "engine:  $HOME_DIR" || { say "engine:  missing (run: mm.sh setup)"; ok=0; }
+  [ -x "$PY" ] && say "python:  $("$PY" --version 2>&1)" || { say "python:  deps not installed (run: mm.sh setup)"; ok=0; }
+  local k; k=$(key_status); say "model credential: $k"
+  case $k in set*) ;; *)
+    if grep -Eq '^LLM_BASE_URL=http://127\.0\.0\.1:5055' "$HOME_DIR/.env" 2>/dev/null; then
+      say "gateway: configured (LLM_GATEWAY=$(grep -E '^LLM_GATEWAY=' "$HOME_DIR/.env" | cut -d= -f2-)); $(curl -fsS -m 2 http://127.0.0.1:5055/health >/dev/null 2>&1 && echo running || echo 'stopped (run: mm.sh gateway start)')"
+    else
+      ok=0
+      for cli in claude codex antigravity gemini; do
+        if [ -x "$PY" ] && "$PY" "$HOME_DIR/backend/gateway/local_gateway.py" --backend "$cli" --check >/dev/null 2>&1; then
+          say "no key, but the $cli CLI is installed: 'mm.sh gateway start $cli' runs on its login (personal use; add --port N to run several side by side)"
+        fi
+      done
+      say "multi-agent pool: 'mm.sh gateway start multi' pools all installed local CLIs together"
+    fi ;;
+  esac
+  if [ -f "$HOME_DIR/.env" ]; then
+    say "model:   $(grep -E '^LLM_MODEL_NAME=' "$HOME_DIR/.env" | cut -d= -f2- || true)"
+    say "memory:  $(grep -E '^MEMORY_BACKEND=' "$HOME_DIR/.env" | cut -d= -f2- || true)"
+  fi
+  backend_up && say "backend: running" || say "backend: stopped (run: mm.sh start)"
+  [ $ok -eq 1 ] && say "ready" || { say "not ready"; return 1; }
+}
+
+cmd="${1:-help}"; shift || true
+case "$cmd" in
+  home) echo "$HOME_DIR" ;;
+  setup)
+    command -v git >/dev/null || die "git is required"
+    if [ -d "$HOME_DIR/.git" ]; then
+      say "using existing checkout $HOME_DIR (update separately with git pull --ff-only)"
+    else
+      say "cloning $REPO_URL -> $HOME_DIR"; mkdir -p "$(dirname "$HOME_DIR")"; git clone -q --depth 1 "$REPO_URL" "$HOME_DIR"
+    fi
+    command -v uv >/dev/null || die "uv is required. Install it with one of: 'brew install uv', 'pipx install uv', 'pip install uv' (see https://docs.astral.sh/uv/), then run setup again"
+    say "installing Python deps (first time takes a few minutes)"
+    (cd "$HOME_DIR/backend" && uv sync -q --python 3.12)
+    [ -f "$HOME_DIR/.env" ] || { cp "$HOME_DIR/.env.example" "$HOME_DIR/.env"; say "created $HOME_DIR/.env"; }
+    doctor || true
+    ;;
+  doctor) doctor ;;
+  agent-config)
+    exec python3 "$HOME_DIR/backend/claude_cli/agent_install.py" --root "$HOME_DIR" "$@"
+    ;;
+  configure|provider)
+    action="configure"
+    if [ "$cmd" = provider ]; then action="${1:-list}"; [ $# -eq 0 ] || shift; fi
+    provider_py="$PY"; [ -x "$provider_py" ] || provider_py="$(command -v python3)"
+    exec "$provider_py" "$HOME_DIR/backend/claude_cli/providers.py" "$action" --root "$HOME_DIR" "$@"
+    ;;
+  start)
+    [ -x "$PY" ] || die "not set up yet (run: mm.sh setup)"
+    case " $* " in
+      *" --env-file"*) ;;           # a per-instance settings file (written by: mm.sh gateway start BACKEND --port N)
+      *) case $(key_status) in set*) ;; *) die "provider not configured; run mm.sh configure (local models and login gateways are available)" ;; esac ;;
+    esac
+    cd "$HOME_DIR" && bash backend/claude_cli/start_server.sh "$@"
+    ;;
+  stop) cd "$HOME_DIR" && bash backend/claude_cli/stop_server.sh "$@" ;;
+  scenario)
+    name="${1:-}"; [ -n "$name" ] || die "usage: mm.sh scenario NAME FILE..."; shift
+    case "$name" in .*|*[!A-Za-z0-9._-]*) die "scenario name must start with a letter or digit and use only letters, digits, . _ -" ;; esac
+    dir="$HOME_DIR/scenarios/$name"; mkdir -p "$dir"
+    for f in "$@"; do [ -f "$f" ] || die "not a file: $f"; cp "$f" "$dir/"; done
+    echo "$dir"
+    ;;
+  cli)
+    [ -x "$PY" ] || die "not set up yet (run: mm.sh setup)"
+    cd "$HOME_DIR" && exec "$PY" "$CLI" "$@"
+    ;;
+  live)
+    [ -x "$PY" ] || die "not set up yet (run: mm.sh setup)"
+    cd "$HOME_DIR" && exec "$PY" "$CLI" live "$@"
+    ;;
+  gateway)
+    [ -x "$PY" ] || die "not set up yet (run: mm.sh setup)"
+    gw_usage="usage: mm.sh gateway login|start|stop|status [claude|codex|gemini|antigravity|chatgpt|siwc|multi] [--port N] [--model M] [--env-file F]"
+    sub="${1:-status}"; [ $# -eq 0 ] || shift
+    be=""; port="5055"; gw_model=""; envf=""
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --port) port="${2:-}"; shift ;;
+        --port=*) port="${1#*=}" ;;
+        --model) gw_model="${2:-}"; shift ;;
+        --model=*) gw_model="${1#*=}" ;;
+        --env-file) envf="${2:-}"; shift ;;
+        --env-file=*) envf="${1#*=}" ;;
+        -*) die "$gw_usage" ;;
+        *) [ -z "$be" ] || die "$gw_usage"; be="$1" ;;
+      esac
+      shift
+    done
+    case "$port" in ''|*[!0-9]*) die "--port must be a number" ;; esac
+    if [ -z "$be" ] && [ "$sub" = start ]; then
+      be="$(grep -E '^LLM_GATEWAY=' "$HOME_DIR/.env" 2>/dev/null | cut -d= -f2- | tr -d '"')"; be="${be:-claude}"
+    fi
+    case "${be:-claude}" in claude|codex|gemini|antigravity|chatgpt|siwc|multi) ;; *) die "unknown gateway backend '$be'; $gw_usage" ;; esac
+    # one pid/token/log file per port, so several gateways (one per provider) run side by side
+    if [ "$port" = 5055 ]; then sfx=""; else sfx="-$port"; fi
+    mkdir -p "$HOME_DIR/backend/logs"
+    pidf="$HOME_DIR/backend/logs/gateway$sfx.pid"
+    tokenf="$HOME_DIR/backend/logs/gateway$sfx.token"
+    logf="$HOME_DIR/backend/logs/gateway$sfx.out"
+    url="http://127.0.0.1:$port"
+    case "$sub" in
+      login) cd "$HOME_DIR" && exec "$PY" backend/gateway/siwc_auth.py login ;;
+      start)
+        if [ "$be" = siwc ]; then
+          "$PY" "$HOME_DIR/backend/gateway/siwc_auth.py" status | "$PY" -c 'import json,sys; s=json.load(sys.stdin); sys.exit(0 if s.get("eligible_scope") and not s.get("needs_login") else 1)' || die "Continue with ChatGPT is not ready (run: mm.sh gateway login)"
+        else
+          # the gateway finds each CLI on PATH or in its known install locations (codex in the ChatGPT app, agy in ~/.local/bin)
+          "$PY" "$HOME_DIR/backend/gateway/local_gateway.py" --backend "$be" --check >/dev/null 2>&1 \
+            || die "'$be' is not available (install its CLI and log in first; for multi, at least one of claude, codex, antigravity, gemini)"
+        fi
+        if [ ! -s "$tokenf" ]; then (umask 077; "$PY" -c 'import secrets,sys; open(sys.argv[1],"w").write(secrets.token_urlsafe(48))' "$tokenf"); fi
+        if curl -fsS -m 2 "$url/health" >/dev/null 2>&1; then
+          curl -fsS -m 2 "$url/health" | "$PY" -c 'import json,sys; s=json.load(sys.stdin); sys.exit(0 if s.get("auth_required") and s.get("backend")==sys.argv[1] else 1)' "$be" || die "a different or unauthenticated gateway is on port $port; stop it or pick another --port"
+          say "gateway already running ($be on $url)"
+        else
+          margs=(); [ -n "$gw_model" ] && margs=(--model "$gw_model")
+          # exec, so the recorded pid is the gateway itself (stop kills it) and nothing keeps the caller's output open
+          (cd "$HOME_DIR" && exec nohup "$PY" backend/gateway/local_gateway.py --backend "$be" --port "$port" --auth-token-file "$tokenf" ${margs[@]+"${margs[@]}"} > "$logf" 2>&1 < /dev/null) &
+          echo $! > "$pidf"
+          for _ in $(seq 1 20); do curl -fsS -m 1 "$url/health" >/dev/null 2>&1 && break; sleep 0.5; done
+          curl -fsS -m 1 "$url/health" >/dev/null 2>&1 || { tail -n 20 "$logf" >&2; die "gateway did not start; see $logf"; }
+          say "gateway started ($be) on $url/v1 (log $logf)"
+        fi
+        model="${gw_model:-$be}"
+        if [ "$be" = siwc ] && [ -z "$gw_model" ]; then model=$("$PY" "$HOME_DIR/backend/gateway/siwc_auth.py" status | "$PY" -c 'import json,sys; print(json.load(sys.stdin).get("model") or "")'); fi
+        # settings: the default port writes .env (as before); other ports write a settings file for that provider,
+        # used by a backend instance started with: mm.sh start --port P --env-file F
+        if [ -z "$envf" ]; then
+          if [ "$port" = 5055 ]; then envf="$HOME_DIR/.env"; else envf="$HOME_DIR/.env.$be"; fi
+        fi
+        case "$envf" in /*) ;; *) envf="$PWD/$envf" ;; esac
+        base_env="$envf"; [ -f "$base_env" ] || base_env="$HOME_DIR/.env"
+        (umask 077
+         { grep -Ev '^(LLM_PROVIDER|LLM_BASE_URL|LLM_API_KEY|LLM_GATEWAY|LLM_MODEL_NAME|LLM_POOL|MARKET_MIRROR_PROVIDER)=' "$base_env" 2>/dev/null || true
+           printf 'LLM_PROVIDER=openai\nLLM_BASE_URL=%s/v1\nLLM_API_KEY=%s\nLLM_GATEWAY=%s\nLLM_MODEL_NAME=%s\n' "$url" "$(cat "$tokenf")" "$be" "$model"; } > "$envf.tmp")
+        mv "$envf.tmp" "$envf"
+        if [ "$envf" = "$HOME_DIR/.env" ]; then
+          say "wrote gateway settings to $envf (restart the backend: mm.sh stop && mm.sh start)"
+        else
+          say "wrote gateway settings to $envf; start a backend on it with:"
+          say "  mm.sh start --port <backend port, e.g. 5011> --env-file $envf"
+          say "  (its data goes to backend/uploads-<port>; point the CLI at it with MIROFISH_URL=http://localhost:<port>)"
+        fi ;;
+      stop)
+        if [ -f "$pidf" ] && kill "$(cat "$pidf")" 2>/dev/null; then rm -f "$pidf"; say "gateway on port $port stopped"; else rm -f "$pidf"; say "no gateway running on port $port"; fi ;;
+      status) curl -fsS -m 2 "$url/health" 2>/dev/null || say "no gateway on port $port" ;;
+      *) die "$gw_usage" ;;
+    esac ;;
+  mcp) exec python3 "$(dirname "$0")/mcp_server.py" "$@" ;;
+  help|-h|--help) sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//' ;;
+  *) die "unknown command '$cmd' (try: mm.sh help)" ;;
+esac

marketmirror-0.4.2/src/marketmirror/cli.py

@@ -0,0 +1,22 @@
+"""Run the bundled MarketMirror MCP server (stdio by default; pass --help for options).
+
+The server is the same file the Claude Code plugin and Gemini extension use. It drives the MarketMirror engine through
+the bundled mm.sh helper; the engine itself is installed on first use with the `setup` tool (into
+~/.market-mirror/engine, or MARKET_MIRROR_HOME).
+"""
+
+import os
+import runpy
+import sys
+
+
+def main() -> None:
+    server = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_server", "mcp_server.py")
+    if not os.path.isfile(server):
+        sys.exit("marketmirror: bundled server files are missing from this install")
+    sys.argv[0] = server
+    runpy.run_path(server, run_name="__main__")
+
+
+if __name__ == "__main__":
+    main()

marketmirror-0.4.2/sync.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Copy the MCP server files from the plugin into the package before building (they are not kept twice in git).
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+src="$here/../../plugin/skills/market-mirror/scripts"
+dst="$here/src/marketmirror/_server"
+rm -rf "$dst"; mkdir -p "$dst"
+cp "$src/mcp_server.py" "$src/job_worker.py" "$src/mm.sh" "$dst/"