justlabs-mcp-server 1.0.0 → 1.1.0

package/dist/analysis/suggestNextSteps.js

@@ -0,0 +1,136 @@
+/**
+ * Suggest next steps based on panel analysis
+ * Returns at most ONE follow-up panel, framed as "more detail" not diagnosis
+ */
+import { getPanel, getFollowUpRules } from "../ranges/panels.js";
+/**
+ * Suggest next steps based on analysis
+ * Conservative approach: one follow-up max, educational framing
+ */
+export function suggestNextSteps(panelId, analysis) {
+    // If red flags detected, always recommend clinician
+    if (analysis.red_flags_detected) {
+        return {
+            next_step: {
+                type: "clinician_discussion",
+                reason: "Based on your results, we recommend speaking with a healthcare provider before any additional testing.",
+            },
+            not_recommended: ["Additional testing through JustLabs at this time"],
+            safety: {
+                red_flags_detected: true,
+                message: analysis.red_flag_message,
+            },
+            clinician_guidance: "Please contact your healthcare provider or seek medical attention promptly.",
+        };
+    }
+    const rules = getFollowUpRules(panelId);
+    // Default response if no rules defined
+    if (!rules) {
+        return {
+            next_step: {
+                type: "clinician_discussion",
+                reason: "Consider discussing these results with a healthcare provider who can provide personalized guidance.",
+            },
+            not_recommended: [],
+            safety: {
+                red_flags_detected: false,
+                message: null,
+            },
+            clinician_guidance: "A healthcare provider can help interpret these results in the context of your overall health.",
+        };
+    }
+    // Get markers that are outside range
+    const abnormalMarkerKeys = analysis.key_findings
+        .filter((f) => f.status === "low" || f.status === "high")
+        .map((f) => f.biomarker_key.toLowerCase());
+    // Check each condition in order (first match wins)
+    for (const condition of rules.conditions) {
+        if (!condition.abnormalMarkers)
+            continue;
+        const matchesCondition = condition.abnormalMarkers.some((marker) => abnormalMarkerKeys.includes(marker.toLowerCase()));
+        if (matchesCondition) {
+            // If followUpPanelId is empty, suggest clinician discussion
+            if (!condition.followUpPanelId) {
+                return {
+                    next_step: {
+                        type: "clinician_discussion",
+                        reason: condition.reason,
+                    },
+                    not_recommended: ["Repeating the same panel within 4-6 weeks"],
+                    safety: {
+                        red_flags_detected: false,
+                        message: null,
+                    },
+                    clinician_guidance: "A healthcare provider can help determine the best next steps based on your complete health picture.",
+                };
+            }
+            const followUpPanel = getPanel(condition.followUpPanelId);
+            if (followUpPanel) {
+                return {
+                    next_step: {
+                        type: "additional_testing",
+                        recommended_panel_id: followUpPanel.id,
+                        recommended_panel_name: followUpPanel.name,
+                        reason: condition.reason,
+                        confidence: "may_be_helpful",
+                        order_url: followUpPanel.url,
+                        price: followUpPanel.price,
+                    },
+                    not_recommended: [
+                        "Repeating the same panel within 4-6 weeks",
+                        "Multiple additional panels at once",
+                    ],
+                    safety: {
+                        red_flags_detected: false,
+                        message: null,
+                    },
+                    clinician_guidance: "While additional testing may provide more detail, a healthcare provider can help you decide if it's right for you.",
+                };
+            }
+        }
+    }
+    // No conditions matched, use default
+    if (rules.defaultFollowUp) {
+        if (rules.defaultFollowUp.type === "no_additional_testing") {
+            return {
+                next_step: {
+                    type: "no_additional_testing",
+                    reason: rules.defaultFollowUp.reason,
+                },
+                not_recommended: ["Unnecessary repeat testing"],
+                safety: {
+                    red_flags_detected: false,
+                    message: null,
+                },
+                clinician_guidance: "Your results look reassuring. Consider sharing them with your healthcare provider at your next visit.",
+            };
+        }
+        else {
+            return {
+                next_step: {
+                    type: "clinician_discussion",
+                    reason: rules.defaultFollowUp.reason,
+                },
+                not_recommended: [],
+                safety: {
+                    red_flags_detected: false,
+                    message: null,
+                },
+                clinician_guidance: "A healthcare provider can help interpret these results and suggest appropriate next steps.",
+            };
+        }
+    }
+    // Fallback
+    return {
+        next_step: {
+            type: "clinician_discussion",
+            reason: "Consider discussing these results with a healthcare provider.",
+        },
+        not_recommended: [],
+        safety: {
+            red_flags_detected: false,
+            message: null,
+        },
+        clinician_guidance: "A healthcare provider can provide personalized guidance based on your complete health picture.",
+    };
+}

package/dist/index.js

@@ -2,6 +2,10 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// Analysis modules for results interpretation
+import { analyzePanelResults } from "./analysis/analyzePanelResults.js";
+import { suggestNextSteps } from "./analysis/suggestNextSteps.js";
+import { generatePatientSummary } from "./analysis/generatePatientSummary.js";
 // Lab test data (subset of popular tests)
 const labTests = [
     {
@@ -280,6 +284,91 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["testIds"],
                 },
             },
+            // Results analysis tools (educational, conservative)
+            {
+                name: "analyze_panel_results",
+                description: "Analyze lab panel results and provide educational context. IMPORTANT: This provides educational information only, not medical diagnosis. User must acknowledge disclaimer before viewing analysis.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        panel_id: {
+                            type: "string",
+                            description: "Panel ID (e.g., 'fatigue_panel', 'thyroid_deep_dive', 'metabolic_panel', 'wellness_basic')",
+                        },
+                        results: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    biomarker_key: { type: "string", description: "Biomarker key (e.g., 'tsh', 'ferritin', 'vitamin-d')" },
+                                    value: { type: "number", description: "The numeric value" },
+                                    unit: { type: "string", description: "The unit (e.g., 'mIU/L', 'ng/mL')" },
+                                },
+                                required: ["biomarker_key", "value", "unit"],
+                            },
+                            description: "Array of biomarker results",
+                        },
+                        sex_at_birth: {
+                            type: "string",
+                            enum: ["male", "female"],
+                            description: "Sex at birth (affects reference ranges for some markers)",
+                        },
+                        age: {
+                            type: "number",
+                            description: "Age in years (optional, may affect interpretation)",
+                        },
+                        fasting: {
+                            type: "boolean",
+                            description: "Whether the sample was taken after fasting",
+                        },
+                        on_thyroid_meds: {
+                            type: "boolean",
+                            description: "Whether currently taking thyroid medication",
+                        },
+                    },
+                    required: ["panel_id", "results"],
+                },
+            },
+            {
+                name: "suggest_next_steps",
+                description: "Based on panel analysis, suggest whether additional testing may provide more detail. Returns at most ONE follow-up panel suggestion. Educational only, not medical advice.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        panel_id: {
+                            type: "string",
+                            description: "The panel ID that was analyzed",
+                        },
+                        analysis: {
+                            type: "object",
+                            description: "The analysis object from analyze_panel_results",
+                        },
+                    },
+                    required: ["panel_id", "analysis"],
+                },
+            },
+            {
+                name: "generate_patient_summary",
+                description: "Generate a patient-friendly summary of results with educational context. Includes required disclaimer. MUST be shown to user with disclaimer acknowledgment.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        panel_id: {
+                            type: "string",
+                            description: "The panel ID",
+                        },
+                        analysis: {
+                            type: "object",
+                            description: "The analysis object from analyze_panel_results",
+                        },
+                        next_steps: {
+                            type: "object",
+                            description: "The next steps object from suggest_next_steps",
+                        },
+                    },
+                    required: ["panel_id", "analysis", "next_steps"],
+                },
+            },
         ],
     };
 });
@@ -426,6 +515,81 @@ No doctor visit or insurance needed.`,
                 ],
             };
         }
+        // Results analysis tools
+        case "analyze_panel_results": {
+            const input = {
+                panel_id: args?.panel_id,
+                results: args?.results,
+                sex_at_birth: args?.sex_at_birth,
+                age: args?.age,
+                fasting: args?.fasting,
+                on_thyroid_meds: args?.on_thyroid_meds,
+            };
+            const analysis = analyzePanelResults(input);
+            // If red flags detected, return safety message immediately
+            if (analysis.red_flags_detected) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `# IMPORTANT: Please Contact a Healthcare Provider
+
+${analysis.red_flag_message}
+
+This analysis cannot continue until these values have been reviewed by a healthcare professional.
+
+---
+**Disclaimer:** This is educational information only, not medical advice.`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(analysis, null, 2),
+                    },
+                ],
+            };
+        }
+        case "suggest_next_steps": {
+            const panelId = args?.panel_id;
+            const analysis = args?.analysis;
+            const nextSteps = suggestNextSteps(panelId, analysis);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(nextSteps, null, 2),
+                    },
+                ],
+            };
+        }
+        case "generate_patient_summary": {
+            const panelId = args?.panel_id;
+            const analysis = args?.analysis;
+            const nextSteps = args?.next_steps;
+            const summary = generatePatientSummary(panelId, analysis, nextSteps);
+            // Format as readable text for the user
+            let output = `# ${summary.patient_summary.headline}\n\n`;
+            if (summary.safety_warning) {
+                output += `**IMPORTANT:** ${summary.safety_warning}\n\n`;
+            }
+            output += summary.patient_summary.bullets.map((b) => `- ${b}`).join("\n");
+            if (summary.patient_summary.cta) {
+                output += `\n\n**Next step for more detail:** [${summary.patient_summary.cta.label}](${summary.patient_summary.cta.url})`;
+            }
+            output += `\n\n---\n**Disclaimer:** ${summary.patient_summary.disclaimer}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: output,
+                    },
+                ],
+            };
+        }
         default:
             return {
                 content: [

package/dist/ranges/panels.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Panel definitions with required markers and follow-up logic
+ */
+export interface PanelDefinition {
+    id: string;
+    name: string;
+    description: string;
+    requiredMarkers: string[];
+    optionalMarkers?: string[];
+    price: number;
+    url: string;
+}
+export interface FollowUpRule {
+    panelId: string;
+    conditions: {
+        abnormalMarkers?: string[];
+        followUpPanelId: string;
+        reason: string;
+    }[];
+    defaultFollowUp?: {
+        type: "no_additional_testing" | "clinician_discussion";
+        reason: string;
+    };
+}
+export declare const PANELS: PanelDefinition[];
+export declare const FOLLOW_UP_RULES: FollowUpRule[];
+export declare function getPanel(panelId: string): PanelDefinition | undefined;
+export declare function getFollowUpRules(panelId: string): FollowUpRule | undefined;

package/dist/ranges/panels.js

@@ -0,0 +1,115 @@
+/**
+ * Panel definitions with required markers and follow-up logic
+ */
+export const PANELS = [
+    {
+        id: "fatigue_panel",
+        name: "Fatigue Panel",
+        description: "Comprehensive testing for common causes of fatigue including thyroid, iron, B12, and vitamin D.",
+        requiredMarkers: ["tsh", "ferritin", "vitamin-b12", "vitamin-d", "wbc", "hemoglobin"],
+        optionalMarkers: ["free-t4", "folate"],
+        price: 55,
+        url: "https://justlabs.health/tests/panel/panel-fatigue",
+    },
+    {
+        id: "thyroid_deep_dive",
+        name: "Complete Thyroid Panel",
+        description: "Comprehensive thyroid evaluation including TSH, Free T4, Free T3, and thyroid antibodies.",
+        requiredMarkers: ["tsh", "free-t4", "free-t3", "tpo-antibodies", "thyroglobulin-antibodies"],
+        price: 65,
+        url: "https://justlabs.health/tests/panel/panel-thyroid-complete",
+    },
+    {
+        id: "metabolic_panel",
+        name: "Metabolic Health Panel",
+        description: "Assess blood sugar regulation and cardiovascular markers.",
+        requiredMarkers: ["hemoglobin-a1c", "glucose", "insulin", "total-cholesterol", "hdl-cholesterol", "ldl-cholesterol", "triglycerides"],
+        optionalMarkers: ["hs-crp"],
+        price: 75,
+        url: "https://justlabs.health/tests/panel/panel-metabolic",
+    },
+    {
+        id: "wellness_basic",
+        name: "Basic Wellness Panel",
+        description: "Essential health screening including blood counts, metabolic markers, lipids, and thyroid.",
+        requiredMarkers: ["wbc", "hemoglobin", "glucose", "creatinine", "alt", "total-cholesterol", "tsh"],
+        price: 35,
+        url: "https://justlabs.health/tests/panel/panel-wellness-basic",
+    },
+];
+export const FOLLOW_UP_RULES = [
+    {
+        panelId: "fatigue_panel",
+        conditions: [
+            {
+                // If thyroid markers abnormal, suggest deep dive
+                abnormalMarkers: ["tsh"],
+                followUpPanelId: "thyroid_deep_dive",
+                reason: "Your TSH result suggests thyroid function may benefit from a closer look. A complete thyroid panel provides more detail about how your thyroid is functioning.",
+            },
+            {
+                // If metabolic markers present and abnormal, suggest metabolic panel
+                abnormalMarkers: ["glucose"],
+                followUpPanelId: "metabolic_panel",
+                reason: "Your glucose result suggests metabolic health may benefit from a closer look. A metabolic panel provides more detail about blood sugar regulation and cardiovascular markers.",
+            },
+        ],
+        defaultFollowUp: {
+            type: "clinician_discussion",
+            reason: "Your results are within expected ranges. If fatigue persists, consider discussing with a healthcare provider who can review your complete health picture.",
+        },
+    },
+    {
+        panelId: "thyroid_deep_dive",
+        conditions: [
+            {
+                // If antibodies elevated, no further JustLabs testing needed
+                abnormalMarkers: ["tpo-antibodies", "thyroglobulin-antibodies"],
+                followUpPanelId: "", // Empty means clinician discussion
+                reason: "Your antibody results provide useful information. We recommend discussing these findings with a healthcare provider who can provide personalized guidance.",
+            },
+        ],
+        defaultFollowUp: {
+            type: "clinician_discussion",
+            reason: "Thyroid results are best interpreted by a healthcare provider who can consider your symptoms and health history.",
+        },
+    },
+    {
+        panelId: "metabolic_panel",
+        conditions: [],
+        defaultFollowUp: {
+            type: "clinician_discussion",
+            reason: "Metabolic results are best interpreted by a healthcare provider who can provide personalized guidance on lifestyle and any next steps.",
+        },
+    },
+    {
+        panelId: "wellness_basic",
+        conditions: [
+            {
+                abnormalMarkers: ["tsh"],
+                followUpPanelId: "thyroid_deep_dive",
+                reason: "Your TSH result suggests thyroid function may benefit from a closer look.",
+            },
+            {
+                abnormalMarkers: ["glucose"],
+                followUpPanelId: "metabolic_panel",
+                reason: "Your glucose result suggests metabolic health may benefit from a closer look.",
+            },
+            {
+                abnormalMarkers: ["hemoglobin", "wbc"],
+                followUpPanelId: "fatigue_panel",
+                reason: "Your blood count results suggest looking at additional markers that can affect energy levels.",
+            },
+        ],
+        defaultFollowUp: {
+            type: "no_additional_testing",
+            reason: "Your basic wellness markers are within expected ranges. Consider retesting annually or if new symptoms develop.",
+        },
+    },
+];
+export function getPanel(panelId) {
+    return PANELS.find((p) => p.id === panelId);
+}
+export function getFollowUpRules(panelId) {
+    return FOLLOW_UP_RULES.find((r) => r.panelId === panelId);
+}

package/dist/ranges/questRanges.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Quest-style reference ranges for common biomarkers
+ * These are educational reference points, not diagnostic criteria
+ */
+export interface ReferenceRange {
+    low?: number;
+    high?: number;
+    unit: string;
+    note?: string;
+}
+export interface BiomarkerRange {
+    key: string;
+    displayName: string;
+    unit: string;
+    defaultRange: ReferenceRange;
+    maleRange?: ReferenceRange;
+    femaleRange?: ReferenceRange;
+    educationalContext: string;
+    lowContext?: string;
+    highContext?: string;
+}
+export interface CriticalThreshold {
+    key: string;
+    criticalLow?: number;
+    criticalHigh?: number;
+    unit: string;
+    message: string;
+}
+export declare const CRITICAL_THRESHOLDS: CriticalThreshold[];
+export declare const BIOMARKER_RANGES: BiomarkerRange[];
+/**
+ * Get reference range for a biomarker, considering sex if provided
+ */
+export declare function getReferenceRange(biomarkerKey: string, sex?: "male" | "female"): BiomarkerRange | undefined;
+/**
+ * Get the appropriate range values for a biomarker based on sex
+ */
+export declare function getApplicableRange(biomarker: BiomarkerRange, sex?: "male" | "female"): ReferenceRange;
+/**
+ * Check if a value is within reference range
+ */
+export declare function classifyValue(value: number, range: ReferenceRange): "low" | "normal" | "high" | "unknown";
+/**
+ * Check for critical (red flag) values
+ */
+export declare function checkCriticalValue(biomarkerKey: string, value: number): {
+    isCritical: boolean;
+    message?: string;
+};
+/**
+ * Format a reference range for display
+ */
+export declare function formatReferenceRange(range: ReferenceRange): string;