Clinic-front-desk-MCP-server: Instructions file for Claude Code

CLAUDE.md — Clinic Front-Desk MCP Server

Project Overview

Build clinic-frontdesk-mcp: an open-source MCP (Model Context Protocol) server that turns any MCP-compatible client (Claude Desktop, Claude Code, custom agents) into an AI receptionist for a small medical clinic.

The server exposes tools for appointment booking, rescheduling, reminders, patient intake, and clinic FAQs. The LLM client is the "brain"; this server provides the hands.

License: MIT. Language: Python 3.11+. MCP SDK: official mcp Python SDK (use FastMCP). Storage: SQLite (zero-config, file-based). Distribution: installable via uvx / pip, runnable over stdio transport.

Design Principles

1. Human-in-the-loop for all writes. Tools that book, cancel, or message must return a clear confirmation summary. Destructive actions (cancel, delete) require an explicit confirm=true parameter — if called without it, return a preview of what would happen and ask for confirmation.
2. No clinical advice. This server handles logistics only. If tools receive medical questions, the FAQ tool should return a canned "please discuss with the doctor" style entry. Never store or return diagnostic recommendations.
3. Privacy-first. All data stays in a local SQLite file. No external calls in v1 except optional notification adapters (stubbed by default). Never log patient names/phones to stdout (stdout is the MCP transport anyway — log to stderr or a file, and redact PII in logs).
4. Zero-config startup. First run auto-creates the database with schema + seed data. Config via environment variables with sensible defaults.
5. Timezone-aware. Clinic timezone from config (default Asia/Kolkata). All stored timestamps in UTC ISO 8601; all tool inputs/outputs in clinic-local time.

Repository Structure

clinic-frontdesk-mcp/
├── CLAUDE.md
├── README.md               # install, Claude Desktop config snippet, demo script
├── LICENSE                 # MIT
├── pyproject.toml          # project metadata, deps, entry point: clinic-frontdesk-mcp
├── src/
│   └── clinic_frontdesk_mcp/
│       ├── __init__.py
│       ├── server.py       # FastMCP app: tool definitions ONLY (thin layer)
│       ├── db.py           # SQLite connection, schema creation, migrations
│       ├── models.py       # dataclasses / pydantic models
│       ├── scheduling.py   # availability logic, slot math, conflict checks
│       ├── patients.py     # patient CRUD + intake logic
│       ├── faq.py          # FAQ lookup (simple keyword + fuzzy match)
│       ├── notifications.py# adapter interface + ConsoleAdapter (stub) + TwilioAdapter (optional)
│       └── config.py       # env-var config loading
├── seed/
│   └── seed_data.sql       # demo clinic, doctors, FAQ entries, sample patients
├── tests/
│   ├── test_scheduling.py
│   ├── test_tools.py       # tool-level integration tests via FastMCP test client
│   └── test_db.py
└── .github/
    └── workflows/ci.yml    # ruff + pytest on push