Appointment Scheduler API

A small REST API for booking, rescheduling, and cancelling appointments, built with Node.js, Express, and TypeScript. Data is kept in an in-memory store, so it's meant for local development, demos, and testing rather than production use.

Full CRUD for appointments, users, and services, plus provider availability lookups — matching the accompanying OpenAPI spec.

Component diagram

flowchart LR
    Client([HTTP Client])

    subgraph API["Express App (src/app.ts)"]
        AuthMW["Auth middleware\nBearer token check"]
        Routes["Routes\nappointments / users /\navailability / services"]
        Controllers["Controllers\nvalidation +\nbusiness rules"]
        Store[("In-memory data store\n(data/store.ts)")]
        ErrorMW["Error middleware\nApiError -> 400/401/404/409,\nelse 500"]
    end

    Client -- "HTTP request" --> AuthMW
    AuthMW --> Routes
    AuthMW -. "throws ApiError (401)" .-> ErrorMW
    Routes --> Controllers
    Controllers -- "read / write" --> Store
    Store -. "data" .-> Controllers
    Controllers -. "throws ApiError" .-> ErrorMW
    Controllers -- "JSON response" --> Client
    ErrorMW -- "JSON response" --> Client

GET /health bypasses the auth middleware entirely (not pictured above, for simplicity) — deploy platforms and load balancers need to reach it without a token. Rate limiting (see below) sits between the health route and the auth middleware, so it also isn't pictured — a 429 from it never reaches ErrorMW, since express-rate-limit sends its own JSON response directly.

Related MCP server: MCP Appointment Booking Server

Requirements

• Node.js 18+ (developed/tested on Node 22)

• npm

Install

npm install

Environment variables

Copy the example file and adjust as needed:

cp dev.env.example dev.env

dev.env is loaded automatically on startup (via dotenv) and is git-ignored, so local overrides never get committed. dev.env.example is the committed template — keep it in sync whenever a new variable is added.

Run

# Development (auto-reload on file changes)
npm run dev

# Production
npm run build
npm start

The server listens on http://localhost:8080 by default. Override the port by setting PORT in dev.env (or as an environment variable directly). Every request is logged to stdout (method, path, status, response time) via morgan.

Authentication

Every endpoint requires a bearer token matching API_TOKEN, sent in the Authorization header:

curl http://localhost:8080/services \
  -H "Authorization: Bearer $API_TOKEN"

Missing, malformed, or incorrect tokens get a 401 response. This is a single shared static token (no per-user login, sessions, or expiry) — enough to demonstrate an auth-protected API without adding a user/identity system to a project meant to stay small.

Rate limiting

Every endpoint except /health is rate-limited per IP. Callers can optionally send X-Client-Type: human, agent, or service to self-identify — doing so raises the limit from 60 to 150 requests/minute (any other or missing value is treated as unidentified). This isn't an auth mechanism (the value is self-declared, not verified); it's a fair-use signal, and it's also echoed into the server logs ([client=agent]) and the business-rule log lines in the controllers, so agent traffic is visible and distinguishable from human traffic without any extra tracing. Exceeding the limit returns 429.

curl http://localhost:8080/services \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "X-Client-Type: agent"

Booking rules

POST /appointments and PUT /appointments/:id reject a date that's before today or more than a year out (400). Combined with the fixed weekly schedule in PROVIDER_BASE_SLOTS, this keeps bookings within a sensible window without needing a real calendar/scheduling system behind it. The full set of validation rules (unknown user/provider/service, time slots the provider doesn't offer, etc.) is documented in the OpenAPI spec.

MCP server

src/mcp/server.ts exposes this API to AI agents as an MCP server over stdio — list_users, list_services, check_availability, book_appointment, list_appointments, and cancel_appointment. It's a normal authenticated HTTP client of the real running API (it calls /appointments, /users, etc. over fetch, sending Authorization: Bearer $API_TOKEN and X-Client-Type: agent) — it doesn't import controllers or touch the in-memory store directly, so everything in the Rate limiting and Booking rules sections above applies to it exactly as it would to any other caller.

Two deliberate restrictions, both enforced in the MCP tool layer rather than the REST API: there's no create_user tool (the REST API supports creating users; agents can't autonomously add identity records through MCP), and list_users only returns id/name — never email/phone — since that's all book_appointment's name matching actually needs. GET /users itself is unaffected by either restriction; a normal authorized caller still gets full user records.

Run the API first, then the MCP server in a separate terminal:

npm run dev    # terminal 1 — the real API, must be running
npm run mcp    # terminal 2 — the MCP server (stdio)

To try it interactively without wiring up an agent, use the MCP Inspector:

npx @modelcontextprotocol/inspector npx tsx src/mcp/server.ts

Test

# Run the test suite once
npm test

# Watch mode
npm run test:watch

# Type-check only
npm run lint

Tests use Vitest and Supertest to exercise the Express app directly (no running server required), covering the main CRUD flows and the 400/401/404/409 error paths for each resource, plus a dedicated rate-limiter unit test (src/middleware/rateLimiter.test.ts) and a contract-test suite (src/test/contract/) that validates real responses against docs/openapi.yaml's schemas, so the spec can't silently drift from what the API actually returns. A GitHub Actions workflow (.github/workflows/ci.yml) runs npm run lint and npm test on every push and pull request.

Project structure

src/
  types/               Shared TypeScript interfaces
  data/store.ts        In-memory seed data and id counters
  utils/               ApiError, and client-type detection for logs/rate limiting
  controllers/         Request handling + validation per resource
  routes/              Express routers, one per resource
  middleware/          Auth, rate limiting, 404, and centralized error handling
  mcp/                 MCP server exposing the API as agent-callable tools
  test/contract/       Validates real responses against docs/openapi.yaml
  app.ts               Express app factory
  index.ts             Server entrypoint

API docs

• OpenAPI spec: docs/openapi.yaml describes every endpoint, request/response schema, and error case. Paste it into editor.swagger.io or any OpenAPI viewer to browse it interactively.

API overview

Full request/response shapes are defined in the OpenAPI spec provided with this project.

License