# GeraClinic MCP Server

[![A Gera Systems product](https://img.shields.io/badge/Gera-Systems-0a7?style=flat)](https://geraclinic.com)

An [MCP](https://modelcontextprotocol.io) server that lets AI agents — Claude
Desktop, ChatGPT with tools, Cursor, Windsurf, or any MCP client — **find
CQC-registered UK care and health providers**, read **area care statistics**,
and run **non-diagnostic health calculators**, fully offline.

It bundles a snapshot of GeraClinic's real **Care Quality Commission (CQC)**
provider directory — GP surgeries, dentists, hospitals, clinics, care/nursing
homes, hospices and more — plus GeraClinic's published health-calculator math.
**No backend, no network, no auth** — everything is computed locally, so it is
safe to run anywhere and gives the same answers the
[GeraClinic](https://geraclinic.com) product gives.

> Source: Care Quality Commission `www.cqc.org.uk`, licensed under the
> [Open Government Licence v3.0](https://www.cqc.org.uk/about-us/transparency/using-cqc-data).
> CQC ratings are categorical (Outstanding / Good / Requires improvement /
> Inadequate), never numeric. Health calculators are educational reference math,
> not medical advice.

## Tools

| Tool | What it does |
|------|--------------|
| `find_care_provider` | Search real CQC-registered providers by name, postcode (full or outward), service type, and/or local authority. Returns address, phone, website, service types, last-inspected date, and the CQC profile URL. |
| `get_cqc_area_stats` | Aggregated CQC statistics for a UK authority or locality: total providers, phone/website coverage, service-type breakdown (GPs, dentists, care homes, hospitals…), top service type, latest inspection date. |
| `list_care_authorities` | List the UK areas the directory covers (optionally filtered by region) with provider counts and the available service types — use to discover valid `area` / `authority` values. |
| `list_health_calculators` | List the available health calculators with their inputs and the public reference standard each uses. |
| `run_health_calculator` | Run a calculator: BMI, BMR/TDEE calories, ideal weight, blood-pressure category, heart-rate zones, A1C↔glucose, water intake, or waist-to-height ratio. |

A typical agent flow: `list_care_authorities` → `find_care_provider`
(by area + service type) or `get_cqc_area_stats`; and separately
`list_health_calculators` → `run_health_calculator`.

## Install & run

```bash
# Run directly (no global install) once published to npm:
npx -y @gera-services/mcp-gera-clinic

# Or from this repo:
cd packages/mcp-gera-clinic
npm run build      # tsc --noCheck  -> dist/  (+ copies the CQC data file)
node bin/cli.js    # starts on stdio
```

## Client configuration

### Claude Desktop / Claude Code (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "gera-clinic": {
      "command": "npx",
      "args": ["-y", "@gera-services/mcp-gera-clinic"]
    }
  }
}
```

Local (unpublished) variant — point at the built CLI:

```json
{
  "mcpServers": {
    "gera-clinic": {
      "command": "node",
      "args": ["/Users/armen/Gera/packages/mcp-gera-clinic/bin/cli.js"]
    }
  }
}
```

### Cursor / Windsurf (`.cursor/mcp.json` etc.)

```json
{
  "mcpServers": {
    "gera-clinic": {
      "command": "npx",
      "args": ["-y", "@gera-services/mcp-gera-clinic"]
    }
  }
}
```

## Verify it works

```bash
npm run build
node scripts/smoke.mjs
```

The smoke test speaks raw MCP JSON-RPC over stdio (`initialize` → `tools/list`
→ several `tools/call`) and asserts the results. Expected output ends with
`ALL SMOKE CHECKS PASSED`.

## Example

Ask your agent: *"Find me a dentist in Kent, and what's the BMI for someone
82 kg and 178 cm?"*

The agent calls `find_care_provider` with
`{ authority: "kent", serviceType: "Dentist" }` and `run_health_calculator`
with `{ calculator: "bmi", weightKg: 82, heightCm: 178 }`, returning real CQC
provider records and a BMI of `25.9` (`Overweight`, WHO category).

## License

MIT © Gera Systems Ltd