bayane 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# bayane
+
+CLI and MCP server for hospital satisfaction survey data.
+
+## Install
+
+```bash
+npm install -g @anouar-bm/bayane
+```
+
+Or run without installing:
+
+```bash
+npx @anouar-bm/bayane setup
+```
+
+## Quick start
+
+```bash
+bayane setup      # enter your API URL and key
+bayane stats      # satisfaction stats for the last 7 days
+```
+
+## Commands
+
+```bash
+bayane setup                     # configure API URL and key (~/.health-survey-rc)
+bayane whoami                    # show current config
+bayane stats                     # stats for last 7 days
+bayane stats --period 30d        # stats for last 30 days
+bayane stats --period all        # all-time stats
+bayane alerts                    # critical alerts from last 7 days
+bayane report --latest           # download latest PDF report
+bayane report --date 2026-03-21  # download report for a specific date
+bayane report --output ~/out.pdf # save to a custom path
+```
+
+## Auth
+
+`bayane setup` stores an API key (`sk_*`) in `~/.health-survey-rc` (mode 0600). Keys are created from the admin dashboard and never expire.
+
+## MCP server
+
+`bayane` also ships as an [MCP](https://modelcontextprotocol.io) server so Claude Code and claude.ai can query hospital data directly.
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "health-survey": {
+    "command": "node",
+    "args": ["<path-to>/node_modules/@anouar-bm/bayane/dist/mcp/index.js"]
+  }
+}
+```
+
+Available MCP tools: `get_stats`, `get_alerts`, `download_report`, `display_report`.
+
+## Claude Code skill
+
+Install the companion skill for natural-language queries inside Claude Code:
+
+```bash
+npx skills add https://github.com/anouar-bm/bayane
+```
+
+Then use `/bayane` inside any Claude Code session to ask questions like _"show me NPS for the last 30 days"_.
+
+## Requirements
+
+- Node.js >= 18
+- Access to a running [1337 hospital survey API](https://github.com/anouar-bm/1337)

package/dist/cli/index.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { password, input } from "@inquirer/prompts";
+import { writeFileSync } from "fs";
+import { spawnSync } from "child_process";
+import { loadConfig, saveConfig, CONFIG_PATH } from "../core/config.js";
+import { fetchStats, fetchReportPdf, fetchLatestReportDate } from "../core/api.js";
+import { formatStats, formatAlerts } from "../core/format.js";
+const DEFAULT_API_URL = "https://health-bd.nonas.app";
+const program = new Command();
+program.name("bayane").description("Hospital satisfaction survey CLI").version("1.0.0");
+// bayane setup
+program
+    .command("setup")
+    .description("Configure API URL and API key")
+    .action(async () => {
+    const apiUrl = await input({ message: "API URL:", default: DEFAULT_API_URL });
+    const apiKey = await password({ message: "API key (sk_...):" });
+    saveConfig({ apiUrl, apiKey });
+    console.log(`✓ Config saved to ${CONFIG_PATH}`);
+});
+// bayane whoami
+program
+    .command("whoami")
+    .description("Show current config")
+    .action(() => {
+    const config = loadConfig();
+    console.log(`API URL: ${config.apiUrl}`);
+    console.log(`API key: ${config.apiKey.slice(0, 8)}...`);
+});
+// bayane stats
+program
+    .command("stats")
+    .description("Show satisfaction statistics")
+    .option("--period <period>", "7d, 30d, or all", "7d")
+    .action(async (opts) => {
+    try {
+        const config = loadConfig();
+        const data = await fetchStats(config, opts.period);
+        console.log(formatStats(data, opts.period));
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// bayane report
+program
+    .command("report")
+    .description("Download a daily PDF report")
+    .option("--date <date>", "YYYY-MM-DD (defaults to latest available)")
+    .option("--latest", "Download the most recent available report")
+    .option("--output <path>", "Output file path")
+    .action(async (opts) => {
+    try {
+        const config = loadConfig();
+        const date = opts.date ??
+            (opts.latest
+                ? await fetchLatestReportDate(config)
+                : new Date().toISOString().split("T")[0]);
+        const outPath = opts.output ?? `report-${date}.pdf`;
+        const buffer = await fetchReportPdf(config, date);
+        writeFileSync(outPath, buffer);
+        console.log(`✓ Report saved to ${outPath}`);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// bayane alerts
+program
+    .command("alerts")
+    .description("Show critical alerts from the last 7 days")
+    .action(async () => {
+    try {
+        const config = loadConfig();
+        const data = await fetchStats(config, "7d");
+        console.log(formatAlerts(data));
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// bayane install
+program
+    .command("install")
+    .description("Install the bayane skill for your AI agent")
+    .action(() => {
+    console.log("Installing bayane skill...");
+    spawnSync("npx", ["skills", "add", "anouar-bm/bayane"], { stdio: "inherit" });
+});
+program.parse();

package/dist/core/api.js

@@ -0,0 +1,62 @@
+const TIMEOUT_MS = 10_000;
+async function apiFetch(config, path) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(`${config.apiUrl}${path}`, {
+            headers: { Authorization: `Bearer ${config.apiKey}` },
+            signal: controller.signal,
+        });
+        if (res.status === 401)
+            throw new Error("Invalid API key. Run: bayane setup");
+        if (!res.ok) {
+            const text = await res.text().catch(() => res.statusText);
+            throw new Error(`API error ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error("Request timed out. Check your connection.");
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchStats(config, period) {
+    return apiFetch(config, `/api/analytics?range=${period}`);
+}
+export async function fetchReportPdf(config, date) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const res = await fetch(`${config.apiUrl}/api/reports/${date}/pdf`, {
+            headers: { Authorization: `Bearer ${config.apiKey}` },
+            signal: controller.signal,
+        });
+        if (res.status === 401)
+            throw new Error("Invalid API key. Run: bayane setup");
+        if (res.status === 404)
+            throw new Error(`No report found for ${date}`);
+        if (!res.ok)
+            throw new Error(`Failed to download report: ${res.status}`);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error("Report download timed out.");
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchLatestReportDate(config) {
+    const reports = await apiFetch(config, "/api/reports");
+    if (!reports.length)
+        throw new Error("No reports available yet.");
+    return reports[0].date;
+}

package/dist/core/api.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { fetchStats, fetchReportPdf, fetchLatestReportDate } from "./api.js";
+const mockConfig = { apiUrl: "https://test.example.com", apiKey: "sk_test" };
+beforeEach(() => {
+    vi.resetAllMocks();
+});
+describe("fetchStats", () => {
+    it("throws on 401", async () => {
+        vi.stubGlobal("fetch", async () => ({ ok: false, status: 401, json: async () => ({}) }));
+        await expect(fetchStats(mockConfig, "7d")).rejects.toThrow("Invalid API key");
+    });
+    it("throws on network timeout", async () => {
+        vi.stubGlobal("fetch", () => new Promise((_, reject) => {
+            const err = new Error("aborted");
+            err.name = "AbortError";
+            setTimeout(() => reject(err), 0);
+        }));
+        await expect(fetchStats(mockConfig, "7d")).rejects.toThrow("timed out");
+    });
+    it("returns data on success", async () => {
+        const mockData = {
+            totalSubmissions: 10,
+            averageScore: 8,
+            nps: 50,
+            serviceScores: [],
+            criticalAlerts: [],
+        };
+        vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, json: async () => mockData }));
+        const result = await fetchStats(mockConfig, "7d");
+        expect(result.totalSubmissions).toBe(10);
+    });
+});
+describe("fetchReportPdf", () => {
+    it("throws on 401", async () => {
+        vi.stubGlobal("fetch", async () => ({ ok: false, status: 401, arrayBuffer: async () => new ArrayBuffer(0) }));
+        await expect(fetchReportPdf(mockConfig, "2026-03-22")).rejects.toThrow("Invalid API key");
+    });
+    it("throws on 404", async () => {
+        vi.stubGlobal("fetch", async () => ({ ok: false, status: 404 }));
+        await expect(fetchReportPdf(mockConfig, "2026-03-22")).rejects.toThrow("No report found");
+    });
+    it("returns buffer on success", async () => {
+        const bytes = new Uint8Array([1, 2, 3]);
+        vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, arrayBuffer: async () => bytes.buffer }));
+        const buf = await fetchReportPdf(mockConfig, "2026-03-22");
+        expect(buf).toBeInstanceOf(Buffer);
+        expect(buf.length).toBe(3);
+    });
+});
+describe("fetchLatestReportDate", () => {
+    it("throws when no reports available", async () => {
+        vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, json: async () => [] }));
+        await expect(fetchLatestReportDate(mockConfig)).rejects.toThrow("No reports available");
+    });
+    it("returns the first report date", async () => {
+        vi.stubGlobal("fetch", async () => ({
+            ok: true,
+            status: 200,
+            json: async () => [{ date: "2026-03-22" }, { date: "2026-03-15" }],
+        }));
+        const date = await fetchLatestReportDate(mockConfig);
+        expect(date).toBe("2026-03-22");
+    });
+});

package/dist/core/config.js

@@ -0,0 +1,20 @@
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+export const CONFIG_PATH = join(homedir(), ".health-survey-rc");
+export function loadConfig() {
+    if (!existsSync(CONFIG_PATH)) {
+        console.error("Not configured. Run: bayane setup");
+        process.exit(1);
+    }
+    try {
+        return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    }
+    catch {
+        console.error("Config file is corrupted. Run: bayane setup");
+        process.exit(1);
+    }
+}
+export function saveConfig(config) {
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+}

package/dist/core/format.js

@@ -0,0 +1,30 @@
+export function formatStats(data, period) {
+    const lines = [
+        ``,
+        `📊 Hospital Satisfaction — last ${period}`,
+        `   Responses:  ${data.totalSubmissions}`,
+        `   Avg score:  ${data.averageScore}/10`,
+        `   NPS:        ${data.nps}`,
+    ];
+    if (data.serviceScores.length > 0) {
+        lines.push(``, `   By service:`);
+        [...data.serviceScores]
+            .sort((a, b) => b.avgScore - a.avgScore)
+            .forEach((s) => lines.push(`     ${s.service.padEnd(20)} ${s.avgScore}/10  (${s.count} responses)`));
+    }
+    if (data.criticalAlerts.length > 0) {
+        lines.push(``, `⚠️  Critical alerts: ${data.criticalAlerts.length}`);
+        data.criticalAlerts.forEach((a) => lines.push(`   - ${a.message}`));
+    }
+    return lines.join("\n");
+}
+export function formatAlerts(data) {
+    if (data.criticalAlerts.length === 0) {
+        return "✓ No critical alerts in the last 7 days.";
+    }
+    const lines = [``, `⚠️  ${data.criticalAlerts.length} critical alert(s):`, ``];
+    data.criticalAlerts.forEach((a) => {
+        lines.push(`  - ${a.message}${a.service ? ` [${a.service}]` : ""}${a.date ? ` — ${a.date}` : ""}`);
+    });
+    return lines.join("\n");
+}

package/dist/core/format.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { formatStats, formatAlerts } from "./format.js";
+const mockData = {
+    totalSubmissions: 42,
+    averageScore: 7.8,
+    nps: 35,
+    serviceScores: [
+        { service: "Emergency", avgScore: 8.2, count: 20 },
+        { service: "Maternity", avgScore: 7.1, count: 22 },
+    ],
+    criticalAlerts: [],
+};
+describe("formatStats", () => {
+    it("shows key metrics", () => {
+        const out = formatStats(mockData, "7d");
+        expect(out).toContain("42");
+        expect(out).toContain("7.8/10");
+        expect(out).toContain("35");
+    });
+    it("sorts services by score descending", () => {
+        const out = formatStats(mockData, "7d");
+        expect(out.indexOf("Emergency")).toBeLessThan(out.indexOf("Maternity"));
+    });
+    it("shows alerts when present", () => {
+        const data = { ...mockData, criticalAlerts: [{ message: "Score below 5" }] };
+        expect(formatStats(data, "7d")).toContain("Score below 5");
+    });
+});
+describe("formatAlerts", () => {
+    it("returns ok message when no alerts", () => {
+        expect(formatAlerts(mockData)).toContain("No critical alerts");
+    });
+    it("lists alerts with service and date", () => {
+        const data = {
+            ...mockData,
+            criticalAlerts: [{ message: "Low score", service: "ER", date: "2026-03-21" }],
+        };
+        const out = formatAlerts(data);
+        expect(out).toContain("Low score");
+        expect(out).toContain("[ER]");
+        expect(out).toContain("2026-03-21");
+    });
+});

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/index.js

@@ -0,0 +1,50 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { writeFileSync } from "fs";
+import { loadConfig } from "../core/config.js";
+import { fetchStats, fetchReportPdf, fetchLatestReportDate } from "../core/api.js";
+import { formatStats, formatAlerts } from "../core/format.js";
+const server = new McpServer({
+    name: "health-survey",
+    version: "1.0.0",
+});
+server.tool("get_stats", "Get hospital satisfaction statistics", { period: z.enum(["7d", "30d", "all"]).default("7d").describe("Time period") }, async ({ period }) => {
+    const config = loadConfig();
+    const data = await fetchStats(config, period);
+    return { content: [{ type: "text", text: formatStats(data, period) }] };
+});
+server.tool("get_alerts", "Get critical satisfaction alerts from the last 7 days", {}, async () => {
+    const config = loadConfig();
+    const data = await fetchStats(config, "7d");
+    return { content: [{ type: "text", text: formatAlerts(data) }] };
+});
+server.tool("download_report", "Download a hospital satisfaction PDF report", {
+    date: z.string().optional().describe("YYYY-MM-DD — omit for latest"),
+    output: z.string().optional().describe("Output file path"),
+}, async ({ date, output }) => {
+    const config = loadConfig();
+    const reportDate = date ?? (await fetchLatestReportDate(config));
+    const outPath = output ?? `report-${reportDate}.pdf`;
+    const buffer = await fetchReportPdf(config, reportDate);
+    writeFileSync(outPath, buffer);
+    return { content: [{ type: "text", text: `✓ Report saved to ${outPath}` }] };
+});
+server.tool("display_report", "Display a hospital satisfaction PDF report (returns base64 for rendering)", {
+    date: z.string().optional().describe("YYYY-MM-DD — omit for latest"),
+}, async ({ date }) => {
+    const config = loadConfig();
+    const reportDate = date ?? (await fetchLatestReportDate(config));
+    const buffer = await fetchReportPdf(config, reportDate);
+    const base64 = buffer.toString("base64");
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Hospital Satisfaction Report — ${reportDate}\n\nPDF (base64-encoded, ${buffer.length} bytes):\ndata:application/pdf;base64,${base64}`,
+            },
+        ],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "bayane",
+  "version": "1.0.0",
+  "description": "CLI and MCP server for hospital satisfaction survey data",
+  "type": "module",
+  "bin": {
+    "bayane": "./dist/cli/index.js"
+  },
+  "exports": {
+    "./mcp": "./dist/mcp/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev:cli": "tsx src/cli/index.ts",
+    "dev:mcp": "tsx src/mcp/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@inquirer/prompts": "^5.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "tsx": "^4.0.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": { "node": ">=18" }
+}

package/src/cli/index.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { password, input } from "@inquirer/prompts";
+import { writeFileSync } from "fs";
+import { spawnSync } from "child_process";
+import { execSync } from "child_process";
+import { loadConfig, saveConfig, CONFIG_PATH } from "../core/config.js";
+import { fetchStats, fetchReportPdf, fetchLatestReportDate } from "../core/api.js";
+import { formatStats, formatAlerts } from "../core/format.js";
+
+const DEFAULT_API_URL = "https://health-bd.nonas.app";
+
+const program = new Command();
+program.name("bayane").description("Hospital satisfaction survey CLI").version("1.0.0");
+
+// bayane setup
+program
+  .command("setup")
+  .description("Configure API URL and API key")
+  .action(async () => {
+    const apiUrl = await input({ message: "API URL:", default: DEFAULT_API_URL });
+    const apiKey = await password({ message: "API key (sk_...):" });
+    saveConfig({ apiUrl, apiKey });
+    console.log(`✓ Config saved to ${CONFIG_PATH}`);
+  });
+
+// bayane whoami
+program
+  .command("whoami")
+  .description("Show current config")
+  .action(() => {
+    const config = loadConfig();
+    console.log(`API URL: ${config.apiUrl}`);
+    console.log(`API key: ${config.apiKey.slice(0, 8)}...`);
+  });
+
+// bayane stats
+program
+  .command("stats")
+  .description("Show satisfaction statistics")
+  .option("--period <period>", "7d, 30d, or all", "7d")
+  .action(async (opts) => {
+    try {
+      const config = loadConfig();
+      const data = await fetchStats(config, opts.period);
+      console.log(formatStats(data, opts.period));
+    } catch (err: unknown) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+// bayane report
+program
+  .command("report")
+  .description("Download a daily PDF report")
+  .option("--date <date>", "YYYY-MM-DD (defaults to latest available)")
+  .option("--latest", "Download the most recent available report")
+  .option("--output <path>", "Output file path")
+  .action(async (opts) => {
+    try {
+      const config = loadConfig();
+      const date =
+        opts.date ??
+        (opts.latest
+          ? await fetchLatestReportDate(config)
+          : new Date().toISOString().split("T")[0]);
+      const outPath = opts.output ?? `report-${date}.pdf`;
+      const buffer = await fetchReportPdf(config, date);
+      writeFileSync(outPath, buffer);
+      console.log(`✓ Report saved to ${outPath}`);
+    } catch (err: unknown) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+// bayane alerts
+program
+  .command("alerts")
+  .description("Show critical alerts from the last 7 days")
+  .action(async () => {
+    try {
+      const config = loadConfig();
+      const data = await fetchStats(config, "7d");
+      console.log(formatAlerts(data));
+    } catch (err: unknown) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+// bayane install
+program
+  .command("install")
+  .description("Install the bayane skill for your AI agent")
+  .action(() => {
+    console.log("Installing bayane skill...");
+    spawnSync("npx", ["skills", "add", "anouar-bm/bayane"], { stdio: "inherit" });
+  });
+
+program.parse();

package/src/core/api.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { fetchStats, fetchReportPdf, fetchLatestReportDate } from "./api.js";
+
+const mockConfig = { apiUrl: "https://test.example.com", apiKey: "sk_test" };
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+describe("fetchStats", () => {
+  it("throws on 401", async () => {
+    vi.stubGlobal("fetch", async () => ({ ok: false, status: 401, json: async () => ({}) }));
+    await expect(fetchStats(mockConfig, "7d")).rejects.toThrow("Invalid API key");
+  });
+
+  it("throws on network timeout", async () => {
+    vi.stubGlobal("fetch", () =>
+      new Promise((_, reject) => {
+        const err = new Error("aborted");
+        err.name = "AbortError";
+        setTimeout(() => reject(err), 0);
+      })
+    );
+    await expect(fetchStats(mockConfig, "7d")).rejects.toThrow("timed out");
+  });
+
+  it("returns data on success", async () => {
+    const mockData = {
+      totalSubmissions: 10,
+      averageScore: 8,
+      nps: 50,
+      serviceScores: [],
+      criticalAlerts: [],
+    };
+    vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, json: async () => mockData }));
+    const result = await fetchStats(mockConfig, "7d");
+    expect(result.totalSubmissions).toBe(10);
+  });
+});
+
+describe("fetchReportPdf", () => {
+  it("throws on 401", async () => {
+    vi.stubGlobal("fetch", async () => ({ ok: false, status: 401, arrayBuffer: async () => new ArrayBuffer(0) }));
+    await expect(fetchReportPdf(mockConfig, "2026-03-22")).rejects.toThrow("Invalid API key");
+  });
+
+  it("throws on 404", async () => {
+    vi.stubGlobal("fetch", async () => ({ ok: false, status: 404 }));
+    await expect(fetchReportPdf(mockConfig, "2026-03-22")).rejects.toThrow("No report found");
+  });
+
+  it("returns buffer on success", async () => {
+    const bytes = new Uint8Array([1, 2, 3]);
+    vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, arrayBuffer: async () => bytes.buffer }));
+    const buf = await fetchReportPdf(mockConfig, "2026-03-22");
+    expect(buf).toBeInstanceOf(Buffer);
+    expect(buf.length).toBe(3);
+  });
+});
+
+describe("fetchLatestReportDate", () => {
+  it("throws when no reports available", async () => {
+    vi.stubGlobal("fetch", async () => ({ ok: true, status: 200, json: async () => [] }));
+    await expect(fetchLatestReportDate(mockConfig)).rejects.toThrow("No reports available");
+  });
+
+  it("returns the first report date", async () => {
+    vi.stubGlobal("fetch", async () => ({
+      ok: true,
+      status: 200,
+      json: async () => [{ date: "2026-03-22" }, { date: "2026-03-15" }],
+    }));
+    const date = await fetchLatestReportDate(mockConfig);
+    expect(date).toBe("2026-03-22");
+  });
+});

package/src/core/api.ts

@@ -0,0 +1,65 @@
+import { Config, AnalyticsData, Period } from "./types.js";
+
+const TIMEOUT_MS = 10_000;
+
+async function apiFetch<T>(config: Config, path: string): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+  try {
+    const res = await fetch(`${config.apiUrl}${path}`, {
+      headers: { Authorization: `Bearer ${config.apiKey}` },
+      signal: controller.signal,
+    });
+
+    if (res.status === 401) throw new Error("Invalid API key. Run: bayane setup");
+    if (!res.ok) {
+      const text = await res.text().catch(() => res.statusText);
+      throw new Error(`API error ${res.status}: ${text}`);
+    }
+
+    return res.json() as Promise<T>;
+  } catch (err: unknown) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error("Request timed out. Check your connection.");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchStats(config: Config, period: Period): Promise<AnalyticsData> {
+  return apiFetch<AnalyticsData>(config, `/api/analytics?range=${period}`);
+}
+
+export async function fetchReportPdf(config: Config, date: string): Promise<Buffer> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 30_000);
+
+  try {
+    const res = await fetch(`${config.apiUrl}/api/reports/${date}/pdf`, {
+      headers: { Authorization: `Bearer ${config.apiKey}` },
+      signal: controller.signal,
+    });
+
+    if (res.status === 401) throw new Error("Invalid API key. Run: bayane setup");
+    if (res.status === 404) throw new Error(`No report found for ${date}`);
+    if (!res.ok) throw new Error(`Failed to download report: ${res.status}`);
+
+    return Buffer.from(await res.arrayBuffer());
+  } catch (err: unknown) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error("Report download timed out.");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchLatestReportDate(config: Config): Promise<string> {
+  const reports = await apiFetch<Array<{ date: string }>>(config, "/api/reports");
+  if (!reports.length) throw new Error("No reports available yet.");
+  return reports[0].date;
+}

package/src/core/config.ts

@@ -0,0 +1,23 @@
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { Config } from "./types.js";
+
+export const CONFIG_PATH = join(homedir(), ".health-survey-rc");
+
+export function loadConfig(): Config {
+  if (!existsSync(CONFIG_PATH)) {
+    console.error("Not configured. Run: bayane setup");
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8")) as Config;
+  } catch {
+    console.error("Config file is corrupted. Run: bayane setup");
+    process.exit(1);
+  }
+}
+
+export function saveConfig(config: Config): void {
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+}

package/src/core/format.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { formatStats, formatAlerts } from "./format.js";
+import { AnalyticsData } from "./types.js";
+
+const mockData: AnalyticsData = {
+  totalSubmissions: 42,
+  averageScore: 7.8,
+  nps: 35,
+  serviceScores: [
+    { service: "Emergency", avgScore: 8.2, count: 20 },
+    { service: "Maternity", avgScore: 7.1, count: 22 },
+  ],
+  criticalAlerts: [],
+};
+
+describe("formatStats", () => {
+  it("shows key metrics", () => {
+    const out = formatStats(mockData, "7d");
+    expect(out).toContain("42");
+    expect(out).toContain("7.8/10");
+    expect(out).toContain("35");
+  });
+
+  it("sorts services by score descending", () => {
+    const out = formatStats(mockData, "7d");
+    expect(out.indexOf("Emergency")).toBeLessThan(out.indexOf("Maternity"));
+  });
+
+  it("shows alerts when present", () => {
+    const data = { ...mockData, criticalAlerts: [{ message: "Score below 5" }] };
+    expect(formatStats(data, "7d")).toContain("Score below 5");
+  });
+});
+
+describe("formatAlerts", () => {
+  it("returns ok message when no alerts", () => {
+    expect(formatAlerts(mockData)).toContain("No critical alerts");
+  });
+
+  it("lists alerts with service and date", () => {
+    const data = {
+      ...mockData,
+      criticalAlerts: [{ message: "Low score", service: "ER", date: "2026-03-21" }],
+    };
+    const out = formatAlerts(data);
+    expect(out).toContain("Low score");
+    expect(out).toContain("[ER]");
+    expect(out).toContain("2026-03-21");
+  });
+});

package/src/core/format.ts

@@ -0,0 +1,40 @@
+import { AnalyticsData, Period } from "./types.js";
+
+export function formatStats(data: AnalyticsData, period: Period): string {
+  const lines: string[] = [
+    ``,
+    `📊 Hospital Satisfaction — last ${period}`,
+    `   Responses:  ${data.totalSubmissions}`,
+    `   Avg score:  ${data.averageScore}/10`,
+    `   NPS:        ${data.nps}`,
+  ];
+
+  if (data.serviceScores.length > 0) {
+    lines.push(``, `   By service:`);
+    [...data.serviceScores]
+      .sort((a, b) => b.avgScore - a.avgScore)
+      .forEach((s) =>
+        lines.push(`     ${s.service.padEnd(20)} ${s.avgScore}/10  (${s.count} responses)`)
+      );
+  }
+
+  if (data.criticalAlerts.length > 0) {
+    lines.push(``, `⚠️  Critical alerts: ${data.criticalAlerts.length}`);
+    data.criticalAlerts.forEach((a) => lines.push(`   - ${a.message}`));
+  }
+
+  return lines.join("\n");
+}
+
+export function formatAlerts(data: AnalyticsData): string {
+  if (data.criticalAlerts.length === 0) {
+    return "✓ No critical alerts in the last 7 days.";
+  }
+  const lines = [``, `⚠️  ${data.criticalAlerts.length} critical alert(s):`, ``];
+  data.criticalAlerts.forEach((a) => {
+    lines.push(
+      `  - ${a.message}${a.service ? ` [${a.service}]` : ""}${a.date ? ` — ${a.date}` : ""}`
+    );
+  });
+  return lines.join("\n");
+}

package/src/core/types.ts

@@ -0,0 +1,19 @@
+export interface Config {
+  apiUrl: string;
+  apiKey: string;
+}
+
+export interface AnalyticsData {
+  totalSubmissions: number;
+  averageScore: number;
+  nps: number;
+  serviceScores: Array<{ service: string; avgScore: number; count: number }>;
+  criticalAlerts: Array<{ message: string; service?: string; date?: string }>;
+}
+
+export interface ReportMeta {
+  date: string;
+  url?: string;
+}
+
+export type Period = "7d" | "30d" | "all";

package/src/mcp/index.ts

@@ -0,0 +1,76 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { writeFileSync } from "fs";
+import { loadConfig } from "../core/config.js";
+import { fetchStats, fetchReportPdf, fetchLatestReportDate } from "../core/api.js";
+import { formatStats, formatAlerts } from "../core/format.js";
+
+const server = new McpServer({
+  name: "health-survey",
+  version: "1.0.0",
+});
+
+server.tool(
+  "get_stats",
+  "Get hospital satisfaction statistics",
+  { period: z.enum(["7d", "30d", "all"]).default("7d").describe("Time period") },
+  async ({ period }) => {
+    const config = loadConfig();
+    const data = await fetchStats(config, period);
+    return { content: [{ type: "text", text: formatStats(data, period) }] };
+  }
+);
+
+server.tool(
+  "get_alerts",
+  "Get critical satisfaction alerts from the last 7 days",
+  {},
+  async () => {
+    const config = loadConfig();
+    const data = await fetchStats(config, "7d");
+    return { content: [{ type: "text", text: formatAlerts(data) }] };
+  }
+);
+
+server.tool(
+  "download_report",
+  "Download a hospital satisfaction PDF report",
+  {
+    date: z.string().optional().describe("YYYY-MM-DD — omit for latest"),
+    output: z.string().optional().describe("Output file path"),
+  },
+  async ({ date, output }) => {
+    const config = loadConfig();
+    const reportDate = date ?? (await fetchLatestReportDate(config));
+    const outPath = output ?? `report-${reportDate}.pdf`;
+    const buffer = await fetchReportPdf(config, reportDate);
+    writeFileSync(outPath, buffer);
+    return { content: [{ type: "text", text: `✓ Report saved to ${outPath}` }] };
+  }
+);
+
+server.tool(
+  "display_report",
+  "Display a hospital satisfaction PDF report (returns base64 for rendering)",
+  {
+    date: z.string().optional().describe("YYYY-MM-DD — omit for latest"),
+  },
+  async ({ date }) => {
+    const config = loadConfig();
+    const reportDate = date ?? (await fetchLatestReportDate(config));
+    const buffer = await fetchReportPdf(config, reportDate);
+    const base64 = buffer.toString("base64");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Hospital Satisfaction Report — ${reportDate}\n\nPDF (base64-encoded, ${buffer.length} bytes):\ndata:application/pdf;base64,${base64}`,
+        },
+      ],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}