# FHIR Tools MCP Server

An MCP (Model Context Protocol) server exposing FHIR resource validation, synthetic test fixture generation, and HIPAA-safe logging review as tools an AI agent can call directly.

## What it does

Three tools:

* `fhir_validate_resource` — validates a FHIR resource JSON payload: checks `resourceType` presence, `id` format, required fields for known resource types (Observation, Encounter, Condition, MedicationRequest), reference field format (`ResourceType/id`), and whether `Coding` system URIs are recognized (LOINC, SNOMED CT, ICD-10, RxNorm) rather than placeholder/made-up values.
* `fhir_generate_test_fixture` — generates synthetic FHIR test data (Patient, Observation, Condition) for use in tests. All generated data is obviously fake (`TEST-` prefixed ids, placeholder names) — this tool never uses or produces real patient data.
* `fhir_check_hipaa_safe_logging` — reviews code for patterns that could leak PHI into application logs: logging full request/response bodies, logging clinical resource variables directly (vs. just their id), and exception handlers that log raw request context.

## Why an MCP server instead of just asking an LLM

FHIR schema rules (required fields per resource type, valid coding systems, reference formats) are precise and well-documented — the kind of thing that should be checked deterministically, not re-derived by an LLM from training data each time (which risks subtly wrong or outdated schema assumptions). Wrapping this as MCP tools means an agent gets a guaranteed-correct validation result and can iterate on a payload until it actually passes, rather than trusting a plausible-sounding but unverified answer.

## Running it

```bash
pip install -r requirements.txt
python server.py
```

Connect it to Claude Code, Claude Desktop, or any MCP client via the client's MCP server config (stdio transport by default).

## Example: generating a test fixture

Request: generate an `Observation` fixture for scenario "blood pressure reading"

Output:

```json
# Scenario: blood pressure reading
{
  "resourceType": "Observation",
  "id": "TEST-4f9a1b2c",
  "status": "final",
  "code": {
    "coding": [{"system": "http://loinc.org", "code": "85354-9", "display": "Blood pressure panel"}]
  },
  "subject": {"reference": "Patient/TEST-8e2d0a91"},
  "effectiveDateTime": "2026-08-11",
  "_note": "SYNTHETIC TEST DATA -- not a real observation"
}
```

## Tests

```bash
pytest -v
```

13 tests covering validation (valid/invalid resources, malformed references, unknown coding systems), fixture generation, and logging safety review.

## Limitations

* Required-field checks cover a handful of common resource types, not the full FHIR resource catalog.
* Coding system recognition is an allowlist of common systems (LOINC, SNOMED CT, ICD-10, RxNorm, etc.) — legitimate but less common systems will be flagged as "unrecognized" and need manual confirmation.
* Logging safety checks are pattern-based static analysis, not a full data-flow analysis — treat findings as a starting point for review, not a compliance guarantee.

## Possible extensions

* Expand required-field rules to cover more FHIR resource types
* Add a tool that checks a resource against a specific FHIR Implementation Guide / profile, not just base FHIR structure
* Add a tool that redacts PHI fields from a resource for safe logging, rather than just flagging unsafe patterns