justlabs-mcp-server 1.0.0 → 1.1.0

package/src/index.ts

@@ -7,6 +7,11 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 
+// Analysis modules for results interpretation
+import { analyzePanelResults, AnalysisInput } 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 = [
   {
@@ -291,6 +296,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"],
+        },
+      },
     ],
   };
 });
@@ -472,6 +562,96 @@ No doctor visit or insurance needed.`,
       };
     }
 
+    // Results analysis tools
+    case "analyze_panel_results": {
+      const input: AnalysisInput = {
+        panel_id: args?.panel_id as string,
+        results: args?.results as Array<{ biomarker_key: string; value: number; unit: string }>,
+        sex_at_birth: args?.sex_at_birth as "male" | "female" | undefined,
+        age: args?.age as number | undefined,
+        fasting: args?.fasting as boolean | undefined,
+        on_thyroid_meds: args?.on_thyroid_meds as boolean | undefined,
+      };
+
+      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 as string;
+      const analysis = args?.analysis as ReturnType<typeof analyzePanelResults>;
+
+      const nextSteps = suggestNextSteps(panelId, analysis);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(nextSteps, null, 2),
+          },
+        ],
+      };
+    }
+
+    case "generate_patient_summary": {
+      const panelId = args?.panel_id as string;
+      const analysis = args?.analysis as ReturnType<typeof analyzePanelResults>;
+      const nextSteps = args?.next_steps as ReturnType<typeof suggestNextSteps>;
+
+      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/src/ranges/panels.ts

@@ -0,0 +1,145 @@
+/**
+ * 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: {
+    // If any of these markers are outside range, suggest follow-up
+    abnormalMarkers?: string[];
+    // If all conditions met, suggest this follow-up
+    followUpPanelId: string;
+    reason: string;
+  }[];
+  // Default if no conditions match
+  defaultFollowUp?: {
+    type: "no_additional_testing" | "clinician_discussion";
+    reason: string;
+  };
+}
+
+export const PANELS: PanelDefinition[] = [
+  {
+    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: FollowUpRule[] = [
+  {
+    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: string): PanelDefinition | undefined {
+  return PANELS.find((p) => p.id === panelId);
+}
+
+export function getFollowUpRules(panelId: string): FollowUpRule | undefined {
+  return FOLLOW_UP_RULES.find((r) => r.panelId === panelId);
+}