# Healthcare Data Quality MCP Server

An MCP (Model Context Protocol) server that exposes healthcare data
quality validation as tools any MCP-compatible AI client — Claude Desktop,
Claude Code, or Cowork — can call directly in conversation.

This wraps the rule logic from the **Healthcare Data Quality & Governance
Agent** skill — all four quality dimensions (completeness, integrity,
consistency, temporal accuracy) across five CMS/claims-adjacent data
types — as callable tools, so instead of pasting data into a chat and
asking for a report, an AI assistant can run the checks itself against
a real file.

The rule logic and severity scoring live here as tested, versioned code.
Turning the structured findings into the CDO-facing governance report
(plain-English explanations, executive summary, PDF) stays a job for
the skill/prompt layer, which consumes this server's JSON output.

## Supported data types

`inpatient`, `outpatient`, `carrier`, `pharmacy`, `ehr`, `population_health`
— see `rules/schema.py` for the exact required fields and identifiers
per type.

## What it does

- **`profile_dataset`** — row/column counts, columns detected, sample rows,
  and a best-guess data type (confirm before running checks)
- **`check_completeness`** — flags required fields that are null, blank, or
  placeholder values, with severity scoring (Critical / High / Medium / Note)
- **`check_integrity`** — flags duplicate claim IDs, malformed provider
  NPIs, invalid ICD-9/ICD-10 diagnosis code formats, invalid beneficiary
  IDs, and payment amount anomalies
- **`check_consistency`** — flags mixed date formats and CMS code-set
  violations (gender, race, state FIPS, claim type, chronic condition flags)
- **`check_temporal`** — flags illogical date sequences (discharge before
  admission, service after death), future-dated records, implausible ages,
  and length-of-stay anomalies
- **`run_full_quality_scan`** — runs all four dimensions and returns a
  severity-scored, prioritised summary with AI readiness signals

Every dimension tool (except `profile_dataset`) takes `filename` and
`data_type`.

## Setup

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## Run it standalone (no MCP client needed)

```bash
python3 -c "
import rules, json
df = rules.load_csv('sample_data/claims.csv')
print(json.dumps(rules.run_full_scan(df, 'outpatient'), indent=2))
"
```

Other sample files: `inpatient_sample.csv`, `carrier_sample.csv`,
`pharmacy_sample.csv`, `ehr_sample.csv`, `population_health_sample.csv`
— each paired with its matching data type.

## Connect it to Claude Desktop

1. Open your Claude Desktop config file (`claude_desktop_config.json`).
2. Add an entry like the one in `claude_desktop_config.example.json`,
   updating the path to the absolute path of `server.py` on your machine.
3. Restart Claude Desktop.
4. Ask Claude something like: *"Run a full quality scan on claims.csv as
   outpatient claims data"* — Claude will call the tool, run the checks,
   and summarize the findings.

## Notes on the SDK

This was built against `mcp==2.0.0`, which uses `mcp.server.MCPServer` as
the high-level server class. Some older tutorials reference
`mcp.server.fastmcp.FastMCP` under the same name — the `@mcp.tool()`
decorator API is identical either way; only the import path and class
name differ by SDK version.