booking-mcp

A standalone MCP server (built on FastMCP) that exposes the booking datastore used by booking-agent to any MCP-compatible client. It is decoupled from booking-agent and connects to the shared DB with its own SQLAlchemy layer. booking-agent owns the schema and migrations; a schema-contract test guards against drift.

Features

Resources (read-only, URI-addressed)

URI	Returns
booking://staff	active cleaners (skills + location)
booking://staff/{staff_id}	one staff member
booking://schedule/{date}	appointments on a date
booking://clients/{email}	client + contacts + saved preferences

Read tools (readOnly, idempotent)

• search_availability(service, date, time, latitude?, longitude?, radius_km?): staff who can do the job, are free at the slot, and are within range. This uses the same skill/free/geo filter as the booking engine.
• find_next_available(service, date, time, days?, …): first day within the window with a free, qualified cleaner.
• list_staff(skill?), daily_schedule(date), get_client(email).

Write tools (only when READ_ONLY=false; each asks for confirmation via MCP elicitation before writing)

• create_booking(...): client + job + appointment, idempotent (deduped on a hash of all material fields).
• cancel_booking(appointment_id): idempotent delete.
• reschedule_booking(appointment_id, date, time): moves a slot and rejects staff conflicts.
• add_customer_preference(email, note).
• book_from_text(request): parses a free-text request using the client's LLM via MCP sampling, then confirms and books. Requires a sampling-capable client. Idempotent.

Writes go directly to the DB and bypass booking-agent's approval workflow. Use the workflow bridge below if you want human approval.

Workflow bridge tools (only when BOOKING_AGENT_URL is set; routes through booking-agent's human-approval workflow over HTTP)

• book_via_workflow(message): start an approval run from a natural-language request and return {run_id, status}.
• get_workflow_run(run_id): poll status and the final response.
• decide_workflow_run(run_id, approve, by?, reason?): submit the approve/reject decision.

Prompts: book_cleaning(...), summarize_schedule(date).

All inputs are validated (real calendar dates/times, email format); all outputs are typed (structured content).

Quickstart

cp .env.example .env   # point DATABASE_URL at the shared Postgres
make install           # uv sync --dev
make dev-up            # start Postgres on :5433 (Docker)
make seed              # create_all + demo data (requires STANDALONE_MODE guard)
make server            # run in stdio mode

For the HTTP transport on the host: make server-http (binds :8000).

Fully standalone (own DB + data). No booking-agent needed. One-shot the whole stack:

make stack-up   # docker compose up (db + seed + mcp on :8000)

booking-mcp-seed bootstraps the schema with create_all and populates demo staff, clients, appointments, and preferences so the read tools return data immediately. STANDALONE_MODE=true is required. The guard prevents accidental schema mutation against a shared DB. When sharing a DB with booking-agent, skip the seed: booking-agent owns the canonical Alembic migrations.

API / Usage

Any MCP client takes the standard mcpServers config (the same JSON an mcp add accepts).

Local (stdio). The client launches the server as a subprocess. This is local and trusted, so no auth is required:

{
  "mcpServers": {
    "booking": {
      "command": "/ABS/PATH/booking-mcp/.venv/bin/booking-mcp",
      "env": {
        "DATABASE_URL": "postgresql+psycopg://booking:booking@localhost:5432/booking",
        "READ_ONLY": "true"
      }
    }
  }
}

(booking-mcp is the console script installed into the venv.)

Remote (HTTP). Connect over the streamable-HTTP transport with a Bearer key. Mint a key, then pass the hash in API_KEYS (the server refuses to start write-enabled over HTTP without credentials):

# 1. Mint a key (prints plaintext once + the JSON record to add to API_KEYS)
#    Available scopes: read, write, workflow, pii (grant only what the client needs)
booking-mcp-mintkey --client claude-desktop --scopes read,write,pii

# 2. Start the server
API_KEYS='[{"hash":"<paste-hash>","client_id":"claude-desktop","scopes":["read","write","pii"]}]' \
  READ_ONLY=false booking-mcp

{
  "mcpServers": {
    "booking": {
      "url": "http://your-host:8000/mcp",
      "headers": { "Authorization": "Bearer <plaintext-key>" }
    }
  }
}

A client with no or wrong key gets 401. Scope enforcement is strict: a key without read cannot see read tools; write/workflow/pii are additional gates on top. stdio needs no token because it is local/trusted, so all surfaces are open.

Legacy: AUTH_TOKEN=<token> still works as a single full-access fallback but is deprecated It grants read+write with no scope isolation. Migrate to API_KEYS.

Development

Common make targets:

Target	What it runs
make install	uv sync --dev
make dev-up / dev-stop / dev-down	Postgres container lifecycle
make seed	Schema + demo data (STANDALONE_MODE=true)
make server	stdio server on host
make server-http	HTTP server on host (:8000)
make stack-up / stack-down	Full containerised stack
make mintkey ARGS="--client X --scopes read,pii"	Mint an API key
make db	psql shell into the running container
make test	pytest --cov=booking_mcp
make lint	ruff check src tests
make fmt	ruff format src tests
make audit	pip-audit
make check	lint then test

Testing

make test   # pytest --cov=booking_mcp, requires 100% coverage to pass

• In-memory client: tools/resources are exercised through fastmcp.Client against the server object, with no subprocess.
• Testcontainer Postgres: the MCP's own create_all schema, truncated per test (real FK/types).
• Schema-contract test (test_schema_contract.py): when ../booking-agent/backend is checked out, it applies booking-agent's real Alembic migrations to a fresh container and runs the MCP queries against them. This catches drift between this server's models and the owning service's schema. Skips when booking-agent isn't present.

Configuration

Copy .env.example to .env. All settings are read from the environment (or .env).

Variable	Default	Purpose
DATABASE_URL	postgresql+psycopg://booking:booking@localhost:5432/booking	The same Postgres booking-agent uses; booking-agent owns the schema, this is a client.
READ_ONLY	true	Set to false to enable the write tools. Writes bypass booking-agent's human-approval workflow, so enable deliberately.
STANDALONE_MODE	false	Must be true to run booking-mcp-seed / create_all(). Guards against accidental schema mutation on a shared DB. Not needed when connecting to a DB already managed by booking-agent.
API_KEYS	(empty)	Preferred HTTP auth. JSON array of {hash, client_id, scopes} records. Store hashes only, never plaintext. Mint records with booking-mcp-mintkey. All four scopes (read, write, workflow, pii) are enforced at the auth layer: a key sees only the surfaces its scopes explicitly cover.
AUTH_TOKEN	(empty)	Deprecated: single static token granting full access (all scopes). Superseded by API_KEYS. Kept for backward compatibility.
REDACT_PII	true	Mask phone numbers (last-4 digits) and addresses ([REDACTED]) in client resources and get_client. Resources are pulled into model context, where PII can spread to prompts/logs/transcripts. Set false only for internal tooling backed by a scoped key.
FORCE_WORKFLOW_FOR_SAMPLING	false	Redirect book_from_text to book_via_workflow instead of writing directly. Recommended in production: sampled LLM output carries implicit trust/quota risks.
BOOKING_AGENT_URL	(empty)	When set, the workflow-bridge tools are registered and POST to booking-agent so a booking goes through its full approval workflow. Decoupled: HTTP only, no import.
BOOKING_AGENT_TIMEOUT	10.0	HTTP timeout (seconds) for workflow-bridge calls to booking-agent.
SAMPLE_TIMEOUT	30.0	Cap on the client's LLM sampling call in book_from_text so a hung client can't pin a worker.
DB_POOL_SIZE	20	Connection pool size (sized for FastMCP's sync-tool threadpool).
DB_MAX_OVERFLOW	20	Pool overflow beyond DB_POOL_SIZE.
DB_POOL_RECYCLE	3600	Recycle connections after this many seconds.
DB_POOL_TIMEOUT	10	Seconds to wait for a pooled connection.
DB_STATEMENT_TIMEOUT_MS	30000	Per-query statement timeout (ms).
LOG_LEVEL	INFO	Logging level.

Notes

• Schema ownership: in standalone mode (STANDALONE_MODE=true), booking-mcp-seed bootstraps the schema with create_all. When sharing a DB with booking-agent, booking-agent owns the canonical Alembic migrations. Skip the seed entirely; the schema-contract test guards against model drift.
• No FastAPI/LangGraph. FastMCP brings its own (Starlette/uvicorn) HTTP stack for the HTTP transport.
• MCP client features used: elicitation (write confirmation), sampling (book_from_text). Both degrade gracefully. A client that does not support them just cannot call those tools.
• Per-resource content subscriptions and argument completions are not supported. Neither is first-class in this FastMCP version. Clients re-read booking://schedule/{date} for fresh data.

License

MIT. See LICENSE.