Files
HealthLog/src/lib/mcp/tools/get-labs.ts
T

168 lines
6.6 KiB
TypeScript

import { z } from "zod/v4";
import { fenceUserText } from "@/lib/ai/coach/data-fence";
import { resolveMarkerForRead } from "@/lib/labs/biomarker-resolve";
import {
getLabHistory,
LAB_HISTORY_MAX_LIMIT,
type LabHistoryResult,
} from "@/lib/mcp/rich-reads";
import { decodeOffsetCursor } from "@/lib/mcp/pagination";
import { annotate } from "@/lib/logging/context";
import { attachLabLinks, readLatestLabs } from "@/lib/mcp/lab-reads";
import type { McpAuthContext } from "../auth";
import { coachReadOutput, recordLinkSchema } from "./output-shapes";
import { runCoachTool, whenModuleOn } from "./shared";
import { READ_ONLY_ANNOTATIONS, type McpToolDefinition } from "./types";
import { labUnitText } from "@/lib/labs/dimensionless";
/** Output schema for `get_labs` — latest-per-biomarker OR a paginated history. */
const getLabsOutput: z.ZodRawShape = {
// Latest-mode payload, including typed empty-read availability metadata.
...coachReadOutput,
// History-mode payload (per-analyte trajectory + pagination).
analyte: z.string().optional(),
readings: z
.array(
z.object({
value: z.number().nullable(),
valueText: z.string().nullable(),
unit: z.string(),
referenceLow: z.number().nullable(),
referenceHigh: z.number().nullable(),
rangeStatus: z.enum(["in-range", "below", "above", "unknown"]),
takenAt: z.string(),
// The fetch ids of what this reading links to; each is described
// once in `linkedRecords`.
links: z.array(z.string()),
linksTruncated: z.boolean(),
}),
)
.optional(),
nextCursor: z.string().optional(),
// Both modes: every record a listed reading links to, named once.
linkedRecords: z.array(recordLinkSchema).optional(),
};
/** The free-text fields of a lab reading: a document's words, never instructions. */
const LAB_TEXT_KEYS = new Set([
"analyte",
"name",
"panel",
"unit",
"valueText",
]);
/**
* Fence every free-text field of a labs answer, at any depth. An analyte,
* panel or unit committed from an uploaded document is whatever a model read
* out of that file, so it reaches the client's model fenced, as the server
* instructions promise.
*/
function fenceLabText(value: unknown): unknown {
if (Array.isArray(value)) return value.map(fenceLabText);
if (value === null || typeof value !== "object") return value;
return Object.fromEntries(
Object.entries(value).map(([key, inner]) => [
key,
typeof inner === "string" && LAB_TEXT_KEYS.has(key)
? fenceUserText(inner)
: fenceLabText(inner),
]),
);
}
/**
* A value without a unit (a ratio, INR) is stored as the UCUM unity "1". The
* model is shown no unit for it, as the Coach's lab block does, so it never
* writes "3.6 1".
*/
function withShownUnits(result: LabHistoryResult): LabHistoryResult {
if (!result.readings) return result;
return {
...result,
readings: result.readings.map((r) => ({ ...r, unit: labUnitText(r.unit) })),
};
}
/** `get_labs` behind its module gate: latest-per-biomarker or a history page. */
function readLabs(
ctx: McpAuthContext,
args: Record<string, unknown>,
): Promise<unknown> {
// History mode: one analyte's paginated trajectory over the labs read
// path. Requires an analyte — there is no whole-record history dump.
if (args.history === true) {
const analyte = typeof args.analyte === "string" ? args.analyte : "";
if (!analyte.trim()) {
return Promise.resolve({
present: false,
reason: "analyte_required_for_history",
});
}
return getLabHistory(ctx.userId, {
analyte,
offset: decodeOffsetCursor(args.cursor),
limit: LAB_HISTORY_MAX_LIMIT,
}).then(withShownUnits);
}
// Default: latest reading per biomarker via the Coach labs read. A name that
// resolves to one of the user's markers (an alias or a catalog abbreviation
// such as "GPT" for "ALT") is read as that marker's own name (v1.43).
// A present read carries each reading's lab result id (see `lab-reads.ts`);
// a miss is the Coach read's grounded answer.
return (async () => {
const asked = typeof args.analyte === "string" ? args.analyte : null;
const marker = asked?.trim()
? await resolveMarkerForRead(ctx.userId, asked)
: null;
const analyte = asked !== null ? (marker?.name ?? asked) : undefined;
let missed = false;
const result = await readLatestLabs(ctx.userId, analyte, () => {
missed = true;
return runCoachTool(
ctx,
"get_labs",
analyte !== undefined ? { analyte } : {},
);
});
if (!missed) {
annotate({
action: { name: "mcp.tool.invoked" },
meta: { tool: "get_labs", present: true },
});
}
return result;
})();
}
export const getLabsTool: McpToolDefinition = {
name: "get_labs",
title: "Get lab results",
description:
"Fetch the user's lab results. By default returns the latest reading per biomarker over the whole record. Filtered to one named analyte, each matching marker also carries a summarised history (the newest earlier values in full, older ones as one mean / min / max / count per year). Pass history:true with an analyte to return that analyte's reading TRAJECTORY (newest first, paginated). Each reading carries its value, unit, reference range, and in-range/below/above status. Each reading (the latest, an earlier value in full, a trajectory reading; not a per-year summary) carries links: the ids of the records it is linked to (the report it was read from, the visits it is filed against), [] when none, at most 25 with linksTruncated; every linked record is described once in linkedRecords (id for fetch, kind, label, date, and for a document imported from Paperless-ngx or Papra its sourceSystem and sourceId). A document is listed only while the Documents module is on. Returns { present: false } when no labs match, and { present: false, reason: \"module_disabled\" } when the labs module is switched off.",
inputShape: {
analyte: z.string().min(1).max(80).optional(),
history: z
.boolean()
.optional()
.describe(
"When true (requires `analyte`), return that analyte's full reading trajectory (newest first, paginated) instead of the latest-per-biomarker snapshot.",
),
cursor: z
.string()
.max(256)
.optional()
.describe(
"Opaque pagination cursor from a previous history response's nextCursor. Treat as a black box.",
),
},
annotations: READ_ONLY_ANNOTATIONS,
outputShape: getLabsOutput,
run(ctx, args) {
return whenModuleOn(ctx, "labs", "get_labs", async () =>
attachLabLinks(ctx.userId, fenceLabText(await readLabs(ctx, args))),
);
},
};