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:

{"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

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:

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

Or Claude Desktop (claude_desktop_config.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).