pymc-marketing-mcp

# PyMC Marketing MCP [](https://github.com/imMamdouhaboammar/pymc-marketing-mcp/actions) [](https://github.com/imMamdouhaboammar/pymc-marketing-mcp/actions)    [](LICENSE) **Decision-safe Bayesian marketing science for MCP-compatible agents** > LLMs can explain marketing data. They should not invent marketing science PyMC Marketing MCP gives AI agents a controlled interface to [PyMC-Marketing](https://www.pymc-marketing.io/) for Marketing Mix Modeling, Bayesian decision support, experimentation, budget allocation, customer lifetime value, and durable analytical workflows The design boundary is deliberate - the agent frames the business question, chooses an allowed operation, and explains the evidence - PyMC-Marketing, PyMC, and ArviZ compute model-dependent quantities - this project owns validation, persistence, authorization, diagnostic policy, decision gates, provenance, jobs, and MCP contracts - decision-grade actions stop when the statistical evidence is not strong enough This is not a thin tool wrapper around a probabilistic library, and it is not an autonomous media-buying agent --- ## What you can do today `src/marketing_mcp/capabilities.py` is canonical for capability and resource names and maturity; the public surface is generated into [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md). Treat that generated inventory as the derived reference for current capability totals, maturity, and evidence instead of copying a fixed count into this README Capability maturity is evidence-backed, so an exposed tool is not automatically considered stable | Area | What the MCP can do | Representative capabilities | | --- | --- | --- | | Dataset readiness | Register, inspect, fingerprint, and validate modeling data | `register_dataset`, `inspect_dataset`, `validate_dataset` | | MMM | Fit models, inspect status, compare models, calibrate with lift tests, and evaluate sensitivity | `fit_mmm`, `get_model_status`, `compare_models`, `calibrate_mmm`, `evaluate_prior_sensitivity` | | Diagnostics | Run the mandatory statistical decision gate | `diagnose_mmm` | | Measurement | Cross-validate models and suggest evidence-gathering work | `cross_validate_mmm`, `recommend_next_measurement` | | Decision science | Contributions, incremental ROAS, scenarios, budget allocation, and weekly flighting | `get_channel_contributions`, `get_incremental_roas`, `simulate_budget`, `optimize_budget`, `optimize_flighting` | | CLV | Purchase, churn, monetary-value, and lifetime-value modeling | `fit_purchase_model`, `fit_value_model`, `estimate_customer_lifetime_value` | | Visual evidence | Produce posterior plot artifacts | `get_posterior_plots` | | Durable work | Submit, inspect, list, cancel, resume, and recover background jobs | `submit_fit_mmm_job`, `get_job_status`, `list_jobs`, `cancel_job`, `resume_job` | | Artifact exchange | Export model/dataset artifacts to an AI-client sandbox and clean expired server storage | `export_artifact_to_sandbox`, `cleanup_server_storage` | | Agent evidence | Record and retrieve structured analytical or operational insights | `record_agent_insight`, `get_agent_insights` | | Scientific skill guidance | Route tasks to scientific workflows and inspect the skill dependency map | `get_skill_guidance`, `list_agentic_skills`, `get_skill_workflow_map` | | Provenance | Inspect datasets, models, diagnostics, plots, CLV records, model lineage, and scientific-skill references through MCP resources | `marketing://...` resources | Some capabilities above are still `experimental`. Check the generated inventory before treating a capability as verified behavior --- ## Why this project exists A useful marketing agent needs more than access to a model It needs a boundary between **reasoning about marketing** and **claiming a statistically supported decision** ```text Business question | v AI agent | v MCP tool or resource | v validation + authentication + tenant authorization | v application service | v PyMC-Marketing / PyMC / ArviZ | v posterior evidence + diagnostics | v decision policy | v structured result + warnings + provenance ``` The model library owns the math. The MCP owns the rules around when that math may be used as decision evidence --- ## Decision safety is a runtime rule The repository separates descriptive analytical outputs from decision-grade actions For example, a fitted MMM is not automatically allowed to drive budget optimization. `diagnose_mmm` persists the current decision status, and gated tools such as `simulate_budget`, `optimize_budget`, and `optimize_flighting` refuse to execute when the model does not satisfy the decision contract The important rule is simple ```text model fitted != model approved for decisions ``` The gate does not claim that an approved model proves causal truth. It establishes whether the repository permits a defined class of downstream decisions under the current diagnostics contract Read [`docs/DECISION-INTEGRITY.md`](docs/DECISION-INTEGRITY.md) and [`docs/STATISTICAL-SAFETY.md`](docs/STATISTICAL-SAFETY.md) before extending model-dependent decision behavior --- ## What the project deliberately does not do The current runtime does not provide unrestricted autonomous marketing control It does not - let an LLM replace PyMC-Marketing for model-dependent calculations - allow arbitrary shell, SQL, Python, or callback execution through MCP tools - bypass diagnostics because a caller asks to "continue anyway" - change priors, model families, variables, or diagnostic thresholds until a model passes - treat a recent KPI movement as proof that something is broken - mutate Google Ads, Meta Ads, LinkedIn Ads, or other ad-platform campaigns as a current public capability - infer production readiness from the presence of tests or planning documents These restrictions are product behavior, not prompt conventions --- ## Quick start ### Requirements - Python 3.12 or 3.13 - [`uv`](https://docs.astral.sh/uv/) ### Install the development environment ```bash git clone https://github.com/imMamdouhaboammar/pymc-marketing-mcp.git cd pymc-marketing-mcp uv sync --frozen --extra dev ``` ### Run the synthetic demo ```bash uv run marketing-mcp-demo --fast ``` ### Start the MCP server over stdio ```bash uv run marketing-mcp --transport stdio ``` Local stdio intentionally runs as a trusted local principal. Use an authenticated security profile for remote HTTP access --- ## Runtime modes ### Local stdio Use this for local MCP clients and development ```bash uv run marketing-mcp --transport stdio ``` ### Local Streamable HTTP Use loopback HTTP for development ```bash uv run marketing-mcp \ --transport streamable-http \ --host 127.0.0.1 \ --port 8000 ``` The runtime exposes the MCP endpoint at `/mcp`, plus `/health`, `/health/live`, and `/health/ready` ### Private HTTP with an API key The `http-private-api-key` profile requires authentication before startup ```bash export MARKETING_MCP_SECURITY_PROFILE=http-private-api-key export MARKETING_MCP_API_KEY='replace-with-a-real-secret' uv run marketing-mcp \ --transport streamable-http \ --host 127.0.0.1 \ --port 8000 ``` Do not commit credentials or place them in examples, fixtures, logs, screenshots, or release evidence ### Production OAuth profile The codebase includes an `http-production-oauth` profile with asymmetric token verification, required scopes, and tenant claim mapping Production deployment is **not release-approved**. External identity-provider integration and exact-commit release evidence remain part of the production-readiness contract Use [`docs/SECURITY.md`](docs/SECURITY.md), [`docs/DEPLOYMENT-GCP.md`](docs/DEPLOYMENT-GCP.md), and [`docs/PRODUCTION-READINESS.md`](docs/PRODUCTION-READINESS.md) instead of treating this README as a production deployment runbook --- ## Background jobs Expensive statistical work can be represented as durable jobs rather than tying computation to one MCP request Run a standalone worker with ```bash uv run marketing-mcp-worker --poll-interval 2.0 ``` The current job implementation includes durable job records, semantic idempotency, cancellation, leases, fencing, retry limits, and stale-lease recovery Production claims about distributed workers remain subject to the G2 and H4 evidence requirements in [`docs/PRODUCTION-READINESS.md`](docs/PRODUCTION-READINESS.md) --- ## Typical MMM workflow A normal model-to-decision path is ```text 1. register_dataset 2. inspect_dataset 3. validate_dataset 4. fit_mmm or submit_fit_mmm_job 5. diagnose_mmm 6. inspect descriptive posterior evidence 7. use decision-grade tools only when the gate permits them 8. retain dataset, model, configuration, package, and decision provenance ``` A useful agent should not skip directly from `fit_mmm` to a budget recommendation ### Example decision path ```text fit_mmm | v diagnose_mmm | +-- rejected/caution requiring stop --> explain evidence or request more measurement | +-- decision access permitted ------> simulate_budget / optimize_budget / optimize_flighting ``` --- ## Typical CLV workflow The CLV surface separates purchase behavior from monetary value instead of hiding both behind one generic prediction call ```text 1. fit_purchase_model 2. predict_expected_purchases / predict_probability_alive 3. fit_value_model when monetary modeling is required 4. predict_expected_spend 5. estimate_customer_lifetime_value ``` Legacy compatibility wrappers remain visible in the capability inventory as deprecated rather than pretending they are current first-choice APIs --- ## Architecture The project is structured so the MCP transport does not own marketing or statistical behavior ```text src/marketing_mcp/ MCP transport mcp/ tools + resources + envelopes + request context | v Application services services/ datasets + modeling + diagnostics + decisions + plots + CLV + jobs | +--------------------+ | | v v Domain policy Computation adapters domain/ adapters/ validation PyMC-Marketing boundary diagnostics PyMC / ArviZ integration decision rules | | +----------+---------+ | v Persistence + artifacts storage/ + repositories/ + jobs/ + credentials/ Cross-cutting boundaries security/ principals + scopes + tenant authorization + OAuth observability/ structured logs + metrics + traces http/ health + request safety + credential control API schemas/ typed public contracts ``` The main ownership rule is that orchestration may coordinate domain owners, but it should not duplicate their math, persistence semantics, or authorization rules Read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the current and target topology --- ## Persistence and artifacts The default local runtime uses SQLite-backed metadata, jobs, and credential state with local artifact storage The repository also contains a shared-SQL persistence path used by the production-hardening work. Multi-instance production readiness must be judged against the current persistence and artifact evidence, not the existence of an adapter alone Important local paths can be configured with environment variables including ```text MARKETING_MCP_INGEST_DIR MARKETING_MCP_ARTIFACT_DIR MARKETING_MCP_METADATA_DB MARKETING_MCP_MAX_DATASET_MB MARKETING_MCP_PERSISTENCE_BACKEND MARKETING_MCP_SHARED_SQL_URL ``` See `src/marketing_mcp/config.py` for the runtime configuration contract --- ## Security model Remote access is request-scoped and tenant-aware The security boundary includes - authenticated principals propagated into MCP tool execution - scope checks mapped to public tools - object and tenant authorization - backend-controlled API-key verification and revocation - asymmetric OAuth verification for the production profile - request safety middleware - structured-log secret redaction - fail-closed startup checks for insecure HTTP configurations A valid token or API key does not imply access to every tenant or every operation Read [`docs/SECURITY.md`](docs/SECURITY.md) for the full contract and known production gaps --- ## Observability The runtime includes - structured JSON logging - secret scrubbing - low-cardinality metrics - trace context propagation - liveness and readiness endpoints Identifiers useful for correlation belong in logs or trace context where allowed, not in metric labels that create uncontrolled cardinality Production exporters, alerts, and SLO evidence are tracked separately from the local observability implementation --- ## Capability maturity Public capability status comes from `src/marketing_mcp/capabilities.py` and is rendered into [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) ```text stable executable evidence is referenced for the capability experimental exposed, but the required evidence is incomplete or absent deprecated retained for compatibility and scheduled for removal ``` The registry, actual MCP discovery, generated documentation, and evidence references are checked for drift in tests Do not hand-edit `docs/CAPABILITIES.md` --- ## Current maturity **Advanced beta / release-candidate implementation, not release-approved** The repository contains substantial hardening work across scientific correctness, recovery, remote security, observability, release evidence, agent quality, and upstream compatibility That does not make every release gate green for the current commit A gate is green only when machine-collected evidence for the exact commit being assessed proves the required property. Older test runs, historical release notes, a passing local command, or the existence of a test file are not substitutes for current release evidence Current gate interpretation lives in [`docs/PRODUCTION-READINESS.md`](docs/PRODUCTION-READINESS.md) --- ## Planned next capability: Marketing Reconciliation Engine The repository now has an implementation-ready plan for a bounded reconciliation capability This is **planned work, not a current MCP runtime capability** The v1 direction is intentionally narrow - detect machine-checkable operational, data-integrity, and decision-safety incidents - persist incident evidence and action attempts - run shadow-first - allow automatic mutation only for explicit low-risk internal recipes - verify every repair before reporting an incident as healed - escalate when evidence is uncertain - keep commercial ad-platform mutation outside v1 The first planned automatic repair is subject-scoped expired worker-lease recovery. The plan explicitly rejects a free-form autonomous growth agent and arbitrary campaign actuation Planning artifacts - [Canonical product and technical plan](docs/plans/2026-09-12-0919-feat-marketing-reconciliation-engine-plan.md) - [Staff Engineer execution brief](docs/plans/2026-09-12-0919-feat-marketing-reconciliation-engine-engineering-brief.md) - [Atomic engineering task ledger](docs/plans/2026-09-12-0919-feat-marketing-reconciliation-engine-tasks.md) Do not expose planned reconciliation tools or scopes as current capability until implementation, discovery, authorization, and evidence tests land together --- ## Verify the repository Install the development dependencies first ```bash uv sync --frozen --extra dev ``` ### Fast and integration-oriented checks ```bash uv run pytest -m "not statistical" -v ``` ### Statistical checks These run real PyMC-Marketing sampling and can take materially longer than ordinary unit tests ```bash uv run pytest -m statistical -v ``` ### Static checks ```bash uv run ruff check src tests scripts uv run pyright ``` ### Documentation and capability drift ```bash uv run python scripts/generate_capability_inventory.py --check uv run python scripts/check_docs_drift.py ``` ### Full suite and package build ```bash uv run pytest -v uv build ``` Passing these commands locally is useful engineering evidence. It is not by itself a production release approval --- ## Repository map ```text . ├── src/marketing_mcp/ │ ├── adapters/ PyMC-Marketing computation boundary │ ├── credentials/ API-key issuance, verifier storage, and revocation │ ├── domain/ validation, diagnostics, allocation, and decision policy │ ├── http/ health, request safety, and control-plane routes │ ├── jobs/ durable jobs, idempotency, leases, fencing, worker CLI │ ├── mcp/ tools, resources, envelopes, context, and task adapter │ ├── observability/ structured logging, metrics, and tracing │ ├── schemas/ typed public contracts │ ├── security/ principals, scopes, authorization, OAuth, redaction │ ├── services/ application workflows │ └── storage/ SQLite migrations and durable stores ├── tests/ │ ├── contract/ public and decision-gate contracts │ ├── integration/ transport, auth, persistence, resource, and worker behavior │ ├── release/ G0-G5 and H0-H6 release assertions │ ├── statistical/ real PyMC-Marketing statistical invariants │ └── unit/ focused domain and service tests ├── docs/ │ ├── plans/ active implementation plans and engineering ledgers │ ├── release-evidence/ machine-collected release proof │ └── README.md documentation truth map ├── scripts/ documentation, capability, release, and verification tooling ├── pyproject.toml package and tool configuration └── task_plan.md broader implementation and phase tracker ``` --- ## Documentation map Start with the document that owns the question you are asking | Question | Source of truth | | --- | --- | | What is publicly exposed | [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) | | What does each tool promise | [`docs/TOOL-CONTRACTS.md`](docs/TOOL-CONTRACTS.md) | | How is the code organized | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | | When may model outputs drive decisions | [`docs/DECISION-INTEGRITY.md`](docs/DECISION-INTEGRITY.md) | | What statistical rules are non-negotiable | [`docs/STATISTICAL-SAFETY.md`](docs/STATISTICAL-SAFETY.md) | | How does authentication and tenancy work | [`docs/SECURITY.md`](docs/SECURITY.md) | | What is actually release-ready | [`docs/PRODUCTION-READINESS.md`](docs/PRODUCTION-READINESS.md) | | What evidence supports release claims | [`docs/release-evidence/`](docs/release-evidence/) | | How should conflicting documentation be interpreted | [`docs/README.md`](docs/README.md) | | What are engineers building next | [`docs/plans/`](docs/plans/) | Plans are targets. Tests are evidence for the behavior they actually exercise. Release evidence is commit-specific. The current source and executable checks outrank historical prose --- ## Dependency policy The supported package contract currently targets ```text Python >=3.12,<3.14 PyMC-Marketing >=1.0.0,<2 MCP Python SDK >=2,<3 Pydantic >=2.12,<2.13 NumPy >=2,<3 Pandas >=2.2,<3 ArviZ >=0.21,<2 ``` The upstream canary can test newer dependency combinations without silently widening the committed package contract PyMC-Marketing 2.x should be adopted only after adapter, statistical, plotting, optimization, calibration, and persisted-artifact compatibility is proven and any required migration is explicit --- ## Historical releases Earlier v0.3 and v0.4 material remains in [`CHANGELOG.md`](CHANGELOG.md) and [`docs/FINAL-REVIEW.md`](docs/FINAL-REVIEW.md) for provenance Historical release notes do not establish the readiness of the current commit --- ## License Apache License 2.0. See [`LICENSE`](LICENSE)