# AppointmentAgent LiveKit

A standalone [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that
exposes tools for patient management, appointments, insurance, encounters, and task
management against a configurable EHR platform's REST APIs. Designed to be plugged into
an LLM-based voice/chat agent (e.g. a LiveKit agent) so it can search patients, book or
cancel appointments, verify insurance, and more, entirely through natural language.

## Features

- 29 MCP tools covering patients, insurance, appointments, encounters, tasks, and
  reference-data lookups (providers, locations, visit reasons, state codes).
- Works over stdio (for local MCP clients) or SSE (for HTTP/Docker deployments).
- Every tool call is optionally logged to disk for auditing/debugging.
- All API base URLs and credentials are supplied via environment variables — nothing
  is hardcoded.

## Getting Started

### 1. Install dependencies

```bash
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
```

### 2. Configure environment variables

```bash
cp .env.example .env
```

Fill in `.env` with your own EHR platform's base URLs and API credentials. See
`.env.example` for the full list of required variables.

### 3. Run the server

```bash
# stdio transport (for Claude Desktop / local MCP clients)
python server.py

# SSE transport over HTTP, default port 8000
python server.py --sse

# SSE transport on a custom port
python server.py --sse 3000
```

### 4. Run with Docker

```bash
docker compose up --build
```

## Project Structure

```
.
├── server.py           # MCP server + all tool definitions
├── requirements.txt    # Python dependencies
├── Dockerfile           # Container build
├── docker-compose.yml   # Local container orchestration
├── .env.example         # Environment variable template (no real secrets)
└── .gitignore
```

## Security Notes

- Never commit a real `.env` file — it is already excluded via `.gitignore`.
- `tool_logs/` may contain patient data (PHI/PII) from live calls; it is gitignored
  and should never be committed or shared.
- Rotate any credentials before reusing this server against a production system.

## License

MIT — see [LICENSE](LICENSE).