@tkawen/ambulancedz-mcp 1.1.0 → 2.0.0

package/README.md

@@ -1,32 +1,90 @@
 # @tkawen/ambulancedz-mcp
 
-MCP server for **[Ambulance.dz](https://ambulancedz.com)** — Algeria's 69-wilaya
-ambulance / medical-transport marketplace. Lets any MCP client (Claude Desktop,
-Claude Code, etc.) find ambulances, locate the nearest available one by GPS,
-estimate a trip's cost, and read live platform stats.
+MCP server for **[ambulancedz.com](https://ambulancedz.com)** — Algeria's ambulance
+and medical-transport marketplace across all 69 wilayas. It lets any MCP client
+(Claude Desktop, Claude Code, …) find and vet ambulance drivers, locate the
+nearest available one by GPS, read a driver's reviews, estimate a trip's cost,
+check coverage, and set up recurring dialysis transport.
 
-## Tools
+## ⚠️ Read this first
+
+**ambulancedz is a directory of private ambulance operators. It is not a
+government ambulance service and not an emergency dispatch centre.** It does not
+send anyone, and it cannot guarantee availability or response time.
+
+In a life-threatening emergency in Algeria, call these first:
+
+| Number | Service |
+|--------|---------|
+| **14** | الحماية المدنية — Civil Protection |
+| **16** | الاستعجالات الطبية — SAMU (medical) |
+| **17** | الأمن الوطني — National Police |
+
+Every tool that returns drivers also returns a `safety` object carrying these
+numbers, and `emergency_numbers` answers from a built-in constant even if the
+API is unreachable. If you extend this server, keep that property.
+
+## Tools (12)
 
 | Tool | Description |
 |------|-------------|
 | `list_wilayas` | All 69 wilayas with driver counts + how many are available now |
 | `list_communes` | Communes of a wilaya (by id) |
-| `search_ambulances` | Search drivers by wilaya / commune / service type / status (verified first) |
-| `find_nearest_ambulance` | Nearest **available** ambulances to a GPS point, with distance + ETA |
-| `get_ambulance` | Full details of one driver by id |
-| `estimate_price` | Estimated DZD cost range for a trip between two wilayas |
-| `platform_stats` | Drivers / verified / available / coverage / avg rating |
+| `search_ambulances` | Search drivers by wilaya / commune / service type / status / **verified**, with sorting |
+| `find_nearest_ambulance` | Nearest **available** ambulances to a GPS point, with real distance + ETA |
+| `get_ambulance` | Full details of one driver: phone, WhatsApp, plate, coordinates, gallery, member-since |
+| `get_ambulance_reviews` | A driver's reviews **plus the star distribution**, so a rating can be reconciled against its evidence |
+| `estimate_price` | Indicative DZD cost **range** for a trip between two wilayas |
+| `platform_stats` | Drivers / verified / available / coverage / average rating |
+| `coverage_report` | Per-wilaya coverage **including the wilayas with no drivers at all** |
+| `emergency_numbers` | Algeria's national emergency numbers and what each is for |
+| `driver_join_info` | For ambulance owners: trial length, plans and prices, payment methods, verification documents |
+| `request_recurring_booking` | ✍️ Register a recurring (dialysis) transport request — creates a **pending** booking |
+
+All tools are read-only except `request_recurring_booking`, and they are
+annotated as such (`readOnlyHint`) so clients can treat them accordingly.
+
+### Resources
 
-It talks to the public read-only JSON API at `{BASE}/api/v1`. No credentials needed.
+| URI | Contents |
+|-----|----------|
+| `ambulancedz://safety` | What the platform is and is not, plus the emergency numbers |
+| `ambulancedz://coverage` | Live per-wilaya driver coverage |
+
+### Prompts
+
+| Prompt | Purpose |
+|--------|---------|
+| `find_ambulance` | Guided, safety-first flow for finding an ambulance |
+| `plan_dialysis_transport` | Guided flow for setting up recurring dialysis transport |
+
+## Honesty guarantees
+
+These are enforced by the API this server reads, and are worth preserving in any
+client that presents the data:
+
+- **A rating with no reviews behind it is returned as `null`**, never as a score.
+  `get_ambulance_reviews` returns a star breakdown that always sums to the
+  reported total.
+- **Prices are ranges, not quotes.** The platform is not party to the agreement
+  between patient and driver, and takes no commission on trips.
+- **«موثّق» (verified) means a human reviewed the driver's licence, vehicle
+  registration and vehicle photo.** Drivers who are not verified are reported as
+  not verified rather than being quietly presented the same way.
+- **Availability is whatever the driver last set** — `status` and
+  `last_active_at` are reported as-is, with no invented green dots.
 
 ## Install & run
 
 ```bash
 npm install
 node src/index.js          # stdio MCP server
-npm test                   # smoke test against the live API
+npm test                   # full smoke test against the live API
 ```
 
+The smoke test creates one pending recurring booking to exercise the write path
+and prints its id — delete it from the admin panel afterwards.
+
 ## Configure
 
 | Env | Default | Purpose |
@@ -37,6 +95,19 @@ npm test                   # smoke test against the live API
 
 Add to your MCP config (e.g. `claude_desktop_config.json`):
 
+```json
+{
+  "mcpServers": {
+    "ambulancedz": {
+      "command": "npx",
+      "args": ["-y", "@tkawen/ambulancedz-mcp"]
+    }
+  }
+}
+```
+
+Running from a local checkout instead:
+
 ```json
 {
   "mcpServers": {
@@ -48,7 +119,14 @@ Add to your MCP config (e.g. `claude_desktop_config.json`):
 }
 ```
 
-Or, once published: `"command": "npx", "args": ["-y", "@tkawen/ambulancedz-mcp"]`.
+## Underlying API
+
+Public, read-only, no credentials: `https://ambulancedz.com/api/v1`
+
+`/wilayas` · `/wilayas/{id}/communes` · `/ambulances` · `/ambulances/nearest` ·
+`/ambulances/{id}` · `/ambulances/{id}/reviews` · `/price-estimate` · `/stats` ·
+`/coverage` · `/driver-plans` · `/emergency-numbers` ·
+`POST /recurring-bookings` (rate-limited)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tkawen/ambulancedz-mcp",
-  "version": "1.1.0",
-  "description": "MCP server for Ambulance.dz — find ambulances, locate the nearest available one, estimate trip cost, and query Algeria's 69-wilaya emergency-transport marketplace.",
+  "version": "2.0.0",
+  "description": "MCP server for ambulancedz.com — Algeria's ambulance marketplace: find and vet ambulance drivers across 69 wilayas, locate the nearest available one by GPS, read driver reviews, estimate trip cost, check coverage, and book recurring dialysis transport.",
   "type": "module",
   "bin": {
     "ambulancedz-mcp": "src/index.js"
@@ -24,7 +24,10 @@
     "ambulance",
     "algeria",
     "ambulancedz",
-    "tkawen"
+    "tkawen",
+    "dialysis",
+    "emergency",
+    "healthcare"
   ],
   "license": "MIT",
   "dependencies": {

package/src/index.js

@@ -1,10 +1,21 @@
 #!/usr/bin/env node
 /**
- * Ambulance.dz MCP server
- * ------------------------
- * Exposes Algeria's ambulance-transport marketplace (ambulancedz.com) as MCP
- * tools: list wilayas/communes, search drivers, find the nearest available
- * ambulance by GPS, estimate trip cost, and read platform stats.
+ * ambulancedz MCP server
+ * ----------------------
+ * Exposes Algeria's ambulance-transport marketplace (ambulancedz.com) over MCP:
+ * discover wilayas/communes, search drivers, find the nearest available
+ * ambulance by GPS, read a driver's reviews, estimate trip cost, check coverage,
+ * read the driver subscription offer, and register recurring (dialysis)
+ * transport.
+ *
+ * SAFETY — read before adding tools:
+ * ambulancedz is a directory of PRIVATE ambulance operators. It is NOT a
+ * government ambulance service and NOT an emergency dispatch centre. A client
+ * of this server may be an AI assistant acting for someone in a life-threatening
+ * situation, so every tool that returns drivers also returns Algeria's national
+ * emergency numbers and states they should be called first. Do not remove that
+ * field, and do not add a tool implying this platform dispatches anyone or
+ * guarantees a response.
  *
  * Talks to the public read-only JSON API at {BASE}/api/v1.
  * Configure the target with AMBULANCEDZ_BASE_URL (default https://ambulancedz.com).
@@ -13,37 +24,51 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
-const BASE = (process.env.AMBULANCEDZ_BASE_URL || "https://ambulancedz.com").replace(/\/+$/, "");
+/** Trim trailing slashes without a backtracking-prone regex. */
+function trimTrailingSlashes(s) {
+  let end = s.length;
+  while (end > 0 && s[end - 1] === "/") end--;
+  return s.slice(0, end);
+}
+
+const BASE = trimTrailingSlashes(process.env.AMBULANCEDZ_BASE_URL || "https://ambulancedz.com");
 const API = BASE + "/api/v1";
+const VERSION = "2.0.0";
 
-async function api(path, params) {
+/** Everything here reads public data; only request_recurring_booking writes. */
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+
+/** Attached to every response that returns drivers. */
+const SAFETY = {
+  life_threatening_call_first: [
+    { number: "14", ar: "الحماية المدنية" },
+    { number: "16", ar: "الاستعجالات الطبية SAMU" },
+    { number: "17", ar: "الأمن الوطني" },
+  ],
+  notice_en:
+    "ambulancedz lists private ambulance operators; it does not dispatch them and cannot guarantee availability or response time. In a life-threatening emergency, call 14 / 16 / 17 first.",
+  notice_ar:
+    "ambulancedz دليل لسائقي إسعاف خواص — لا يرسلهم ولا يضمن التوفر أو زمن الوصول. في حالة خطر على الحياة اتصل بـ 14 / 16 / 17 أولاً.",
+};
+
+async function request(path, { method = "GET", params, body } = {}) {
   const url = new URL(API + path);
   if (params) {
     for (const [k, v] of Object.entries(params)) {
       if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
     }
   }
-  const res = await fetch(url, { headers: { Accept: "application/json" } });
-  const text = await res.text();
-  let json;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    json = { raw: text.slice(0, 500) };
-  }
-  if (!res.ok) {
-    const msg = json?.error || json?.message || JSON.stringify(json);
-    throw new Error(`HTTP ${res.status}: ${msg}`);
-  }
-  return json;
-}
 
-async function apiPost(path, body) {
-  const res = await fetch(API + path, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", Accept: "application/json" },
-    body: JSON.stringify(body),
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Accept: "application/json",
+      "User-Agent": `ambulancedz-mcp/${VERSION}`,
+      ...(body ? { "Content-Type": "application/json" } : {}),
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
   });
+
   const text = await res.text();
   let json;
   try {
@@ -51,118 +76,406 @@ async function apiPost(path, body) {
   } catch {
     json = { raw: text.slice(0, 500) };
   }
+
   if (!res.ok) {
-    const msg = json?.error || json?.message || JSON.stringify(json);
-    throw new Error(`HTTP ${res.status}: ${msg}`);
+    // Surface Laravel validation errors usefully instead of "[object Object]".
+    const detail =
+      json?.error ||
+      json?.message ||
+      (json?.errors ? Object.values(json.errors).flat().join("; ") : null) ||
+      JSON.stringify(json).slice(0, 300);
+    throw new Error(`HTTP ${res.status}: ${detail}`);
   }
   return json;
 }
 
+const api = (path, params) => request(path, { params });
+const apiPost = (path, body) => request(path, { method: "POST", body });
+
 const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
-const fail = (e) => ({ content: [{ type: "text", text: "Error: " + (e?.message || String(e)) }], isError: true });
+const okDrivers = (data) => ok({ ...data, safety: SAFETY });
+const fail = (e) => ({
+  content: [{ type: "text", text: "Error: " + (e?.message || String(e)) }],
+  isError: true,
+});
+
+const server = new McpServer({ name: "ambulancedz", version: VERSION });
 
-const server = new McpServer({ name: "ambulancedz", version: "1.1.0" });
+/* ─────────────────────────── Discovery ─────────────────────────── */
 
-server.tool(
+server.registerTool(
   "list_wilayas",
-  "List all 69 Algerian wilayas (provinces) with the number of listed ambulance drivers and how many are available right now in each. Use this to discover wilaya ids.",
-  {},
+  {
+    title: "List Algerian wilayas",
+    description:
+      "List all 69 Algerian wilayas (provinces) with how many ambulance drivers are listed and how many are available right now in each. Use this to resolve a wilaya name to the id other tools need.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+  },
   async () => {
-    try { return ok(await api("/wilayas")); } catch (e) { return fail(e); }
+    try {
+      return ok(await api("/wilayas"));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+server.registerTool(
   "list_communes",
-  "List the communes (municipalities) of a wilaya, by the wilaya id from list_wilayas.",
-  { wilaya_id: z.number().int().describe("Wilaya id") },
+  {
+    title: "List communes of a wilaya",
+    description: "List the communes (municipalities) of a wilaya, by the wilaya id from list_wilayas.",
+    inputSchema: { wilaya_id: z.number().int().describe("Wilaya id") },
+    annotations: READ_ONLY,
+  },
   async ({ wilaya_id }) => {
-    try { return ok(await api(`/wilayas/${wilaya_id}/communes`)); } catch (e) { return fail(e); }
+    try {
+      return ok(await api(`/wilayas/${wilaya_id}/communes`));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+/* ─────────────────────────── Finding a driver ─────────────────────────── */
+
+server.registerTool(
   "search_ambulances",
-  "Search listed ambulance drivers, optionally filtered by wilaya, commune, service type or availability. Verified drivers and higher ratings come first.",
   {
-    wilaya: z.number().int().optional().describe("Wilaya id"),
-    commune: z.number().int().optional().describe("Commune id"),
-    service_type: z.enum(["emergency", "transport", "inter_wilaya"]).optional(),
-    status: z.enum(["available", "busy", "offline"]).optional(),
-    per_page: z.number().int().min(1).max(50).optional().describe("Results per page (max 50)"),
+    title: "Search ambulance drivers",
+    description:
+      "Search listed ambulance drivers, filtered by wilaya, commune, service type, availability or verification. Returns phone, licence plate, status, rating and profile URL. Available drivers come first, then verified, then best-rated.",
+    inputSchema: {
+      wilaya: z.number().int().optional().describe("Wilaya id (from list_wilayas)"),
+      commune: z.number().int().optional().describe("Commune id (from list_communes)"),
+      service_type: z
+        .enum(["emergency", "transport", "inter_wilaya"])
+        .optional()
+        .describe("emergency = urgent case, transport = medical transfer, inter_wilaya = between provinces"),
+      status: z.enum(["available", "busy", "offline"]).optional(),
+      verified: z.boolean().optional().describe("Only drivers whose documents were manually reviewed"),
+      sort: z.enum(["best", "rating", "reviews", "newest"]).optional().describe("Default: best (available first)"),
+      per_page: z.number().int().min(1).max(50).optional().describe("Results per page (max 50)"),
+    },
+    annotations: READ_ONLY,
   },
   async (args) => {
-    try { return ok(await api("/ambulances", args)); } catch (e) { return fail(e); }
+    try {
+      return okDrivers(await api("/ambulances", { ...args, verified: args.verified ? 1 : undefined }));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+server.registerTool(
   "find_nearest_ambulance",
-  "Find the nearest AVAILABLE ambulances to a GPS location inside Algeria, sorted by distance, with a rough ETA in minutes.",
   {
-    lat: z.number().describe("Latitude (within Algeria, ~18..38)"),
-    lng: z.number().describe("Longitude (within Algeria, ~-9..12)"),
+    title: "Find nearest available ambulance",
+    description:
+      "Find the nearest AVAILABLE ambulances to a GPS point inside Algeria, sorted by real distance, with a rough ETA in minutes. Use when you have the patient's coordinates; otherwise use search_ambulances by wilaya.",
+    inputSchema: {
+      lat: z.number().describe("Latitude — must be inside Algeria (~18..38)"),
+      lng: z.number().describe("Longitude — must be inside Algeria (~-9..12)"),
+    },
+    annotations: READ_ONLY,
   },
   async ({ lat, lng }) => {
-    try { return ok(await api("/ambulances/nearest", { lat, lng })); } catch (e) { return fail(e); }
+    try {
+      return okDrivers(await api("/ambulances/nearest", { lat, lng }));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+server.registerTool(
   "get_ambulance",
-  "Get full details of a single ambulance/driver by id (phone, plate, location, rating, verification).",
-  { id: z.number().int().describe("Ambulance id") },
+  {
+    title: "Get driver details",
+    description:
+      "Get full details of one driver by id: phone, WhatsApp, licence plate, exact coordinates, verification date, vehicle photo gallery, rating and member-since date.",
+    inputSchema: { id: z.number().int().describe("Ambulance id") },
+    annotations: READ_ONLY,
+  },
   async ({ id }) => {
-    try { return ok(await api(`/ambulances/${id}`)); } catch (e) { return fail(e); }
+    try {
+      return okDrivers(await api(`/ambulances/${id}`));
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+
+server.registerTool(
+  "get_ambulance_reviews",
+  {
+    title: "Read a driver's reviews",
+    description:
+      "Read the reviews of one driver, with the star distribution (how many 5-star, 4-star …). The headline rating is computed from these rows, so it can always be reconciled against its evidence. A driver with no reviews returns rating null rather than a fabricated score.",
+    inputSchema: {
+      id: z.number().int().describe("Ambulance id"),
+      per_page: z.number().int().min(1).max(50).optional().describe("Reviews per page (max 50, default 10)"),
+    },
+    annotations: READ_ONLY,
+  },
+  async ({ id, per_page }) => {
+    try {
+      return ok(await api(`/ambulances/${id}/reviews`, { per_page }));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+/* ─────────────────────────── Cost ─────────────────────────── */
+
+server.registerTool(
   "estimate_price",
-  "Estimate the approximate cost range (DZD) of an ambulance trip between two wilayas. Indicative only — the final price is agreed with the driver.",
   {
-    from_wilaya: z.number().int().describe("Pickup wilaya id"),
-    to_wilaya: z.number().int().describe("Destination wilaya id"),
-    service: z.enum(["basic", "equipped"]).optional().describe("basic (default) or medically-equipped"),
-    night: z.boolean().optional().describe("Night-time pricing (×1.4)"),
+    title: "Estimate trip cost",
+    description:
+      "Estimate the approximate cost range (DZD) of an ambulance trip between two wilayas. INDICATIVE ONLY — the platform is not party to the agreement and the final price is settled directly with the driver. Always present it as a range, never as a quoted price.",
+    inputSchema: {
+      from_wilaya: z.number().int().describe("Pickup wilaya id"),
+      to_wilaya: z.number().int().describe("Destination wilaya id"),
+      service: z.enum(["basic", "equipped"]).optional().describe("basic (default) or medically-equipped"),
+      night: z.boolean().optional().describe("Night-time pricing (×1.4)"),
+    },
+    annotations: READ_ONLY,
   },
   async (args) => {
-    try { return ok(await api("/price-estimate", args)); } catch (e) { return fail(e); }
+    try {
+      return ok(await api("/price-estimate", args));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+/* ─────────────────────────── Platform ─────────────────────────── */
+
+server.registerTool(
   "platform_stats",
-  "Get Ambulance.dz platform stats: total / verified / available drivers, wilaya coverage, commune count and average rating.",
-  {},
+  {
+    title: "Platform statistics",
+    description:
+      "Platform totals: listed drivers, verified drivers, available right now, wilaya coverage, commune count, average rating.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+  },
+  async () => {
+    try {
+      return ok(await api("/stats"));
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+
+server.registerTool(
+  "coverage_report",
+  {
+    title: "Coverage by wilaya",
+    description:
+      "Per-wilaya coverage: how many drivers, how many available now, how many verified — including the wilayas with NO drivers at all. Use this to answer 'is my area covered?' and to see where supply is missing.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+  },
+  async () => {
+    try {
+      return ok(await api("/coverage"));
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+
+server.registerTool(
+  "emergency_numbers",
+  {
+    title: "Algeria emergency numbers",
+    description:
+      "Algeria's national emergency numbers (14 Civil Protection, 16 SAMU medical, 17 Police) and what each is for. Call this FIRST for any life-threatening situation — ambulancedz lists private operators and does not dispatch emergency services.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+  },
   async () => {
-    try { return ok(await api("/stats")); } catch (e) { return fail(e); }
+    try {
+      return ok(await api("/emergency-numbers"));
+    } catch {
+      // Emergency numbers must survive an API outage — they are constants.
+      return ok({
+        data: {
+          country: "DZ",
+          numbers: SAFETY.life_threatening_call_first,
+          notice_ar: SAFETY.notice_ar,
+          notice_en: SAFETY.notice_en,
+          note: "Served from the client's built-in fallback: the ambulancedz API was unreachable.",
+        },
+      });
+    }
+  }
+);
+
+/* ─────────────────────────── Drivers (supply side) ─────────────────────────── */
+
+server.registerTool(
+  "driver_join_info",
+  {
+    title: "How ambulance owners join",
+    description:
+      "For ambulance OWNERS asking how to join ambulancedz: the free-trial length, the subscription plans and prices in DZD (with the per-month equivalent), accepted payment methods, the documents required for the «موثّق» verified badge, and the registration URL. There is no commission on trips.",
+    inputSchema: {},
+    annotations: READ_ONLY,
+  },
+  async () => {
+    try {
+      return ok(await api("/driver-plans"));
+    } catch (e) {
+      return fail(e);
+    }
   }
 );
 
-server.tool(
+/* ─────────────────────────── Recurring transport (write) ─────────────────────────── */
+
+server.registerTool(
   "request_recurring_booking",
-  "Register a recurring (dialysis / chronic-care) transport request for a patient. Creates a PENDING booking that awaits a driver's acceptance. Find ids with list_wilayas / list_communes, and optionally pick a preferred driver with search_ambulances.",
-  {
-    patient_name: z.string().describe("Patient full name"),
-    patient_phone: z.string().describe("Algerian mobile, e.g. 0551234567"),
-    pickup_wilaya_id: z.number().int().describe("Pickup wilaya id"),
-    dest_wilaya_id: z.number().int().describe("Destination (dialysis centre/hospital) wilaya id"),
-    days: z.array(z.number().int().min(0).max(6)).min(1).describe("Weekdays: 0=Sunday .. 6=Saturday, e.g. [0,2,4]"),
-    time: z.string().describe("Pickup time HH:MM (24h), e.g. 07:00"),
-    pickup_commune_id: z.number().int().optional(),
-    dest_commune_id: z.number().int().optional(),
-    pickup_note: z.string().optional().describe("Exact pickup address / landmark"),
-    dest_note: z.string().optional().describe("Hospital / dialysis centre name"),
-    service_type: z.enum(["emergency", "transport", "inter_wilaya"]).optional(),
-    ambulance_id: z.number().int().optional().describe("Preferred driver id (from search_ambulances)"),
-    notes: z.string().optional().describe("Patient condition notes (e.g. needs a wheelchair)"),
+  {
+    title: "Request recurring dialysis transport",
+    description:
+      "Register a recurring (dialysis / chronic-care) transport request for a patient — e.g. three trips a week to the same centre with the same driver. Creates a PENDING booking that a driver must accept; it is NOT a confirmation. Resolve ids first with list_wilayas / list_communes, and optionally pick a preferred driver with search_ambulances.",
+    inputSchema: {
+      patient_name: z.string().describe("Patient full name"),
+      patient_phone: z.string().describe("Algerian mobile, e.g. 0551234567"),
+      pickup_wilaya_id: z.number().int().describe("Pickup wilaya id"),
+      dest_wilaya_id: z.number().int().describe("Destination (dialysis centre/hospital) wilaya id"),
+      days: z
+        .array(z.number().int().min(0).max(6))
+        .min(1)
+        .describe("Weekdays: 0=Sunday .. 6=Saturday, e.g. [0,2,4] for Sun/Tue/Thu"),
+      time: z.string().describe("Pickup time HH:MM (24h), e.g. 07:00"),
+      pickup_commune_id: z.number().int().optional(),
+      dest_commune_id: z.number().int().optional(),
+      pickup_note: z.string().optional().describe("Exact pickup address / landmark"),
+      dest_note: z.string().optional().describe("Hospital / dialysis centre name"),
+      service_type: z.enum(["emergency", "transport", "inter_wilaya"]).optional(),
+      ambulance_id: z.number().int().optional().describe("Preferred driver id (from search_ambulances)"),
+      notes: z.string().optional().describe("Patient condition notes (e.g. needs a wheelchair)"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
   },
   async (args) => {
-    try { return ok(await apiPost("/recurring-bookings", args)); } catch (e) { return fail(e); }
+    try {
+      return ok(await apiPost("/recurring-bookings", args));
+    } catch (e) {
+      return fail(e);
+    }
+  }
+);
+
+/* ─────────────────────────── Resources ─────────────────────────── */
+
+server.registerResource(
+  "safety-notice",
+  "ambulancedz://safety",
+  {
+    title: "Safety notice",
+    description: "What ambulancedz is and is not, plus Algeria's national emergency numbers.",
+    mimeType: "application/json",
+  },
+  async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(SAFETY, null, 2) }],
+  })
+);
+
+server.registerResource(
+  "coverage-snapshot",
+  "ambulancedz://coverage",
+  {
+    title: "Coverage snapshot",
+    description: "Live per-wilaya driver coverage across Algeria's 69 wilayas.",
+    mimeType: "application/json",
+  },
+  async (uri) => {
+    const data = await api("/coverage");
+    return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(data, null, 2) }] };
   }
 );
 
+/* ─────────────────────────── Prompts ─────────────────────────── */
+
+server.registerPrompt(
+  "find_ambulance",
+  {
+    title: "Find an ambulance",
+    description: "Guided flow for helping someone find an ambulance in Algeria, safely.",
+    argsSchema: {
+      location: z.string().describe("Where the patient is — a wilaya, commune, or 'lat,lng'"),
+      situation: z.string().optional().describe("Brief description of the case"),
+    },
+  },
+  ({ location, situation }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Help find an ambulance in Algeria. Patient location: ${location}.`,
+            situation ? `Situation: ${situation}` : "",
+            "",
+            "Follow this order:",
+            "1. If this sounds life-threatening, give the national emergency numbers (14 / 16 / 17) FIRST and say plainly that ambulancedz lists private operators and does not dispatch them.",
+            "2. Resolve the location: use find_nearest_ambulance if you have coordinates, otherwise list_wilayas then search_ambulances.",
+            "3. Prefer drivers who are available now and verified. Show name, phone, licence plate, distance/ETA and whether they are verified.",
+            "4. If the person asks about cost, use estimate_price and present it as an indicative RANGE, never a quoted price.",
+            "5. Never invent a phone number, a plate, an ETA or a rating — report only what the tools returned.",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        },
+      },
+    ],
+  })
+);
+
+server.registerPrompt(
+  "plan_dialysis_transport",
+  {
+    title: "Plan dialysis transport",
+    description: "Guided flow for setting up recurring dialysis transport for a chronic patient.",
+    argsSchema: {
+      patient_area: z.string().describe("Where the patient lives (wilaya / commune)"),
+      centre: z.string().optional().describe("Dialysis centre or hospital name"),
+    },
+  },
+  ({ patient_area, centre }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Set up recurring dialysis transport. Patient area: ${patient_area}.`,
+            centre ? `Destination centre: ${centre}` : "",
+            "",
+            "Steps:",
+            "1. Resolve wilaya/commune ids with list_wilayas and list_communes.",
+            "2. Suggest a preferred driver with search_ambulances (verified: true), and check get_ambulance_reviews before recommending one.",
+            "3. Collect: patient name, Algerian mobile, weekdays (0=Sunday..6=Saturday), pickup time, and pickup/destination addresses.",
+            "4. Call request_recurring_booking, then state clearly that it is a PENDING request awaiting the driver's acceptance — not a confirmed booking.",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        },
+      },
+    ],
+  })
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`ambulancedz MCP server ready — base: ${BASE}`);
+console.error(`ambulancedz MCP server v${VERSION} ready — base: ${BASE}`);