@gera-services/mcp-gera-clinic 0.1.1 → 1.0.0

package/README.md

@@ -1,80 +1,113 @@
-# @gera-services/mcp-gera-clinic
+# GeraClinic MCP Server
 
-MCP (Model Context Protocol) server for [GeraClinic](https://geraclinic.com) -- the AI-powered telemedicine platform by [Gera Services](https://gera.services).
+[![A Gera Systems product](https://img.shields.io/badge/Gera-Systems-0a7?style=flat)](https://geraclinic.com)
 
-Enables AI assistants (Claude, ChatGPT, etc.) to search doctors, check availability, and book medical appointments across 50+ countries.
+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 | Description | Auth Required |
-|------|-------------|:---:|
-| `search_doctors` | Search doctors by specialty, location, language, appointment type, and rating | No |
-| `get_doctor_profile` | Get detailed doctor profile (bio, qualifications, fees, languages) | No |
-| `get_available_slots` | Get open appointment time slots for a doctor on a given date | No |
-| `list_specialties` | List all medical specialties available in a country | No |
-| `get_featured_doctors` | Get top-rated, verified doctors | No |
-| `get_health_services` | Get all health service types available in a country (telemedicine, pharmacy, labs, home nursing) | No |
-| `book_appointment` | Book a video, in-person, or chat consultation | Yes |
+| 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`.
 
-## Installation
+## Install & run
 
 ```bash
-npm install @gera-services/mcp-gera-clinic
-```
+# Run directly (no global install) once published to npm:
+npx -y @gera-services/mcp-gera-clinic
 
-## Usage
+# 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
+```
 
-### With Claude Desktop
+## Client configuration
 
-Add to your `claude_desktop_config.json`:
+### Claude Desktop / Claude Code (`claude_desktop_config.json`)
 
 ```json
 {
   "mcpServers": {
     "gera-clinic": {
       "command": "npx",
-      "args": ["@gera-services/mcp-gera-clinic"]
+      "args": ["-y", "@gera-services/mcp-gera-clinic"]
     }
   }
 }
 ```
 
-### With a custom API endpoint
+Local (unpublished) variant — point at the built CLI:
 
 ```json
 {
   "mcpServers": {
     "gera-clinic": {
-      "command": "npx",
-      "args": ["@gera-services/mcp-gera-clinic"],
-      "env": {
-        "GERACLINIC_API_URL": "https://your-api-url.example.com"
-      }
+      "command": "node",
+      "args": ["/Users/armen/Gera/packages/mcp-gera-clinic/bin/cli.js"]
     }
   }
 }
 ```
 
-### Standalone
+### Cursor / Windsurf (`.cursor/mcp.json` etc.)
 
-```bash
-npx @gera-services/mcp-gera-clinic
+```json
+{
+  "mcpServers": {
+    "gera-clinic": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-gera-clinic"]
+    }
+  }
+}
 ```
 
-## Configuration
+## Verify it works
 
-| Environment Variable | Description | Default |
-|---------------------|-------------|---------|
-| `GERACLINIC_API_URL` | Base URL for the GeraClinic API | `https://api.geraclinic.com` |
+```bash
+npm run build
+node scripts/smoke.mjs
+```
 
-## Multi-Country Support
+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`.
 
-GeraClinic operates across 50+ countries. Pass a country code (ISO 3166-1 alpha-2) to any tool to scope results to that country. Supported countries include Georgia (GE), Uganda (UG), Ghana (GH), Kenya (KE), Nigeria (NG), Pakistan (PK), Bangladesh (BD), Colombia (CO), Peru (PE), Ecuador (EC), and many more.
+## Example
 
-## Authentication
+Ask your agent: *"Find me a dentist in Kent, and what's the BMI for someone
+82 kg and 178 cm?"*
 
-Read-only tools (search, availability, specialties) work without authentication. Booking requires a user bearer token passed via the `auth_token` parameter.
+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
+MIT © Gera Systems Ltd

package/bin/cli.js

@@ -1,2 +1,12 @@
 #!/usr/bin/env node
-require('../dist/server.js');
+/**
+ * CLI entry point for the GeraClinic MCP server.
+ * Starts the server on stdio. Intended to be launched by an MCP client
+ * (Claude Desktop, ChatGPT-with-tools, Cursor, etc.) — not run interactively.
+ */
+import { main } from '../dist/server.js';
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/dist/calculators.d.ts

@@ -0,0 +1,108 @@
+/**
+ * GeraClinic health calculators — pure, non-diagnostic reference math.
+ *
+ * These mirror GeraClinic's published health-tools library
+ * (apps/gera-clinic-web/src/lib/health-tools/calc.ts) exactly: same formulas,
+ * same WHO/NIH/ACC-AHA/ADAG reference ranges. Every function returns an
+ * OBJECTIVE number plus, where applicable, a public reference CATEGORY label.
+ * Nothing here diagnoses a condition or prescribes a dose — orientation only.
+ */
+export declare const LB_PER_KG = 2.2046226218;
+export declare const CM_PER_INCH = 2.54;
+export declare function cmToIn(cm: number): number;
+export type BmiCategory = 'Underweight' | 'Healthy weight' | 'Overweight' | 'Obesity';
+export declare function bmiCategory(value: number): BmiCategory;
+export declare function bmi(weightKg: number, heightCm: number): {
+    bmi: number;
+    category: BmiCategory;
+    healthyWeightRangeKg: {
+        minKg: number;
+        maxKg: number;
+    };
+    reference: string;
+};
+export declare function healthyWeightRangeKg(heightCm: number): {
+    minKg: number;
+    maxKg: number;
+};
+export type Sex = 'male' | 'female';
+export type ActivityLevel = 'sedentary' | 'light' | 'moderate' | 'active' | 'very_active';
+export declare const ACTIVITY_FACTORS: Record<ActivityLevel, number>;
+export declare function bmrValue(weightKg: number, heightCm: number, ageYears: number, sex: Sex): number;
+export declare function bmrTdee(weightKg: number, heightCm: number, ageYears: number, sex: Sex, activity: ActivityLevel): {
+    bmrKcalPerDay: number;
+    tdeeKcalPerDay: number;
+    activityFactor: number;
+    reference: string;
+};
+export declare function idealWeightKg(heightCm: number, sex: Sex): {
+    reference: string;
+    devineKg: number;
+    robinsonKg: number;
+    millerKg: number;
+    hamwiKg: number;
+};
+export type BpCategory = 'Normal' | 'Elevated' | 'Hypertension stage 1' | 'Hypertension stage 2' | 'Hypertensive crisis';
+export declare function bloodPressureCategory(systolic: number, diastolic: number): {
+    systolic: number;
+    diastolic: number;
+    category: BpCategory;
+    reference: string;
+};
+export declare function heartRateZones(ageYears: number): {
+    estimatedMaxHr: number;
+    zones: {
+        description: string;
+        lowBpm: number;
+        highBpm: number;
+        name: string;
+    }[];
+    reference: string;
+};
+export declare const MGDL_PER_MMOL = 18.0182;
+export declare function a1c(a1cPercent?: number, avgGlucoseMgDl?: number): {
+    a1cPercent: number;
+    estAvgGlucoseMgDl: number;
+    estAvgGlucoseMmolL: number;
+    reference: string;
+    avgGlucoseMgDl?: undefined;
+    estA1cPercent?: undefined;
+    avgGlucoseMmolL?: undefined;
+    error?: undefined;
+} | {
+    avgGlucoseMgDl: number;
+    estA1cPercent: number;
+    avgGlucoseMmolL: number;
+    reference: string;
+    a1cPercent?: undefined;
+    estAvgGlucoseMgDl?: undefined;
+    estAvgGlucoseMmolL?: undefined;
+    error?: undefined;
+} | {
+    error: string;
+    a1cPercent?: undefined;
+    estAvgGlucoseMgDl?: undefined;
+    estAvgGlucoseMmolL?: undefined;
+    reference?: undefined;
+    avgGlucoseMgDl?: undefined;
+    estA1cPercent?: undefined;
+    avgGlucoseMmolL?: undefined;
+};
+export declare function waterIntakeLitres(weightKg: number, activityMinutes?: number): {
+    litresPerDay: number;
+    reference: string;
+};
+export type WaistHeightCategory = 'Low' | 'Healthy' | 'Increased' | 'High';
+export declare function waistToHeight(waistCm: number, heightCm: number): {
+    ratio: number;
+    category: WaistHeightCategory;
+    reference: string;
+};
+export interface CalculatorInfo {
+    id: string;
+    title: string;
+    description: string;
+    inputs: string[];
+    reference: string;
+}
+export declare const CALCULATORS: CalculatorInfo[];

package/dist/calculators.js

@@ -0,0 +1,227 @@
+/**
+ * GeraClinic health calculators — pure, non-diagnostic reference math.
+ *
+ * These mirror GeraClinic's published health-tools library
+ * (apps/gera-clinic-web/src/lib/health-tools/calc.ts) exactly: same formulas,
+ * same WHO/NIH/ACC-AHA/ADAG reference ranges. Every function returns an
+ * OBJECTIVE number plus, where applicable, a public reference CATEGORY label.
+ * Nothing here diagnoses a condition or prescribes a dose — orientation only.
+ */
+export const LB_PER_KG = 2.2046226218;
+export const CM_PER_INCH = 2.54;
+export function cmToIn(cm) {
+    return cm / CM_PER_INCH;
+}
+export function bmiCategory(value) {
+    if (value < 18.5)
+        return 'Underweight';
+    if (value < 25)
+        return 'Healthy weight';
+    if (value < 30)
+        return 'Overweight';
+    return 'Obesity';
+}
+export function bmi(weightKg, heightCm) {
+    const m = heightCm / 100;
+    const value = Math.round((weightKg / (m * m)) * 10) / 10;
+    const range = healthyWeightRangeKg(heightCm);
+    return {
+        bmi: value,
+        category: bmiCategory(value),
+        healthyWeightRangeKg: range,
+        reference: 'WHO adult BMI categories (educational).',
+    };
+}
+export function healthyWeightRangeKg(heightCm) {
+    const m = heightCm / 100;
+    return {
+        minKg: Math.round(18.5 * m * m * 10) / 10,
+        maxKg: Math.round(24.9 * m * m * 10) / 10,
+    };
+}
+export const ACTIVITY_FACTORS = {
+    sedentary: 1.2,
+    light: 1.375,
+    moderate: 1.55,
+    active: 1.725,
+    very_active: 1.9,
+};
+export function bmrValue(weightKg, heightCm, ageYears, sex) {
+    const base = 10 * weightKg + 6.25 * heightCm - 5 * ageYears;
+    return Math.round(sex === 'male' ? base + 5 : base - 161);
+}
+export function bmrTdee(weightKg, heightCm, ageYears, sex, activity) {
+    const basal = bmrValue(weightKg, heightCm, ageYears, sex);
+    return {
+        bmrKcalPerDay: basal,
+        tdeeKcalPerDay: Math.round(basal * ACTIVITY_FACTORS[activity]),
+        activityFactor: ACTIVITY_FACTORS[activity],
+        reference: 'Mifflin-St Jeor equation (educational estimate).',
+    };
+}
+// ── Ideal weight (Devine / Robinson / Miller / Hamwi) ────────────────────────
+export function idealWeightKg(heightCm, sex) {
+    const inchesOver5ft = Math.max(0, cmToIn(heightCm) - 60);
+    const r = (n) => Math.round(n * 10) / 10;
+    const result = sex === 'male'
+        ? {
+            devineKg: r(50 + 2.3 * inchesOver5ft),
+            robinsonKg: r(52 + 1.9 * inchesOver5ft),
+            millerKg: r(56.2 + 1.41 * inchesOver5ft),
+            hamwiKg: r(48 + 2.7 * inchesOver5ft),
+        }
+        : {
+            devineKg: r(45.5 + 2.3 * inchesOver5ft),
+            robinsonKg: r(49 + 1.7 * inchesOver5ft),
+            millerKg: r(53.1 + 1.36 * inchesOver5ft),
+            hamwiKg: r(45.5 + 2.2 * inchesOver5ft),
+        };
+    return {
+        ...result,
+        reference: 'Classic clinical reference formulas (Devine, Robinson, Miller, Hamwi). Population estimate, not a personal target.',
+    };
+}
+export function bloodPressureCategory(systolic, diastolic) {
+    let category;
+    if (systolic > 180 || diastolic > 120)
+        category = 'Hypertensive crisis';
+    else if (systolic >= 140 || diastolic >= 90)
+        category = 'Hypertension stage 2';
+    else if (systolic >= 130 || diastolic >= 80)
+        category = 'Hypertension stage 1';
+    else if (systolic >= 120 && diastolic < 80)
+        category = 'Elevated';
+    else
+        category = 'Normal';
+    return {
+        systolic,
+        diastolic,
+        category,
+        reference: 'ACC/AHA 2017 reference categories (educational). Does not diagnose hypertension — that needs repeated clinical measurement.',
+    };
+}
+// ── Heart-rate training zones (220 - age) ────────────────────────────────────
+export function heartRateZones(ageYears) {
+    const maxHr = 220 - ageYears;
+    const z = (lo, hi) => ({
+        lowBpm: Math.round(maxHr * lo),
+        highBpm: Math.round(maxHr * hi),
+    });
+    return {
+        estimatedMaxHr: maxHr,
+        zones: [
+            { name: 'Zone 1 — Very light', ...z(0.5, 0.6), description: 'Warm-up and recovery' },
+            { name: 'Zone 2 — Light', ...z(0.6, 0.7), description: 'Fat burning, base endurance' },
+            { name: 'Zone 3 — Moderate', ...z(0.7, 0.8), description: 'Aerobic fitness' },
+            { name: 'Zone 4 — Hard', ...z(0.8, 0.9), description: 'Increased performance' },
+            { name: 'Zone 5 — Maximum', ...z(0.9, 1.0), description: 'Maximal effort, short bursts' },
+        ],
+        reference: 'Estimated max HR = 220 − age, with the 5 standard training zones (educational).',
+    };
+}
+// ── A1C <-> average glucose (ADAG) ───────────────────────────────────────────
+export const MGDL_PER_MMOL = 18.0182;
+export function a1c(a1cPercent, avgGlucoseMgDl) {
+    if (a1cPercent != null) {
+        const mgDl = Math.round(28.7 * a1cPercent - 46.7);
+        return {
+            a1cPercent,
+            estAvgGlucoseMgDl: mgDl,
+            estAvgGlucoseMmolL: Math.round((mgDl / MGDL_PER_MMOL) * 10) / 10,
+            reference: 'ADAG formula: eAG(mg/dL) = 28.7 × A1C − 46.7 (educational).',
+        };
+    }
+    if (avgGlucoseMgDl != null) {
+        return {
+            avgGlucoseMgDl,
+            estA1cPercent: Math.round(((avgGlucoseMgDl + 46.7) / 28.7) * 10) / 10,
+            avgGlucoseMmolL: Math.round((avgGlucoseMgDl / MGDL_PER_MMOL) * 10) / 10,
+            reference: 'ADAG formula inverted (educational).',
+        };
+    }
+    return { error: 'Provide either a1cPercent or avgGlucoseMgDl.' };
+}
+// ── Water intake ─────────────────────────────────────────────────────────────
+export function waterIntakeLitres(weightKg, activityMinutes = 0) {
+    const base = weightKg * 0.035;
+    const activityBump = (activityMinutes / 30) * 0.35;
+    return {
+        litresPerDay: Math.round((base + activityBump) * 100) / 100,
+        reference: '~35 ml per kg body weight plus a small activity bump (educational rule of thumb).',
+    };
+}
+export function waistToHeight(waistCm, heightCm) {
+    const ratio = Math.round((waistCm / heightCm) * 100) / 100;
+    let category;
+    if (ratio < 0.4)
+        category = 'Low';
+    else if (ratio < 0.5)
+        category = 'Healthy';
+    else if (ratio < 0.6)
+        category = 'Increased';
+    else
+        category = 'High';
+    return {
+        ratio,
+        category,
+        reference: 'Waist-to-height ratio reference bands (educational).',
+    };
+}
+export const CALCULATORS = [
+    {
+        id: 'bmi',
+        title: 'Body Mass Index',
+        description: 'BMI value, WHO category, and the healthy-weight range for the height.',
+        inputs: ['weightKg', 'heightCm'],
+        reference: 'WHO adult BMI ranges',
+    },
+    {
+        id: 'bmr_tdee',
+        title: 'BMR & TDEE (calories)',
+        description: 'Basal metabolic rate and total daily energy expenditure.',
+        inputs: ['weightKg', 'heightCm', 'ageYears', 'sex', 'activity'],
+        reference: 'Mifflin-St Jeor',
+    },
+    {
+        id: 'ideal_weight',
+        title: 'Ideal body weight',
+        description: 'Devine / Robinson / Miller / Hamwi reference estimates (kg).',
+        inputs: ['heightCm', 'sex'],
+        reference: 'Devine, Robinson, Miller, Hamwi formulas',
+    },
+    {
+        id: 'blood_pressure',
+        title: 'Blood-pressure category',
+        description: 'Maps a systolic/diastolic reading to its ACC/AHA reference category.',
+        inputs: ['systolic', 'diastolic'],
+        reference: 'ACC/AHA 2017 categories',
+    },
+    {
+        id: 'heart_rate_zones',
+        title: 'Heart-rate training zones',
+        description: 'Estimated max HR (220 − age) and the 5 standard training zones.',
+        inputs: ['ageYears'],
+        reference: '220 − age',
+    },
+    {
+        id: 'a1c',
+        title: 'A1C ↔ average glucose',
+        description: 'Convert A1C% to estimated average glucose, or the reverse.',
+        inputs: ['a1cPercent OR avgGlucoseMgDl'],
+        reference: 'ADAG study formula',
+    },
+    {
+        id: 'water_intake',
+        title: 'Daily water intake',
+        description: 'General daily water guidance from body weight and activity minutes.',
+        inputs: ['weightKg', 'activityMinutes?'],
+        reference: '~35 ml/kg rule of thumb',
+    },
+    {
+        id: 'waist_to_height',
+        title: 'Waist-to-height ratio',
+        description: 'Ratio plus its reference band.',
+        inputs: ['waistCm', 'heightCm'],
+        reference: 'Waist-to-height ratio bands',
+    },
+];

package/dist/cqc.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Real Care Quality Commission (CQC) provider dataset, bundled as JSON.
+ *
+ * Source: Care Quality Commission www.cqc.org.uk, crawled into GeraClinic's
+ * `crawled_listings` (vertical='geraclinic', country_code='GB') and snapshotted
+ * from apps/gera-clinic-web/src/data/cqc-cluster.generated.ts. Every record
+ * traces to a real registered provider. Public sector information licensed
+ * under the Open Government Licence v3.0.
+ *
+ * CQC publishes a CATEGORICAL rating scheme
+ * (Outstanding / Good / Requires improvement / Inadequate), never a 0–5 numeric
+ * scale, so this dataset carries NO numeric ratings. The `lastInspected` date
+ * is the real last-checked date for the provider record.
+ */
+export interface CqcServiceTypeBucket {
+    type: string;
+    count: number;
+    pct: number;
+}
+export interface CqcStats {
+    total: number;
+    withPhone: number;
+    withPhonePct: number;
+    withWebsite: number;
+    serviceTypes: CqcServiceTypeBucket[];
+    topServiceType: string | null;
+    latestCheck: string | null;
+}
+export interface CqcProvider {
+    cqcLocationId: string;
+    name: string;
+    providerName: string | null;
+    address: string | null;
+    postcode: string | null;
+    phone: string | null;
+    website: string | null;
+    serviceTypes: string[];
+    lastInspected: string | null;
+}
+export interface CqcLocality {
+    slug: string;
+    outwardCode: string;
+    stats: CqcStats;
+    providers: CqcProvider[];
+}
+export interface CqcAuthority {
+    slug: string;
+    name: string;
+    region: string | null;
+    stats: CqcStats;
+    providers: CqcProvider[];
+    localities: CqcLocality[];
+}
+export interface CqcDataset {
+    meta: {
+        generatedAt: string;
+        totalProviders: number;
+        totalLocalities: number;
+        attribution: string;
+        url: string;
+        attributionUrl: string;
+    };
+    authorities: CqcAuthority[];
+}
+export declare const CQC_META: {
+    generatedAt: string;
+    totalProviders: number;
+    totalLocalities: number;
+    attribution: string;
+    url: string;
+    attributionUrl: string;
+};
+export declare const CQC_AUTHORITIES: CqcAuthority[];
+export declare const CQC_ATTRIBUTION: string;
+export declare const ALL_PROVIDERS: CqcProvider[];
+/** All distinct service-type labels present in the dataset, sorted. */
+export declare const SERVICE_TYPES: string[];
+export interface ProviderSearchParams {
+    query?: string;
+    postcode?: string;
+    serviceType?: string;
+    authority?: string;
+    limit: number;
+}
+export interface ProviderSearchResult {
+    provider: CqcProvider;
+    authoritySlug: string;
+    authorityName: string;
+    region: string | null;
+}
+/**
+ * Search the real CQC dataset. All filters are AND-combined; any omitted.
+ * Matching is case-insensitive substring for name/serviceType, and outward- or
+ * full-postcode prefix for postcode.
+ */
+export declare function searchProviders(params: ProviderSearchParams): ProviderSearchResult[];
+/** Look up one authority or locality area by slug or name. */
+export declare function findArea(slugOrName: string): {
+    kind: 'authority' | 'locality';
+    area: CqcAuthority | CqcLocality;
+    authorityName: string;
+} | null;