@tkawen/ambulancedz-mcp 1.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @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.
+
+## Tools
+
+| 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 |
+
+It talks to the public read-only JSON API at `{BASE}/api/v1`. No credentials needed.
+
+## Install & run
+
+```bash
+npm install
+node src/index.js          # stdio MCP server
+npm test                   # smoke test against the live API
+```
+
+## Configure
+
+| Env | Default | Purpose |
+|-----|---------|---------|
+| `AMBULANCEDZ_BASE_URL` | `https://ambulancedz.com` | Target platform base URL |
+
+## Use with Claude Desktop / Claude Code
+
+Add to your MCP config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ambulancedz": {
+      "command": "node",
+      "args": ["D:/PROJECTS/05-OTHER-PROJECTS/ambulancedz-mcp/src/index.js"]
+    }
+  }
+}
+```
+
+Or, once published: `"command": "npx", "args": ["-y", "@tkawen/ambulancedz-mcp"]`.
+
+## License
+
+MIT © TKAWEN

package/package.json

@@ -0,0 +1,34 @@
+{
+  "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.",
+  "type": "module",
+  "bin": {
+    "ambulancedz-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test/smoke.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ambulance",
+    "algeria",
+    "ambulancedz",
+    "tkawen"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}

package/src/index.js

@@ -0,0 +1,168 @@
+#!/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.
+ *
+ * Talks to the public read-only JSON API at {BASE}/api/v1.
+ * Configure the target with AMBULANCEDZ_BASE_URL (default https://ambulancedz.com).
+ */
+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(/\/+$/, "");
+const API = BASE + "/api/v1";
+
+async function api(path, params) {
+  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 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;
+}
+
+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 server = new McpServer({ name: "ambulancedz", version: "1.1.0" });
+
+server.tool(
+  "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.",
+  {},
+  async () => {
+    try { return ok(await api("/wilayas")); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "list_communes",
+  "List the communes (municipalities) of a wilaya, by the wilaya id from list_wilayas.",
+  { wilaya_id: z.number().int().describe("Wilaya id") },
+  async ({ wilaya_id }) => {
+    try { return ok(await api(`/wilayas/${wilaya_id}/communes`)); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "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)"),
+  },
+  async (args) => {
+    try { return ok(await api("/ambulances", args)); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "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)"),
+  },
+  async ({ lat, lng }) => {
+    try { return ok(await api("/ambulances/nearest", { lat, lng })); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "get_ambulance",
+  "Get full details of a single ambulance/driver by id (phone, plate, location, rating, verification).",
+  { id: z.number().int().describe("Ambulance id") },
+  async ({ id }) => {
+    try { return ok(await api(`/ambulances/${id}`)); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "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)"),
+  },
+  async (args) => {
+    try { return ok(await api("/price-estimate", args)); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "platform_stats",
+  "Get Ambulance.dz platform stats: total / verified / available drivers, wilaya coverage, commune count and average rating.",
+  {},
+  async () => {
+    try { return ok(await api("/stats")); } catch (e) { return fail(e); }
+  }
+);
+
+server.tool(
+  "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)"),
+  },
+  async (args) => {
+    try { return ok(await apiPost("/recurring-bookings", args)); } catch (e) { return fail(e); }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`ambulancedz MCP server ready — base: ${BASE}`);