# careops-mcp

An MCP (Model Context Protocol) server that exposes a home-care provider's
operational database to Claude — with **schema-validated write tools** and a
**tamper-evident, hash-chained audit log** of every call.

Built as a working demonstration of authoring a production-style MCP server
in Python: secure bidirectional connection between an LLM and local data,
strict input validation before anything touches the database, and an audit
trail that can prove it hasn't been altered.

## What it does

| Surface | Name | Purpose |
|---|---|---|
| Tool | `list_clients` | Query clients by suburb / preferred language |
| Tool | `get_client` | One client's record + upcoming visits |
| Tool | `schedule_visit` | **Write** tool, Pydantic-validated: rejects past dates, malformed times, out-of-range durations, unknown IDs, and carer double-bookings |
| Tool | `check_compliance` | Carer certifications expired or expiring within N days |
| Tool | `verify_audit_log` | Re-walks the hash chain; reports the exact line if tampered |
| Resource | `audit://log` | Full JSONL audit trail of every tool call |

### The audit log

Every tool invocation appends a JSONL entry carrying the SHA-256 of the
previous entry:

```json
{"ts": "...", "tool": "schedule_visit", "arguments": {...}, "status": "ok",
 "prev_hash": "3f2a...", "hash": "9c41..."}
```

Editing or deleting any historical record breaks the chain, and
`verify_audit_log` pinpoints the broken line. In compliance-sensitive
settings (aged care, audit) the question isn't only *what did the AI do* but
*can you prove the record of it is intact* — this answers both.

## Run it

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest        # 9 tests: validation, double-booking, chain tampering
```

Register with **Claude Code**:

```bash
claude mcp add careops -- /absolute/path/to/.venv/bin/python -m careops.server
```

Or **Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "careops": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "careops.server"]
    }
  }
}
```

Then ask Claude things like:

- *"Which carers have compliance problems in the next 30 days?"*
- *"Schedule a personal-care visit for Mei Lin with a Mandarin-speaking carer tomorrow at 9am."*
- *"Verify the audit log is intact."*

The SQLite database self-seeds with demo data on first run.

## Design notes

- **Validation before side effects.** `schedule_visit` takes a Pydantic
  model; bad input fails at the schema boundary and never reaches SQL. The
  double-booking check runs before the insert.
- **Errors are honest.** Unknown IDs and clashes raise with a clear message
  (surfaced to the model as a tool error) and are still audit-logged with an
  `error:*` status — failures are part of the record.
- **Compatible with mcp 1.x and 2.x.** Imports `MCPServer` (2.x) and falls
  back to `FastMCP` (1.x).