heor-agent-mcp 0.2.0 → 0.7.0

package/dist/tools/survivalFitting.d.ts

@@ -0,0 +1,56 @@
+import type { ToolResult } from "../providers/types.js";
+export declare function handleSurvivalFitting(rawParams: unknown): Promise<ToolResult>;
+export declare const survivalFittingToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            km_data: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                    properties: {
+                        time: {
+                            type: string;
+                            description: string;
+                        };
+                        survival: {
+                            type: string;
+                            description: string;
+                        };
+                        n_at_risk: {
+                            type: string;
+                            description: string;
+                        };
+                        n_events: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+            time_unit: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            endpoint: {
+                type: string;
+                description: string;
+            };
+            output_format: {
+                type: string;
+                enum: string[];
+            };
+            project: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+//# sourceMappingURL=survivalFitting.d.ts.map

package/dist/tools/survivalFitting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"survivalFitting.d.ts","sourceRoot":"","sources":["../../src/tools/survivalFitting.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AA4GxD,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,UAAU,CAAC,CAmDrB;AAED,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CrC,CAAC"}

package/dist/tools/survivalFitting.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { createAuditRecord, addAssumption, setMethodology, } from "../audit/builder.js";
+import { auditToMarkdown } from "../formatters/markdown.js";
+import { fitSurvivalCurves, } from "../models/survivalFitting.js";
+const SurvivalFittingSchema = z.object({
+    km_data: z
+        .array(z.object({
+        time: z.number().nonnegative(),
+        survival: z.number().min(0).max(1),
+        n_at_risk: z.number().int().positive().optional(),
+        n_events: z.number().int().nonnegative().optional(),
+    }))
+        .min(3, "At least 3 KM data points required"),
+    time_unit: z.enum(["months", "years"]).default("months"),
+    endpoint: z.string().default("OS"),
+    output_format: z.enum(["text", "json"]).optional(),
+    project: z.string().optional(),
+});
+function formatResult(result, endpoint) {
+    const unit = result.time_unit;
+    const lines = [
+        `## Survival Curve Fitting: ${endpoint}`,
+        ``,
+        `### Model Comparison`,
+        `| Distribution | AIC | BIC | Log-L | Median (${unit}) | Parameters |`,
+        `|-------------|-----|-----|-------|--------|------------|`,
+    ];
+    for (const fit of result.fits) {
+        const paramStr = Object.entries(fit.params)
+            .map(([k, v]) => `${k}=${v.toFixed(4)}`)
+            .join(", ");
+        const isBestAIC = fit.name === result.best_aic.name;
+        const isBestBIC = fit.name === result.best_bic.name;
+        const badge = isBestAIC && isBestBIC
+            ? " **[Best]**"
+            : isBestAIC
+                ? " *[Best AIC]*"
+                : isBestBIC
+                    ? " *[Best BIC]*"
+                    : "";
+        lines.push(`| ${fit.name}${badge} | ${fit.aic.toFixed(1)} | ${fit.bic.toFixed(1)} | ${fit.log_likelihood.toFixed(1)} | ${fit.median_survival.toFixed(1)} | ${paramStr} |`);
+    }
+    lines.push(``);
+    lines.push(`### Recommended Model`);
+    lines.push(`**${result.best_aic.name}** (AIC: ${result.best_aic.aic.toFixed(1)}) — median ${endpoint}: ${result.best_aic.median_survival.toFixed(1)} ${unit}`);
+    if (result.best_aic.name !== result.best_bic.name) {
+        lines.push(`Note: BIC prefers **${result.best_bic.name}** — consider clinical plausibility when AIC/BIC disagree.`);
+    }
+    lines.push(``);
+    lines.push(`### Extrapolation Table`);
+    lines.push(`| Time (${unit}) | KM Observed | Exponential | Weibull | Log-logistic | Log-normal | Gompertz |`);
+    lines.push(`|------|------------|-------------|---------|-------------|------------|----------|`);
+    for (const row of result.extrapolations) {
+        const km = row.km_observed !== undefined ? row.km_observed.toFixed(3) : "—";
+        lines.push(`| ${row.time.toFixed(1)} | ${km} | ${row.exponential.toFixed(3)} | ${row.weibull.toFixed(3)} | ${row.log_logistic.toFixed(3)} | ${row.log_normal.toFixed(3)} | ${row.gompertz.toFixed(3)} |`);
+    }
+    lines.push(``);
+    lines.push(`### Clinical Plausibility Check`);
+    lines.push(`Per NICE DSU TSD 14, statistical fit (AIC/BIC) should be considered alongside:`);
+    lines.push(`1. **Visual fit** to the KM curve`);
+    lines.push(`2. **Clinical plausibility** of the long-term extrapolation`);
+    lines.push(`3. **External data** (registry data, natural history studies)`);
+    lines.push(`4. **Hazard function shape** — does it match expected disease trajectory?`);
+    lines.push(``);
+    const bestFit = result.best_aic;
+    if (bestFit.name === "log_logistic" || bestFit.name === "log_normal") {
+        lines.push(`> **Note:** ${bestFit.name} has a long tail — extrapolated survival may be optimistic for long time horizons. Compare against Gompertz/Weibull for conservative estimates.`);
+    }
+    return lines.join("\n");
+}
+export async function handleSurvivalFitting(rawParams) {
+    const params = SurvivalFittingSchema.parse(rawParams);
+    const outputFormat = params.output_format ?? "text";
+    let audit = createAuditRecord("survival_fitting", params, outputFormat);
+    audit = setMethodology(audit, "Parametric survival curve fitting per NICE DSU TSD 14 (Latimer 2013). MLE via Nelder-Mead. Model selection via AIC/BIC.");
+    audit = addAssumption(audit, `${params.km_data.length} KM data points provided`);
+    audit = addAssumption(audit, `Endpoint: ${params.endpoint}, time unit: ${params.time_unit}`);
+    audit = addAssumption(audit, `Distributions fitted: Exponential, Weibull, Log-logistic, Log-normal, Gompertz`);
+    const result = fitSurvivalCurves(params.km_data, params.time_unit);
+    if (outputFormat === "json") {
+        return {
+            content: {
+                fits: result.fits.map((f) => ({
+                    name: f.name,
+                    params: f.params,
+                    aic: f.aic,
+                    bic: f.bic,
+                    log_likelihood: f.log_likelihood,
+                    median_survival: f.median_survival,
+                    mean_survival_restricted: f.mean_survival_restricted,
+                })),
+                best_aic: result.best_aic.name,
+                best_bic: result.best_bic.name,
+                extrapolations: result.extrapolations,
+                time_unit: result.time_unit,
+            },
+            audit,
+        };
+    }
+    const text = formatResult(result, params.endpoint) + "\n" + auditToMarkdown(audit);
+    return { content: text, audit };
+}
+export const survivalFittingToolSchema = {
+    name: "survival_fitting",
+    description: "Fit parametric survival distributions (Exponential, Weibull, Log-logistic, Log-normal, Gompertz) to Kaplan-Meier data. Returns AIC/BIC model comparison, parameter estimates, median survival, and extrapolation table. Follows NICE DSU TSD 14 guidance. Use to select the best-fitting distribution for PartSA models.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            km_data: {
+                type: "array",
+                description: "Kaplan-Meier data points. At least 3 required. Extract from published KM curves or trial reports.",
+                items: {
+                    type: "object",
+                    properties: {
+                        time: { type: "number", description: "Time point" },
+                        survival: {
+                            type: "number",
+                            description: "Survival proportion (0-1)",
+                        },
+                        n_at_risk: {
+                            type: "number",
+                            description: "Number at risk (optional, improves fit)",
+                        },
+                        n_events: {
+                            type: "number",
+                            description: "Events in interval (optional)",
+                        },
+                    },
+                    required: ["time", "survival"],
+                },
+            },
+            time_unit: {
+                type: "string",
+                enum: ["months", "years"],
+                description: "Time unit for KM data (default: months)",
+            },
+            endpoint: {
+                type: "string",
+                description: "Endpoint name (e.g., 'OS', 'PFS', 'DFS'). Default: 'OS'.",
+            },
+            output_format: { type: "string", enum: ["text", "json"] },
+            project: { type: "string", description: "Project ID for persistence" },
+        },
+        required: ["km_data"],
+    },
+};
+//# sourceMappingURL=survivalFitting.js.map

package/dist/tools/survivalFitting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"survivalFitting.js","sourceRoot":"","sources":["../../src/tools/survivalFitting.ts"],"names":[],"mappings":"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"}

package/dist/tools/validateLinks.d.ts

@@ -0,0 +1,24 @@
+import type { ToolResult } from "../providers/types.js";
+export declare function handleValidateLinks(rawParams: unknown): Promise<ToolResult>;
+export declare const validateLinksToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            urls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            timeout_ms: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+//# sourceMappingURL=validateLinks.d.ts.map

package/dist/tools/validateLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateLinks.d.ts","sourceRoot":"","sources":["../../src/tools/validateLinks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AA6HxD,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,UAAU,CAAC,CAuErB;AAED,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;CAmBnC,CAAC"}

package/dist/tools/validateLinks.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { createAuditRecord, addAssumption, setMethodology, } from "../audit/builder.js";
+/**
+ * Validate Links Tool
+ *
+ * Checks whether URLs return 200 OK, 404, or other status codes.
+ * Validates links BEFORE presenting them to users so we never
+ * mislead with broken references.
+ *
+ * Handles sites that block automated requests (return 403):
+ *   - CADTH, HAS, and some others block bots but work in browsers
+ *   - These are marked "browser_only" instead of "broken"
+ */
+const ValidateLinksSchema = z.object({
+    urls: z
+        .array(z.string().url())
+        .min(1)
+        .max(50)
+        .describe("URLs to validate"),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(1000)
+        .max(30000)
+        .default(10000)
+        .optional(),
+});
+// Domains known to block bots but work in browsers
+const BROWSER_ONLY_DOMAINS = [
+    "cda-amc.ca",
+    "cadth.ca",
+    "has-sante.fr",
+    "pbs.gov.au",
+    "cochranelibrary.com",
+];
+function categorize(url, status) {
+    if (status >= 200 && status < 400)
+        return "working";
+    if (status === 403) {
+        const host = new URL(url).hostname;
+        if (BROWSER_ONLY_DOMAINS.some((d) => host.includes(d))) {
+            return "browser_only";
+        }
+        return "broken";
+    }
+    if (status === 404 || status === 410)
+        return "broken";
+    if (status === 429)
+        return "broken"; // rate limited
+    if (status === 0)
+        return "timeout";
+    return "error";
+}
+async function checkUrl(url, timeoutMs) {
+    try {
+        const res = await fetch(url, {
+            method: "HEAD",
+            redirect: "follow",
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: {
+                "User-Agent": "Mozilla/5.0 (HEORAgent Link Validator) AppleWebKit/537.36",
+            },
+        });
+        // Some servers reject HEAD — fall back to GET
+        if (res.status === 405 || res.status === 501) {
+            const getRes = await fetch(url, {
+                method: "GET",
+                redirect: "follow",
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: {
+                    "User-Agent": "Mozilla/5.0 (HEORAgent Link Validator) AppleWebKit/537.36",
+                },
+            });
+            return {
+                url,
+                status_code: getRes.status,
+                ok: getRes.ok,
+                category: categorize(url, getRes.status),
+                message: getRes.statusText || "",
+                final_url: getRes.url !== url ? getRes.url : undefined,
+            };
+        }
+        return {
+            url,
+            status_code: res.status,
+            ok: res.ok,
+            category: categorize(url, res.status),
+            message: res.statusText || "",
+            final_url: res.url !== url ? res.url : undefined,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            url,
+            status_code: 0,
+            ok: false,
+            category: msg.includes("abort") || msg.includes("timeout")
+                ? "timeout"
+                : "error",
+            message: msg,
+        };
+    }
+}
+export async function handleValidateLinks(rawParams) {
+    const params = ValidateLinksSchema.parse(rawParams);
+    const timeoutMs = params.timeout_ms ?? 10000;
+    let audit = createAuditRecord("validate_links", { n_urls: params.urls.length }, "text");
+    audit = setMethodology(audit, "HTTP HEAD request with redirect follow");
+    audit = addAssumption(audit, `Timeout: ${timeoutMs}ms per URL. Sites blocking bots (403) marked "browser_only".`);
+    // Validate all URLs in parallel
+    const results = await Promise.all(params.urls.map((url) => checkUrl(url, timeoutMs)));
+    const working = results.filter((r) => r.category === "working").length;
+    const browserOnly = results.filter((r) => r.category === "browser_only").length;
+    const broken = results.filter((r) => r.category === "broken" || r.category === "timeout" || r.category === "error").length;
+    const lines = [
+        `## Link Validation Report`,
+        ``,
+        `**Summary:** ${working} working | ${browserOnly} browser-only (403 to bots, works in browser) | ${broken} broken`,
+        ``,
+        `| URL | Status | Category | Notes |`,
+        `|-----|--------|----------|-------|`,
+    ];
+    for (const r of results) {
+        const icon = r.category === "working"
+            ? "OK"
+            : r.category === "browser_only"
+                ? "Browser"
+                : "BROKEN";
+        const shortUrl = r.url.length > 60 ? r.url.slice(0, 57) + "..." : r.url;
+        const note = r.final_url
+            ? `Redirected to ${r.final_url}`
+            : r.message || "";
+        lines.push(`| ${shortUrl} | ${r.status_code || "—"} | ${icon} | ${note} |`);
+    }
+    lines.push(``);
+    if (broken > 0) {
+        lines.push(`> **WARNING:** ${broken} link(s) are broken. Do NOT present these to the user. Replace with working alternatives or omit.`);
+    }
+    if (browserOnly > 0) {
+        lines.push(`> **Note:** ${browserOnly} link(s) return 403 to automated requests but work in browsers. These are safe to present.`);
+    }
+    return {
+        content: {
+            summary: { total: results.length, working, browser_only: browserOnly, broken },
+            results,
+            text: lines.join("\n"),
+        },
+        audit,
+    };
+}
+export const validateLinksToolSchema = {
+    name: "validate_links",
+    description: "Validate URLs by making HEAD requests and checking HTTP status codes. Returns categorization: working (200), browser_only (403 from bot-blocking sites that work in browsers), broken (404/410), or timeout/error. ALWAYS use this before presenting reference links to users — broken links destroy trust. Pass all URLs you plan to cite.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            urls: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of URLs to validate (max 50)",
+            },
+            timeout_ms: {
+                type: "number",
+                description: "Timeout per URL in ms (default 10000, max 30000)",
+            },
+        },
+        required: ["urls"],
+    },
+};
+//# sourceMappingURL=validateLinks.js.map

package/dist/tools/validateLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateLinks.js","sourceRoot":"","sources":["../../src/tools/validateLinks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heor-agent-mcp",
-  "version": "0.2.0",
+  "version": "0.7.0",
   "license": "MIT",
   "author": "mnaumov",
   "engines": {
@@ -49,6 +49,7 @@
     "url": "https://github.com/neptun2000/HEORAgent/issues"
   },
   "scripts": {
+    "start": "node dist/server.js",
     "build": "tsc",
     "dev": "tsx src/server.ts",
     "test": "jest",
@@ -60,6 +61,7 @@
     "docx": "^9.6.1",
     "express": "^5.2.1",
     "posthog-node": "^5.29.2",
+    "typescript": "^5.9.3",
     "zod": "^3.22.4"
   },
   "devDependencies": {
@@ -69,6 +71,6 @@
     "jest": "^29.7.0",
     "ts-jest": "^29.1.1",
     "tsx": "^4.7.0",
-    "typescript": "^5.3.3"
+    "typescript": "^5.9.3"
   }
 }