# Causal Inference MCP Server

An MCP (Model Context Protocol) server that exposes real causal-inference
methods as callable tools -- so any MCP client (Claude Desktop, Claude
Code, or a custom script) can hand it data and get back a properly
computed statistical estimate, instead of an LLM guessing at statistics
inline. The agent decides *which* method fits a question and orchestrates
the workflow; the actual math always runs in deterministic, tested Python.

Built entirely on free tools: the official open-source MCP Python SDK,
`statsmodels`/`scipy`/`scikit-learn` for the statistics, and free public
datasets (`causaldata`, plus fully-controlled synthetic data with known
ground truth) -- no paid services required.

## Tools exposed

1. **`diff_in_diff`** -- Difference-in-Differences on panel data. Returns
   the ATT estimate, standard error, p-value, 95% CI, and a pre-trend
   diagnostic (checks whether treated/control groups moved similarly
   *before* treatment, which parallel trends requires).
2. **`synthetic_control`** -- builds a weighted combination of donor
   (control) units matching the treated unit's pre-treatment trajectory
   (weights constrained non-negative, summing to 1, solved via SLSQP).
   Returns donor weights, pre-treatment fit (RMSE), and the post-treatment
   effect estimate.
3. **`propensity_matching`** -- logistic propensity scores, nearest-
   neighbor matching on the logit of the propensity score, matched ATT,
   and a covariate balance table (standardized mean differences before vs.
   after matching).
4. **`check_assumptions`** -- meta-tool. Takes the diagnostic fields from
   any of the three tools above and returns a plain-language
   pass/warning/fail verdict: flags likely-violated parallel trends,
   donor-weight concentration (an overfitting risk in synthetic control),
   and remaining covariate imbalance after matching. Deliberately
   rule-based (not an LLM call) so verdicts are deterministic and
   auditable.

## Why this shape of project

The core idea worth calling out:
LLMs are unreliable at doing real statistics inline -- they can confidently
miscompute a p-value or fabricate a synthetic-control weight. Putting the
actual computation behind typed, tested MCP tools means an agent's role is
choosing and sequencing methods correctly, not doing arithmetic it's bad
at. This is infrastructure other agents call, not a standalone app.

## Setup

```
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

Run the unit tests (validates each method against synthetic data with a
known, injected ground-truth effect):

```
pytest tests/
```

## Try it with the demo client

Runs all four tools end-to-end against synthetic data (known ground truth)
plus one real dataset, and prints results:

```
python -m demo.demo_client
```

## Connect it to Claude Desktop

Copy `demo/claude_desktop_config.example.json`'s `"causal-inference"` entry
into your Claude Desktop MCP config (update the path), restart Claude
Desktop, and you can then ask Claude directly to run a DiD or matching
analysis on data you paste in or attach -- it will call these tools rather
than compute the statistics itself.

## Datasets used

- **Synthetic panel data with known, injected effects** (`data/synthetic_generators.py`)
  -- the strongest correctness proof available, since with real data you
  never actually know the true effect, but here you do, and can check the
  tools recover it within tolerance. Used to validate `diff_in_diff`,
  `synthetic_control`, and one variant of `propensity_matching`.
- **`close_college` (Card, 1995)** via the free `causaldata` package -- a
  real, textbook dataset for `propensity_matching`, estimating the effect
  of college completion on log wages.
  **Worth noting honestly**: this dataset's actual textbook use case is
  Instrumental Variables (using distance to a 4-year college as an
  instrument), specifically *because* education is plausibly confounded by
  unobserved ability/motivation that observed covariates can't capture.
  Using it for matching here is a deliberate illustration of that
  limitation -- the `check_assumptions` tool's balance check can show
  clean covariate balance while the deeper confounding problem still isn't
  solved. That's the point: good balance is necessary, not sufficient.


## Phase 2 (planned, not yet built)

An agent orchestration layer (e.g. LangGraph) on top of this server that:
- decides which causal method fits a given question and dataset shape,
- calls the relevant tool via this server,
- calls `check_assumptions` and iterates or flags concerns rather than
  reporting a number blindly,
- explains the result and its caveats in plain language.

Phase 1 (this repo) is the tool layer; Phase 2 reuses it rather than
duplicating the statistics inside an agent framework.