# compliance-mcp

A Python [Model Context Protocol](https://modelcontextprotocol.io) server that
exposes **SOC2** (Trust Services Criteria) and **HIPAA** (Security Rule)
compliance remediation logic as structured tools that AI agents can call.

The server is purpose-built for an LLM-driven workflow:

> **discover → assess → remediate → report**

Each tool returns strongly-typed structured content (Pydantic models) so the
calling agent can chain steps without parsing prose.

---

## Features

- **Curated control catalogs** for SOC2 (Common Criteria + Availability +
  Confidentiality samples) and HIPAA (Administrative, Physical, and Technical
  safeguards under 45 CFR 164.308 / .310 / .312).
- **Assessment engine** that scores controls against provided evidence and
  observations, surfacing matched evidence, missing evidence, findings, and
  prioritized remediation steps.
- **Prescriptive remediation plans** with ordered steps, recommended owner role,
  and effort estimates.
- **Cross-framework mappings** between SOC2 controls and HIPAA safeguards.
- **Report generation** that rolls multiple per-control assessments into a
  prioritized remediation plan with an overall status and human-readable
  summary.
- Exposed as **MCP tools, resources, and a prompt** via the official `mcp`
  Python SDK.

---

## Install

Requires Python 3.10+.

```bash
pip install -e ".[dev]"
```

## Run

```bash
compliance-mcp
```

This starts the MCP server on stdio. Wire it up in any MCP-aware client (Claude
Desktop, Claude Code, custom agents, etc.):

```json
{
  "mcpServers": {
    "compliance": {
      "command": "compliance-mcp"
    }
  }
}
```

## Tools

| Tool | Purpose |
| --- | --- |
| `list_soc2_controls` | List SOC2 controls, optionally filtered by category |
| `get_soc2_control` | Full detail for a SOC2 control (e.g. `CC6.1`) |
| `list_hipaa_safeguards` | List HIPAA safeguards |
| `get_hipaa_safeguard` | Full detail for a HIPAA safeguard (e.g. `164.312(a)(1)`) |
| `search_controls` | Free-text search across both catalogs |
| `assess_soc2_control` | Score evidence + observations against a SOC2 control |
| `assess_hipaa_safeguard` | Score evidence + observations against a HIPAA safeguard |
| `get_soc2_remediation` | Prescriptive plan for a SOC2 control |
| `get_hipaa_remediation` | Prescriptive plan for a HIPAA safeguard |
| `map_soc2_to_hipaa` | HIPAA safeguards mapped to a SOC2 control |
| `map_hipaa_to_soc2` | SOC2 controls mapped to a HIPAA safeguard |
| `list_cross_framework_mappings` | Full cross-framework mapping list |
| `generate_soc2_report` | Multi-control SOC2 assessment report |
| `generate_hipaa_report` | Multi-control HIPAA assessment report |

## Resources

- `compliance://soc2/catalog` – JSON dump of every SOC2 control
- `compliance://hipaa/catalog` – JSON dump of every HIPAA safeguard
- `compliance://mappings` – JSON dump of SOC2 → HIPAA mappings

## Prompt

- `remediation_review` – guides an agent through using the tools to remediate a
  specific control.

## Example agent flow

1. `list_soc2_controls(category="Logical and Physical Access")`
2. `assess_soc2_control(control_id="CC6.1", evidence=[...], observations=[...])`
3. `get_soc2_remediation(control_id="CC6.1", severity="high")`
4. `map_soc2_to_hipaa(soc2_control_id="CC6.1")` then assess the linked HIPAA
   safeguards.
5. `generate_soc2_report(generated_for="prod-platform", assessments=[...])`

## Testing

```bash
pytest
```

The test suite covers the assessment engine end-to-end and verifies that every
tool is registered and callable through the MCP runtime.

## Project layout

```
src/compliance_mcp/
  __init__.py
  models.py           # Pydantic data model
  engine.py           # Pure-Python assessment + remediation logic
  server.py           # FastMCP server: tools, resources, prompts
  data/
    soc2.py           # SOC2 control catalog
    hipaa.py          # HIPAA safeguard catalog
    mappings.py       # SOC2 ↔ HIPAA cross mappings
tests/
  test_engine.py
  test_server.py
```

## Caveats

The control catalogs are intentionally a curated subset suitable for driving
remediation reasoning. They are **not** a substitute for the AICPA TSC or the
HHS HIPAA Security Rule text itself, and should not be the only artifact relied
upon for an audit.

## License

MIT