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

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.

Related MCP server: careflow-mcp

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).