justlabs-mcp-server 1.0.0 → 1.1.0

package/dist/ranges/questRanges.js

@@ -0,0 +1,335 @@
+/**
+ * Quest-style reference ranges for common biomarkers
+ * These are educational reference points, not diagnostic criteria
+ */
+export const CRITICAL_THRESHOLDS = [
+    {
+        key: "glucose",
+        criticalLow: 50,
+        criticalHigh: 400,
+        unit: "mg/dL",
+        message: "Glucose levels outside this range require prompt medical evaluation.",
+    },
+    {
+        key: "potassium",
+        criticalLow: 2.5,
+        criticalHigh: 6.5,
+        unit: "mEq/L",
+        message: "Potassium levels outside this range can affect heart rhythm and require immediate medical attention.",
+    },
+    {
+        key: "sodium",
+        criticalLow: 120,
+        criticalHigh: 160,
+        unit: "mEq/L",
+        message: "Sodium levels outside this range require prompt medical evaluation.",
+    },
+    {
+        key: "hemoglobin",
+        criticalLow: 7.0,
+        criticalHigh: 20.0,
+        unit: "g/dL",
+        message: "Hemoglobin levels outside this range require prompt medical evaluation.",
+    },
+    {
+        key: "tsh",
+        criticalLow: 0.01,
+        criticalHigh: 50,
+        unit: "mIU/L",
+        message: "TSH levels outside this range suggest significant thyroid dysfunction requiring medical evaluation.",
+    },
+    {
+        key: "creatinine",
+        criticalHigh: 10.0,
+        unit: "mg/dL",
+        message: "Significantly elevated creatinine may indicate kidney dysfunction requiring medical evaluation.",
+    },
+];
+export const BIOMARKER_RANGES = [
+    // Thyroid markers
+    {
+        key: "tsh",
+        displayName: "TSH (Thyroid Stimulating Hormone)",
+        unit: "mIU/L",
+        defaultRange: { low: 0.45, high: 4.5, unit: "mIU/L" },
+        educationalContext: "TSH is produced by the pituitary gland and signals the thyroid to produce hormones.",
+        lowContext: "Lower TSH may indicate the thyroid is producing more hormone than usual.",
+        highContext: "Higher TSH may indicate the thyroid is working harder than usual to produce hormones.",
+    },
+    {
+        key: "free-t4",
+        displayName: "Free T4 (Thyroxine)",
+        unit: "ng/dL",
+        defaultRange: { low: 0.8, high: 1.8, unit: "ng/dL" },
+        educationalContext: "Free T4 is the active, unbound form of the main thyroid hormone.",
+        lowContext: "Lower Free T4 may indicate reduced thyroid hormone production.",
+        highContext: "Higher Free T4 may indicate increased thyroid hormone production.",
+    },
+    {
+        key: "free-t3",
+        displayName: "Free T3 (Triiodothyronine)",
+        unit: "pg/mL",
+        defaultRange: { low: 2.3, high: 4.2, unit: "pg/mL" },
+        educationalContext: "Free T3 is the most active thyroid hormone used by cells.",
+        lowContext: "Lower Free T3 may indicate reduced conversion from T4 or lower thyroid function.",
+        highContext: "Higher Free T3 may indicate increased thyroid activity.",
+    },
+    {
+        key: "tpo-antibodies",
+        displayName: "TPO Antibodies",
+        unit: "IU/mL",
+        defaultRange: { high: 34, unit: "IU/mL" },
+        educationalContext: "TPO antibodies, when elevated, may indicate autoimmune thyroid activity.",
+        highContext: "Elevated TPO antibodies are often seen in autoimmune thyroid conditions like Hashimoto's.",
+    },
+    {
+        key: "thyroglobulin-antibodies",
+        displayName: "Thyroglobulin Antibodies",
+        unit: "IU/mL",
+        defaultRange: { high: 1, unit: "IU/mL" },
+        educationalContext: "Thyroglobulin antibodies, when elevated, may indicate autoimmune thyroid activity.",
+        highContext: "Elevated thyroglobulin antibodies are sometimes seen alongside TPO antibodies in autoimmune thyroid conditions.",
+    },
+    // Iron and blood markers
+    {
+        key: "ferritin",
+        displayName: "Ferritin",
+        unit: "ng/mL",
+        defaultRange: { low: 30, high: 300, unit: "ng/mL" },
+        maleRange: { low: 30, high: 400, unit: "ng/mL" },
+        femaleRange: { low: 20, high: 200, unit: "ng/mL" },
+        educationalContext: "Ferritin reflects iron stores in your body.",
+        lowContext: "Lower ferritin may indicate depleted iron stores, a common cause of fatigue.",
+        highContext: "Higher ferritin can indicate excess iron stores or inflammation.",
+    },
+    {
+        key: "hemoglobin",
+        displayName: "Hemoglobin",
+        unit: "g/dL",
+        defaultRange: { low: 12.0, high: 17.5, unit: "g/dL" },
+        maleRange: { low: 13.5, high: 17.5, unit: "g/dL" },
+        femaleRange: { low: 12.0, high: 16.0, unit: "g/dL" },
+        educationalContext: "Hemoglobin carries oxygen in red blood cells.",
+        lowContext: "Lower hemoglobin may indicate anemia, which can cause fatigue and weakness.",
+        highContext: "Higher hemoglobin may indicate dehydration or other conditions.",
+    },
+    {
+        key: "wbc",
+        displayName: "White Blood Cell Count",
+        unit: "K/uL",
+        defaultRange: { low: 4.5, high: 11.0, unit: "K/uL" },
+        educationalContext: "White blood cells are part of your immune system.",
+        lowContext: "Lower WBC may indicate reduced immune cell production.",
+        highContext: "Higher WBC may indicate the body is responding to infection or inflammation.",
+    },
+    // Vitamins
+    {
+        key: "vitamin-d",
+        displayName: "Vitamin D, 25-Hydroxy",
+        unit: "ng/mL",
+        defaultRange: { low: 30, high: 100, unit: "ng/mL" },
+        educationalContext: "Vitamin D is important for bone health, immune function, and energy.",
+        lowContext: "Lower vitamin D is very common and may contribute to fatigue, bone health concerns, and immune function.",
+        highContext: "Very high vitamin D levels are uncommon and usually only seen with supplementation.",
+    },
+    {
+        key: "vitamin-b12",
+        displayName: "Vitamin B12",
+        unit: "pg/mL",
+        defaultRange: { low: 200, high: 900, unit: "pg/mL" },
+        educationalContext: "Vitamin B12 is essential for nerve function and red blood cell production.",
+        lowContext: "Lower B12 may contribute to fatigue, numbness/tingling, and cognitive changes.",
+        highContext: "Higher B12 is generally not concerning and often seen with supplementation.",
+    },
+    {
+        key: "folate",
+        displayName: "Folate",
+        unit: "ng/mL",
+        defaultRange: { low: 3.0, high: 20.0, unit: "ng/mL" },
+        educationalContext: "Folate is a B vitamin important for cell division and red blood cell formation.",
+        lowContext: "Lower folate may contribute to anemia and fatigue.",
+    },
+    // Metabolic markers
+    {
+        key: "glucose",
+        displayName: "Glucose (Fasting)",
+        unit: "mg/dL",
+        defaultRange: { low: 70, high: 99, unit: "mg/dL" },
+        educationalContext: "Fasting glucose reflects blood sugar levels after not eating for 8-12 hours.",
+        lowContext: "Lower fasting glucose may cause symptoms like shakiness or fatigue.",
+        highContext: "Higher fasting glucose may indicate insulin resistance or prediabetes, worth discussing with a clinician.",
+    },
+    {
+        key: "hemoglobin-a1c",
+        displayName: "Hemoglobin A1c",
+        unit: "%",
+        defaultRange: { low: 4.0, high: 5.6, unit: "%" },
+        educationalContext: "HbA1c reflects average blood sugar over the past 2-3 months.",
+        highContext: "Higher A1c (5.7-6.4%) may indicate prediabetes. Above 6.5% is in the diabetes range.",
+    },
+    {
+        key: "insulin",
+        displayName: "Insulin (Fasting)",
+        unit: "uIU/mL",
+        defaultRange: { low: 2.6, high: 24.9, unit: "uIU/mL" },
+        educationalContext: "Fasting insulin helps assess how hard the pancreas is working to manage blood sugar.",
+        highContext: "Higher fasting insulin may indicate insulin resistance, even with normal glucose.",
+    },
+    // Lipids
+    {
+        key: "total-cholesterol",
+        displayName: "Total Cholesterol",
+        unit: "mg/dL",
+        defaultRange: { high: 200, unit: "mg/dL" },
+        educationalContext: "Total cholesterol is the sum of all cholesterol types in your blood.",
+        highContext: "Higher total cholesterol is one factor in cardiovascular risk assessment.",
+    },
+    {
+        key: "ldl-cholesterol",
+        displayName: "LDL Cholesterol",
+        unit: "mg/dL",
+        defaultRange: { high: 100, unit: "mg/dL" },
+        educationalContext: "LDL is often called 'bad' cholesterol because it can contribute to plaque buildup.",
+        highContext: "Higher LDL is associated with increased cardiovascular risk.",
+    },
+    {
+        key: "hdl-cholesterol",
+        displayName: "HDL Cholesterol",
+        unit: "mg/dL",
+        defaultRange: { low: 40, unit: "mg/dL" },
+        maleRange: { low: 40, unit: "mg/dL" },
+        femaleRange: { low: 50, unit: "mg/dL" },
+        educationalContext: "HDL is often called 'good' cholesterol because it helps remove other cholesterol.",
+        lowContext: "Lower HDL may be associated with increased cardiovascular risk.",
+    },
+    {
+        key: "triglycerides",
+        displayName: "Triglycerides",
+        unit: "mg/dL",
+        defaultRange: { high: 150, unit: "mg/dL" },
+        educationalContext: "Triglycerides are a type of fat in the blood, often elevated after meals.",
+        highContext: "Higher triglycerides may be influenced by diet, alcohol, or metabolic factors.",
+    },
+    // Inflammation
+    {
+        key: "hs-crp",
+        displayName: "hs-CRP (High Sensitivity C-Reactive Protein)",
+        unit: "mg/L",
+        defaultRange: { high: 3.0, unit: "mg/L" },
+        educationalContext: "hs-CRP is a marker of inflammation in the body.",
+        highContext: "Higher hs-CRP may indicate inflammation, which has many possible causes.",
+    },
+    // Hormones
+    {
+        key: "testosterone-total",
+        displayName: "Testosterone, Total",
+        unit: "ng/dL",
+        maleRange: { low: 264, high: 916, unit: "ng/dL" },
+        femaleRange: { low: 8, high: 60, unit: "ng/dL" },
+        defaultRange: { low: 8, high: 916, unit: "ng/dL" },
+        educationalContext: "Testosterone plays a role in energy, muscle mass, and mood in both men and women.",
+        lowContext: "Lower testosterone may contribute to fatigue, reduced libido, and mood changes.",
+        highContext: "Higher testosterone may have various causes depending on sex and other factors.",
+    },
+    // Kidney
+    {
+        key: "creatinine",
+        displayName: "Creatinine",
+        unit: "mg/dL",
+        maleRange: { low: 0.7, high: 1.3, unit: "mg/dL" },
+        femaleRange: { low: 0.6, high: 1.1, unit: "mg/dL" },
+        defaultRange: { low: 0.6, high: 1.3, unit: "mg/dL" },
+        educationalContext: "Creatinine is a waste product filtered by the kidneys.",
+        highContext: "Higher creatinine may indicate the kidneys are working harder to filter waste.",
+    },
+    {
+        key: "bun",
+        displayName: "Blood Urea Nitrogen (BUN)",
+        unit: "mg/dL",
+        defaultRange: { low: 7, high: 20, unit: "mg/dL" },
+        educationalContext: "BUN is a waste product from protein metabolism, filtered by the kidneys.",
+        highContext: "Higher BUN may indicate dehydration or reduced kidney function.",
+    },
+    // Liver
+    {
+        key: "alt",
+        displayName: "ALT (Alanine Aminotransferase)",
+        unit: "U/L",
+        defaultRange: { low: 7, high: 56, unit: "U/L" },
+        educationalContext: "ALT is an enzyme found primarily in the liver.",
+        highContext: "Higher ALT may indicate liver cell activity or stress.",
+    },
+    {
+        key: "ast",
+        displayName: "AST (Aspartate Aminotransferase)",
+        unit: "U/L",
+        defaultRange: { low: 10, high: 40, unit: "U/L" },
+        educationalContext: "AST is an enzyme found in the liver, heart, and muscles.",
+        highContext: "Higher AST may indicate liver, heart, or muscle cell activity.",
+    },
+];
+/**
+ * Get reference range for a biomarker, considering sex if provided
+ */
+export function getReferenceRange(biomarkerKey, sex) {
+    const biomarker = BIOMARKER_RANGES.find((b) => b.key.toLowerCase() === biomarkerKey.toLowerCase());
+    return biomarker;
+}
+/**
+ * Get the appropriate range values for a biomarker based on sex
+ */
+export function getApplicableRange(biomarker, sex) {
+    if (sex === "male" && biomarker.maleRange) {
+        return biomarker.maleRange;
+    }
+    if (sex === "female" && biomarker.femaleRange) {
+        return biomarker.femaleRange;
+    }
+    return biomarker.defaultRange;
+}
+/**
+ * Check if a value is within reference range
+ */
+export function classifyValue(value, range) {
+    if (range.low !== undefined && value < range.low) {
+        return "low";
+    }
+    if (range.high !== undefined && value > range.high) {
+        return "high";
+    }
+    if (range.low === undefined && range.high === undefined) {
+        return "unknown";
+    }
+    return "normal";
+}
+/**
+ * Check for critical (red flag) values
+ */
+export function checkCriticalValue(biomarkerKey, value) {
+    const threshold = CRITICAL_THRESHOLDS.find((t) => t.key.toLowerCase() === biomarkerKey.toLowerCase());
+    if (!threshold) {
+        return { isCritical: false };
+    }
+    if (threshold.criticalLow !== undefined && value < threshold.criticalLow) {
+        return { isCritical: true, message: threshold.message };
+    }
+    if (threshold.criticalHigh !== undefined && value > threshold.criticalHigh) {
+        return { isCritical: true, message: threshold.message };
+    }
+    return { isCritical: false };
+}
+/**
+ * Format a reference range for display
+ */
+export function formatReferenceRange(range) {
+    if (range.low !== undefined && range.high !== undefined) {
+        return `${range.low}-${range.high} ${range.unit}`;
+    }
+    if (range.low !== undefined) {
+        return `>= ${range.low} ${range.unit}`;
+    }
+    if (range.high !== undefined) {
+        return `<= ${range.high} ${range.unit}`;
+    }
+    return range.unit;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "justlabs-mcp-server",
-  "version": "1.0.0",
-  "description": "MCP server for JustLabs - search lab tests, get pricing, find locations",
+  "version": "1.1.0",
+  "description": "MCP server for JustLabs - search lab tests, get pricing, analyze results with educational context",
   "main": "dist/index.js",
   "type": "module",
   "bin": {

package/src/__tests__/analysis.test.ts

@@ -0,0 +1,235 @@
+/**
+ * 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: string, fn: () => void) {
+  try {
+    fn();
+    console.log(`✓ ${name}`);
+    passed++;
+  } catch (e: any) {
+    console.log(`✗ ${name}`);
+    console.log(`  Error: ${e.message}`);
+    failed++;
+  }
+}
+
+function expect(actual: any) {
+  return {
+    toBe(expected: any) {
+      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: string) {
+      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);
+}