Metadata-Version: 2.4
Name: bluealpha-incrementality-mcp
Version: 0.1.1
Summary: MCP server that helps marketing teams plan incrementality tests and hand off designs to BlueAlpha
Author: BlueAlpha
License: MIT
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.1.3
Requires-Dist: numpy
Requires-Dist: pandas>=2.0
Requires-Dist: scipy
Description-Content-Type: text/markdown

# bluealpha-incrementality-mcp

An MCP server that helps marketing teams plan incrementality tests through conversation — feasibility checks, business context capture, testing calendars, and handoff documents ready for your data science team to execute.

**This is a planning tool, not a modelling tool.** It helps marketers iterate on their first test design and package everything cleanly for BlueAlpha (or an internal data science team) to run the actual statistics: Causal Impact / BSTS, synthetic control, rigorous power analysis, post-test inference.

## Why

Most marketers know they should run incrementality tests but get stuck at step one: *"Am I even ready? What should I test? How do I explain it to my CMO or data team?"* This server walks them through it — in plain language, no statistics jargon — and produces a handoff document that makes it trivial for a data science team to pick up the work.

## Quick Start

### Claude Desktop

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "incrementality": {
      "command": "uvx",
      "args": ["bluealpha-incrementality-mcp"]
    }
  }
}
```

Restart Claude Desktop.

### Claude Code

```bash
claude mcp add incrementality -- uvx bluealpha-incrementality-mcp
```

### pip install

```bash
pip install bluealpha-incrementality-mcp
bluealpha-incrementality-mcp
```

### What you need

- **[uv](https://docs.astral.sh/uv/)** — handles Python automatically, no separate Python install:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **An MCP client** — [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or any MCP-compatible client
- **(Optional) A CSV with historical geo-level KPI data** — if you want the data-driven feasibility checks. Columns for geography, time, and a numeric KPI.

> **Note:** This MCP runs as a stdio subprocess on the user's local machine. CSV paths must point to files on the same machine as the MCP client — it cannot read files inside Claude.ai web sandboxes or Cowork environments. If you're working in Cowork, export/download the file locally first.

---

## The Happy Path

```
check_test_feasibility  →  capture_test_context  →  generate_test_plan  →  prepare_bluealpha_handoff
     (yes/no)               (business frame)         (handoff doc)          (email + booking link)
```

A marketer opens Claude and says *"We spend $200k/month on Connected TV and I'm not sure it's working. Help me figure out what to do."* Claude walks them through feasibility, asks about budget/goals/constraints, generates a plan, and produces an email draft + booking link for the BlueAlpha team — all in one conversation.

---

## Example Prompts

- *"What is incrementality testing?"*
- *"How long should I run my test?"*
- *"I spend $300k/month on paid media. Is testing worth it?"*
- *"Here's my data at ~/Downloads/conversions.csv — can I even run tests?"*
- *"My CMO wants to cut Connected TV by 40%. Help me build a test to justify or push back."*
- *"We need to hit 2M subscribers by EoY. Which channel should I test first?"*
- *"Build me a testing roadmap for the next 6 months."*
- *"We can't pause California for legal reasons."*
- *"Write this up for BlueAlpha to pick up."*

---

## Tools (14)

### Education

| Tool | What it does |
|------|-------------|
| `explain_concept` | Plain-language explainer for topics like geo lift, holdout, uplift, Causal Impact, statistical power, test duration, control selection. Matches natural-language queries. |
| `list_available_concepts` | Lists all topics that can be explained. |

### Feasibility

| Tool | What it does |
|------|-------------|
| `check_test_feasibility` | High-level yes/no verdict from your CSV data. Five checks: data quality (duplicates, gaps, nulls), historical depth, geo diversity, volume per geo, inter-geo similarity. No stats jargon. |
| `estimate_mmm_value` | Quick sizing: "You spend $X → smarter allocation could save ~$Y/year." |

### Data profiling

| Tool | What it does |
|------|-------------|
| `profile_geo_data` | Auto-detects geo/time/KPI columns in a CSV, returns schema and per-geo volume stats. |
| `recommend_treatment_control_geos` | Correlation-based split with volume balancing and similarity score. |
| `calculate_power_from_data` | Planning heuristic using actual observed volumes. Flagged as planning-only — real power analysis is done by your data science team. |

### Design & planning

| Tool | What it does |
|------|-------------|
| `design_test` | Recommends test type (uplift vs holdout), geo counts, and duration from a business objective. |
| `calculate_power` | Manual power analysis from typed-in parameters. |
| `calculate_sample_size` | Sample size for user-level conversion lift tests (Meta / Google style). |
| `estimate_budget` | Media budget for an uplift test (CPM × impressions × geos × weeks). |
| `plan_testing_calendar` | Multi-quarter roadmap across channels, avoiding blackout periods (Black Friday, holidays). |
| `capture_test_context` | The core planning tool. Captures business question, growth target, budget, KPI, test objective, success definition, decision criteria, off-limits geos/periods, untouchable budgets, regulatory constraints, calendar conflicts, prior tests, stakeholders, priorities. Flags missing info so Claude can ask follow-ups. |

### Handoff

| Tool | What it does |
|------|-------------|
| `generate_test_plan` | Full structured plan doc with business_context, execution plan, timeline, risks. Takes the output of `capture_test_context`. |
| `prepare_bluealpha_handoff` | Final step. Produces an email draft to the BlueAlpha team, a one-line Slack brief, and a pre-configured calendar booking link. |

---

## Division of Labor

**What this MCP does:** Education, feasibility, planning, business context capture, handoff packaging.

**What this MCP explicitly does NOT do:** Final test design, synthetic control construction, real Causal Impact / BSTS modelling, post-test causal inference. Those are done by the BlueAlpha team (or your internal data scientists) using the handoff document produced by this tool.

This separation is deliberate. Marketers get a fast, accessible planning experience. Data scientists get clean, structured inputs. Nothing in this server pretends to be a substitute for rigorous statistical execution.

---

## Development

```bash
cd servers/incrementality
uv sync
uv run bluealpha-incrementality-mcp
```

## About BlueAlpha

BlueAlpha runs production-grade incrementality tests and Marketing Mix Models for consumer brands. This planning tool is a free first step — when you're ready to execute, [book a call](https://cal.com/team/bluealpha/intro-call-with-bluealpha) or reach out to pgrafe@bluealpha.ai.

## License

MIT
