justlabs-mcp-server 1.0.0 → 1.1.0

package/dist/__tests__/analysis.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Basic tests for analysis modules
+ * Run with: npx ts-node src/__tests__/analysis.test.ts
+ */
+export {};

package/dist/__tests__/analysis.test.js

@@ -0,0 +1,203 @@
+/**
+ * Basic tests for analysis modules
+ * Run with: npx ts-node src/__tests__/analysis.test.ts
+ */
+import { classifyValue, checkCriticalValue, getReferenceRange, getApplicableRange } from "../ranges/questRanges.js";
+import { analyzePanelResults } from "../analysis/analyzePanelResults.js";
+import { suggestNextSteps } from "../analysis/suggestNextSteps.js";
+import { generatePatientSummary } from "../analysis/generatePatientSummary.js";
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+    try {
+        fn();
+        console.log(`✓ ${name}`);
+        passed++;
+    }
+    catch (e) {
+        console.log(`✗ ${name}`);
+        console.log(`  Error: ${e.message}`);
+        failed++;
+    }
+}
+function expect(actual) {
+    return {
+        toBe(expected) {
+            if (actual !== expected) {
+                throw new Error(`Expected ${expected}, got ${actual}`);
+            }
+        },
+        toBeTruthy() {
+            if (!actual) {
+                throw new Error(`Expected truthy value, got ${actual}`);
+            }
+        },
+        toBeFalsy() {
+            if (actual) {
+                throw new Error(`Expected falsy value, got ${actual}`);
+            }
+        },
+        toContain(expected) {
+            if (typeof actual !== "string" || !actual.includes(expected)) {
+                throw new Error(`Expected "${actual}" to contain "${expected}"`);
+            }
+        },
+    };
+}
+console.log("\n=== Range Classification Tests ===\n");
+test("classifies value below range as low", () => {
+    const result = classifyValue(0.3, { low: 0.45, high: 4.5, unit: "mIU/L" });
+    expect(result).toBe("low");
+});
+test("classifies value above range as high", () => {
+    const result = classifyValue(5.0, { low: 0.45, high: 4.5, unit: "mIU/L" });
+    expect(result).toBe("high");
+});
+test("classifies value within range as normal", () => {
+    const result = classifyValue(2.5, { low: 0.45, high: 4.5, unit: "mIU/L" });
+    expect(result).toBe("normal");
+});
+test("classifies value with only upper bound", () => {
+    const result = classifyValue(50, { high: 34, unit: "IU/mL" });
+    expect(result).toBe("high");
+});
+console.log("\n=== Critical Value Detection Tests ===\n");
+test("detects critical high glucose", () => {
+    const result = checkCriticalValue("glucose", 450);
+    expect(result.isCritical).toBeTruthy();
+});
+test("does not flag normal glucose", () => {
+    const result = checkCriticalValue("glucose", 95);
+    expect(result.isCritical).toBeFalsy();
+});
+test("detects critical low potassium", () => {
+    const result = checkCriticalValue("potassium", 2.3);
+    expect(result.isCritical).toBeTruthy();
+});
+test("detects critical high TSH", () => {
+    const result = checkCriticalValue("tsh", 60);
+    expect(result.isCritical).toBeTruthy();
+});
+console.log("\n=== Sex-Specific Range Tests ===\n");
+test("returns male-specific ferritin range", () => {
+    const biomarker = getReferenceRange("ferritin");
+    expect(biomarker).toBeTruthy();
+    const range = getApplicableRange(biomarker, "male");
+    expect(range.high).toBe(400);
+});
+test("returns female-specific ferritin range", () => {
+    const biomarker = getReferenceRange("ferritin");
+    const range = getApplicableRange(biomarker, "female");
+    expect(range.high).toBe(200);
+});
+console.log("\n=== Panel Analysis Tests ===\n");
+test("analyzes fatigue panel with normal results", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 2.0, unit: "mIU/L" },
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+            { biomarker_key: "vitamin-b12", value: 500, unit: "pg/mL" },
+            { biomarker_key: "vitamin-d", value: 45, unit: "ng/mL" },
+            { biomarker_key: "hemoglobin", value: 14, unit: "g/dL" },
+            { biomarker_key: "wbc", value: 7.0, unit: "K/uL" },
+        ],
+    });
+    expect(analysis.summary.overall_status).toBe("all_normal");
+    expect(analysis.red_flags_detected).toBeFalsy();
+});
+test("detects abnormal TSH in fatigue panel", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 8.0, unit: "mIU/L" },
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+            { biomarker_key: "vitamin-b12", value: 500, unit: "pg/mL" },
+            { biomarker_key: "vitamin-d", value: 45, unit: "ng/mL" },
+            { biomarker_key: "hemoglobin", value: 14, unit: "g/dL" },
+            { biomarker_key: "wbc", value: 7.0, unit: "K/uL" },
+        ],
+    });
+    expect(analysis.summary.overall_status).toBe("some_outside_range");
+    expect(analysis.key_findings.length).toBe(1);
+    expect(analysis.key_findings[0].biomarker_key).toBe("tsh");
+});
+test("stops analysis on critical value", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 60, unit: "mIU/L" }, // Critical high
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+        ],
+    });
+    expect(analysis.red_flags_detected).toBeTruthy();
+    expect(analysis.summary.overall_status).toBe("critical");
+});
+console.log("\n=== Next Steps Suggestion Tests ===\n");
+test("suggests thyroid deep dive for abnormal TSH", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 8.0, unit: "mIU/L" },
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+            { biomarker_key: "vitamin-b12", value: 500, unit: "pg/mL" },
+            { biomarker_key: "vitamin-d", value: 45, unit: "ng/mL" },
+            { biomarker_key: "hemoglobin", value: 14, unit: "g/dL" },
+            { biomarker_key: "wbc", value: 7.0, unit: "K/uL" },
+        ],
+    });
+    const nextSteps = suggestNextSteps("fatigue_panel", analysis);
+    expect(nextSteps.next_step.type).toBe("additional_testing");
+    if (nextSteps.next_step.type === "additional_testing") {
+        expect(nextSteps.next_step.recommended_panel_id).toBe("thyroid_deep_dive");
+    }
+});
+test("suggests clinician discussion for all normal results", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 2.0, unit: "mIU/L" },
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+            { biomarker_key: "vitamin-b12", value: 500, unit: "pg/mL" },
+            { biomarker_key: "vitamin-d", value: 45, unit: "ng/mL" },
+            { biomarker_key: "hemoglobin", value: 14, unit: "g/dL" },
+            { biomarker_key: "wbc", value: 7.0, unit: "K/uL" },
+        ],
+    });
+    const nextSteps = suggestNextSteps("fatigue_panel", analysis);
+    expect(nextSteps.next_step.type).toBe("clinician_discussion");
+});
+console.log("\n=== Patient Summary Tests ===\n");
+test("generates summary with disclaimer", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 2.0, unit: "mIU/L" },
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+        ],
+    });
+    const nextSteps = suggestNextSteps("fatigue_panel", analysis);
+    const summary = generatePatientSummary("fatigue_panel", analysis, nextSteps);
+    expect(summary.patient_summary.disclaimer).toContain("educational purposes only");
+    expect(summary.patient_summary.requires_acknowledgment).toBeTruthy();
+});
+test("includes CTA only for additional testing", () => {
+    const analysis = analyzePanelResults({
+        panel_id: "fatigue_panel",
+        results: [
+            { biomarker_key: "tsh", value: 8.0, unit: "mIU/L" }, // Abnormal
+            { biomarker_key: "ferritin", value: 80, unit: "ng/mL" },
+        ],
+    });
+    const nextSteps = suggestNextSteps("fatigue_panel", analysis);
+    const summary = generatePatientSummary("fatigue_panel", analysis, nextSteps);
+    expect(summary.patient_summary.cta).toBeTruthy();
+    expect(summary.patient_summary.cta?.url).toContain("justlabs.health");
+});
+// Summary
+console.log("\n=================================");
+console.log(`Tests: ${passed} passed, ${failed} failed`);
+console.log("=================================\n");
+if (failed > 0) {
+    process.exit(1);
+}

package/dist/analysis/analyzePanelResults.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Analyze panel results - educational context only, no diagnostic language
+ */
+export interface ResultInput {
+    biomarker_key: string;
+    value: number;
+    unit: string;
+}
+export interface AnalysisInput {
+    panel_id: string;
+    results: ResultInput[];
+    sex_at_birth?: "male" | "female";
+    age?: number;
+    fasting?: boolean;
+    on_thyroid_meds?: boolean;
+}
+export interface Finding {
+    biomarker_key: string;
+    display_name: string;
+    value: number;
+    unit: string;
+    status: "low" | "high" | "normal" | "unknown";
+    reference_range: string;
+    educational_context: string;
+    note?: string;
+}
+export interface AnalysisOutput {
+    panel_id: string;
+    panel_name: string;
+    summary: {
+        overall_status: "all_normal" | "some_outside_range" | "needs_attention" | "critical";
+        headline: string;
+    };
+    key_findings: Finding[];
+    reassuring_findings: string[];
+    missing_required_markers: string[];
+    red_flags_detected: boolean;
+    red_flag_message: string | null;
+    disclaimer_acknowledged: boolean;
+}
+/**
+ * Analyze panel results with educational context
+ * Returns structured findings without diagnostic language
+ */
+export declare function analyzePanelResults(input: AnalysisInput): AnalysisOutput;

package/dist/analysis/analyzePanelResults.js

@@ -0,0 +1,137 @@
+/**
+ * Analyze panel results - educational context only, no diagnostic language
+ */
+import { getReferenceRange, getApplicableRange, classifyValue, checkCriticalValue, formatReferenceRange, } from "../ranges/questRanges.js";
+import { getPanel } from "../ranges/panels.js";
+/**
+ * Analyze panel results with educational context
+ * Returns structured findings without diagnostic language
+ */
+export function analyzePanelResults(input) {
+    const panel = getPanel(input.panel_id);
+    if (!panel) {
+        return {
+            panel_id: input.panel_id,
+            panel_name: "Unknown Panel",
+            summary: {
+                overall_status: "needs_attention",
+                headline: "Unable to analyze: panel not found",
+            },
+            key_findings: [],
+            reassuring_findings: [],
+            missing_required_markers: [],
+            red_flags_detected: false,
+            red_flag_message: null,
+            disclaimer_acknowledged: false,
+        };
+    }
+    // Check for critical values first
+    const criticalFindings = [];
+    for (const result of input.results) {
+        const critical = checkCriticalValue(result.biomarker_key, result.value);
+        if (critical.isCritical && critical.message) {
+            criticalFindings.push({
+                key: result.biomarker_key,
+                message: critical.message,
+            });
+        }
+    }
+    if (criticalFindings.length > 0) {
+        return {
+            panel_id: input.panel_id,
+            panel_name: panel.name,
+            summary: {
+                overall_status: "critical",
+                headline: "Important: Please contact a healthcare provider promptly",
+            },
+            key_findings: [],
+            reassuring_findings: [],
+            missing_required_markers: [],
+            red_flags_detected: true,
+            red_flag_message: `One or more values require prompt medical attention. ${criticalFindings.map((f) => f.message).join(" ")} Please contact your healthcare provider or seek medical care.`,
+            disclaimer_acknowledged: false,
+        };
+    }
+    // Check for missing required markers
+    const providedKeys = input.results.map((r) => r.biomarker_key.toLowerCase());
+    const missingMarkers = panel.requiredMarkers.filter((m) => !providedKeys.includes(m.toLowerCase()));
+    // Analyze each result
+    const keyFindings = [];
+    const reassuringFindings = [];
+    for (const result of input.results) {
+        const biomarkerRange = getReferenceRange(result.biomarker_key);
+        if (!biomarkerRange) {
+            keyFindings.push({
+                biomarker_key: result.biomarker_key,
+                display_name: result.biomarker_key,
+                value: result.value,
+                unit: result.unit,
+                status: "unknown",
+                reference_range: "Not available",
+                educational_context: "Reference range not available for this marker.",
+            });
+            continue;
+        }
+        const applicableRange = getApplicableRange(biomarkerRange, input.sex_at_birth);
+        const status = classifyValue(result.value, applicableRange);
+        const referenceRangeStr = formatReferenceRange(applicableRange);
+        // Build educational context based on status
+        let educationalContext = biomarkerRange.educationalContext;
+        let note;
+        if (status === "low" && biomarkerRange.lowContext) {
+            educationalContext = biomarkerRange.lowContext;
+        }
+        else if (status === "high" && biomarkerRange.highContext) {
+            educationalContext = biomarkerRange.highContext;
+        }
+        // Add medication notes if relevant
+        if (input.on_thyroid_meds && ["tsh", "free-t4", "free-t3"].includes(result.biomarker_key.toLowerCase())) {
+            note = "Note: Thyroid medication can affect these values. Results are best interpreted by your prescribing clinician.";
+        }
+        // Add fasting note if relevant
+        if (!input.fasting && ["glucose", "insulin", "triglycerides"].includes(result.biomarker_key.toLowerCase())) {
+            note = "Note: This marker is ideally measured after fasting. Non-fasting values may be higher.";
+        }
+        const finding = {
+            biomarker_key: result.biomarker_key,
+            display_name: biomarkerRange.displayName,
+            value: result.value,
+            unit: result.unit,
+            status,
+            reference_range: referenceRangeStr,
+            educational_context: educationalContext,
+            note,
+        };
+        if (status === "normal") {
+            reassuringFindings.push(`${biomarkerRange.displayName} is within the expected range.`);
+        }
+        else {
+            keyFindings.push(finding);
+        }
+    }
+    // Determine overall status
+    let overallStatus = "all_normal";
+    let headline = "Your results are within expected ranges.";
+    if (keyFindings.length > 0) {
+        overallStatus = "some_outside_range";
+        const outsideRangeCount = keyFindings.filter((f) => f.status !== "unknown").length;
+        headline = `${outsideRangeCount} marker${outsideRangeCount !== 1 ? "s" : ""} outside the typical range. See details below.`;
+    }
+    if (missingMarkers.length > 0) {
+        headline += ` Note: ${missingMarkers.length} expected marker${missingMarkers.length !== 1 ? "s" : ""} not provided.`;
+    }
+    return {
+        panel_id: input.panel_id,
+        panel_name: panel.name,
+        summary: {
+            overall_status: overallStatus,
+            headline,
+        },
+        key_findings: keyFindings,
+        reassuring_findings: reassuringFindings,
+        missing_required_markers: missingMarkers,
+        red_flags_detected: false,
+        red_flag_message: null,
+        disclaimer_acknowledged: false,
+    };
+}

package/dist/analysis/generatePatientSummary.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Generate patient-friendly summary with required disclaimer
+ */
+import { AnalysisOutput } from "./analyzePanelResults.js";
+import { NextStepsOutput } from "./suggestNextSteps.js";
+export interface PatientSummaryCTA {
+    label: string;
+    url: string;
+}
+export interface PatientSummary {
+    headline: string;
+    bullets: string[];
+    cta: PatientSummaryCTA | null;
+    disclaimer: string;
+    requires_acknowledgment: boolean;
+}
+export interface PatientSummaryOutput {
+    patient_summary: PatientSummary;
+    safety_warning: string | null;
+}
+/**
+ * Generate a patient-friendly summary
+ * Requires disclaimer acknowledgment before showing analysis
+ */
+export declare function generatePatientSummary(panelId: string, analysis: AnalysisOutput, nextSteps: NextStepsOutput): PatientSummaryOutput;

package/dist/analysis/generatePatientSummary.js

@@ -0,0 +1,94 @@
+/**
+ * Generate patient-friendly summary with required disclaimer
+ */
+const DISCLAIMER = `This summary is for educational purposes only and is not medical advice. Reference ranges may vary by lab and individual factors. Always discuss your results with a qualified healthcare provider before making any health decisions.`;
+const SAFETY_DISCLAIMER = `IMPORTANT: One or more of your results requires prompt medical attention. Please contact your healthcare provider or seek medical care before reviewing this summary further.`;
+/**
+ * Generate a patient-friendly summary
+ * Requires disclaimer acknowledgment before showing analysis
+ */
+export function generatePatientSummary(panelId, analysis, nextSteps) {
+    // Safety check first
+    if (analysis.red_flags_detected || nextSteps.safety.red_flags_detected) {
+        return {
+            patient_summary: {
+                headline: "Please contact a healthcare provider",
+                bullets: [
+                    "One or more values in your results need prompt medical review.",
+                    "Do not delay seeking care based on this summary.",
+                    "Your healthcare provider can evaluate these findings properly.",
+                ],
+                cta: null,
+                disclaimer: DISCLAIMER,
+                requires_acknowledgment: true,
+            },
+            safety_warning: nextSteps.safety.message || SAFETY_DISCLAIMER,
+        };
+    }
+    // Build summary based on analysis and next steps
+    const bullets = [];
+    // Add headline context
+    if (analysis.summary.overall_status === "all_normal") {
+        bullets.push("All markers reviewed are within expected ranges.");
+    }
+    else if (analysis.key_findings.length > 0) {
+        bullets.push(`${analysis.key_findings.length} marker${analysis.key_findings.length !== 1 ? "s" : ""} outside the typical range.`);
+    }
+    // Add key findings (max 2)
+    const significantFindings = analysis.key_findings
+        .filter((f) => f.status === "low" || f.status === "high")
+        .slice(0, 2);
+    for (const finding of significantFindings) {
+        const direction = finding.status === "low" ? "below" : "above";
+        bullets.push(`${finding.display_name}: ${finding.value} ${finding.unit} (${direction} typical range of ${finding.reference_range})`);
+    }
+    // Add reassuring note if some things are normal
+    if (analysis.reassuring_findings.length > 0 && analysis.key_findings.length > 0) {
+        bullets.push(`${analysis.reassuring_findings.length} other marker${analysis.reassuring_findings.length !== 1 ? "s" : ""} within expected ranges.`);
+    }
+    // Add next step guidance
+    if (nextSteps.next_step.type === "additional_testing") {
+        bullets.push(`For more detail, consider: ${nextSteps.next_step.recommended_panel_name}`);
+    }
+    else if (nextSteps.next_step.type === "clinician_discussion") {
+        bullets.push("Consider discussing these results with your healthcare provider.");
+    }
+    // Ensure we have 3-5 bullets
+    if (bullets.length < 3) {
+        bullets.push("These results provide a snapshot of selected health markers.");
+    }
+    if (bullets.length < 3) {
+        bullets.push("A healthcare provider can help put these in context with your overall health.");
+    }
+    // Cap at 5 bullets
+    const finalBullets = bullets.slice(0, 5);
+    // Build CTA only for additional testing
+    let cta = null;
+    if (nextSteps.next_step.type === "additional_testing") {
+        cta = {
+            label: `Learn more: ${nextSteps.next_step.recommended_panel_name} ($${nextSteps.next_step.price})`,
+            url: nextSteps.next_step.order_url,
+        };
+    }
+    // Build headline
+    let headline;
+    if (analysis.summary.overall_status === "all_normal") {
+        headline = "Your results are within expected ranges";
+    }
+    else if (analysis.key_findings.length === 1) {
+        headline = "One marker to note in your results";
+    }
+    else {
+        headline = "A few markers to review in your results";
+    }
+    return {
+        patient_summary: {
+            headline,
+            bullets: finalBullets,
+            cta,
+            disclaimer: DISCLAIMER,
+            requires_acknowledgment: true,
+        },
+        safety_warning: null,
+    };
+}

package/dist/analysis/suggestNextSteps.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Suggest next steps based on panel analysis
+ * Returns at most ONE follow-up panel, framed as "more detail" not diagnosis
+ */
+import { AnalysisOutput } from "./analyzePanelResults.js";
+export interface NextStepAdditionalTesting {
+    type: "additional_testing";
+    recommended_panel_id: string;
+    recommended_panel_name: string;
+    reason: string;
+    confidence: "suggested" | "may_be_helpful";
+    order_url: string;
+    price: number;
+}
+export interface NextStepNoTesting {
+    type: "no_additional_testing";
+    reason: string;
+}
+export interface NextStepClinicianDiscussion {
+    type: "clinician_discussion";
+    reason: string;
+}
+export type NextStep = NextStepAdditionalTesting | NextStepNoTesting | NextStepClinicianDiscussion;
+export interface NextStepsOutput {
+    next_step: NextStep;
+    not_recommended: string[];
+    safety: {
+        red_flags_detected: boolean;
+        message: string | null;
+    };
+    clinician_guidance: string;
+}
+/**
+ * Suggest next steps based on analysis
+ * Conservative approach: one follow-up max, educational framing
+ */
+export declare function suggestNextSteps(panelId: string, analysis: AnalysisOutput): NextStepsOutput;