@cyanheads/medical-codes-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/map-codes.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-codes.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/map-codes.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/search-codes.tool.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview medcode_search_codes — find codes whose official descriptions
+ * match a described concept, via full-text search over the bundled index.
+ * Filter by system, billable status, and chapter. The reverse of
+ * medcode_get_code: you have a clinical description and need the code.
+ * @module mcp-server/tools/definitions/search-codes.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const searchCodesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    system: z.ZodOptional<z.ZodEnum<{
+        ICD10CM: "ICD10CM";
+        ICD10PCS: "ICD10PCS";
+        HCPCS: "HCPCS";
+        RXNORM: "RXNORM";
+    }>>;
+    billableOnly: z.ZodDefault<z.ZodBoolean>;
+    chapter: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    codes: z.ZodArray<z.ZodObject<{
+        system: z.ZodString;
+        code: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        shortDescription: z.ZodNullable<z.ZodString>;
+        billable: z.ZodBoolean;
+        header: z.ZodBoolean;
+        chapter: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_match";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The full-text query returned zero rows.";
+    readonly recovery: "Broaden the terms, drop the system or chapter filter, or try clinical synonyms.";
+}], {
+    readonly effectiveQuery: z.ZodString;
+    readonly appliedFilters: z.ZodObject<{
+        system: z.ZodNullable<z.ZodString>;
+        billableOnly: z.ZodBoolean;
+        chapter: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    readonly truncated: z.ZodBoolean;
+    readonly shown: z.ZodNumber;
+    readonly cap: z.ZodNumber;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=search-codes.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-codes.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-codes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-codes.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AASjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyI1B,CAAC"}

package/dist/mcp-server/tools/definitions/search-codes.tool.js

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview medcode_search_codes — find codes whose official descriptions
+ * match a described concept, via full-text search over the bundled index.
+ * Filter by system, billable status, and chapter. The reverse of
+ * medcode_get_code: you have a clinical description and need the code.
+ * @module mcp-server/tools/definitions/search-codes.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getServerConfig } from '../../../config/server-config.js';
+import { getCodeIndexService } from '../../../services/code-index/code-index-service.js';
+import { SYSTEM_IDS } from '../../../services/code-index/types.js';
+import { renderCodeLine } from './_render.js';
+const SOURCE_URL = 'https://github.com/cyanheads/medical-codes-mcp-server/blob/main/src/mcp-server/tools/definitions/search-codes.tool.ts';
+export const searchCodesTool = tool('medcode_search_codes', {
+    title: 'medical-codes-mcp-server',
+    description: 'Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear (prefix-matched), so "diabetic neuropathy" returns codes mentioning both. Filter by `system` (ICD10CM/ICD10PCS/HCPCS/RXNORM), `billableOnly` to exclude headers/categories, and `chapter`. Use when you have a clinical description and need the code — the reverse of medcode_get_code. Results echo the resolved system per row for chaining, and disclose truncation when the result hits the cap.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    sourceUrl: SOURCE_URL,
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Clinical description to match, e.g. "type 2 diabetes with neuropathy".'),
+        system: z
+            .enum(SYSTEM_IDS)
+            .optional()
+            .describe('Restrict results to one system. Omit to search all bundled systems.'),
+        billableOnly: z
+            .boolean()
+            .default(false)
+            .describe('When true, return only billable leaf codes (exclude headers/categories).'),
+        chapter: z
+            .string()
+            .optional()
+            .describe("Restrict to a chapter/range bucket (the value from a code's `chapter` field)."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max codes to return. Defaults to the server's MEDCODE_MAX_RESULTS (50), ceiling 200."),
+    }),
+    output: z.object({
+        codes: z
+            .array(z
+            .object({
+            system: z.string().describe('The system the code belongs to, echoed for chaining.'),
+            code: z.string().describe('The code in display form (ICD-10-CM carries the dot).'),
+            description: z
+                .string()
+                .nullable()
+                .describe('Official long description (falls back to short when no long form exists).'),
+            shortDescription: z
+                .string()
+                .nullable()
+                .describe('Official short description, or null when none is on record.'),
+            billable: z.boolean().describe('True when the code is a billable leaf.'),
+            header: z.boolean().describe('True when the code is a non-billable category/header.'),
+            chapter: z.string().nullable().describe('Chapter/range bucket, or null.'),
+        })
+            .describe('A code matching the search query.'))
+            .describe('Matching codes, ranked by full-text relevance.'),
+    }),
+    enrichment: {
+        effectiveQuery: z.string().describe('The query as the server parsed it for matching.'),
+        appliedFilters: z
+            .object({
+            system: z.string().nullable().describe('System filter applied, or null.'),
+            billableOnly: z.boolean().describe('Whether the billable-only filter was applied.'),
+            chapter: z.string().nullable().describe('Chapter filter applied, or null.'),
+        })
+            .describe('Filters the server applied to the search.'),
+        truncated: z.boolean().describe('True when results were capped at the limit.'),
+        shown: z.number().describe('Number of codes returned.'),
+        cap: z.number().describe('The limit that was applied.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Guidance when nothing matched — echoes the query and suggests how to broaden.'),
+    },
+    enrichmentTrailer: {
+        appliedFilters: {
+            render: (f) => `**Filters:** system=${f.system ?? 'any'}, billableOnly=${f.billableOnly}, chapter=${f.chapter ?? 'any'}`,
+        },
+    },
+    errors: [
+        {
+            reason: 'no_match',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The full-text query returned zero rows.',
+            recovery: 'Broaden the terms, drop the system or chapter filter, or try clinical synonyms.',
+        },
+    ],
+    handler(input, ctx) {
+        const cap = input.limit ?? getServerConfig().maxResults;
+        const codes = getCodeIndexService().searchFts(input.query, {
+            ...(input.system && { system: input.system }),
+            billableOnly: input.billableOnly,
+            ...(input.chapter && { chapter: input.chapter }),
+            limit: cap,
+        });
+        ctx.enrich({
+            effectiveQuery: input.query.trim(),
+            appliedFilters: {
+                system: input.system ?? null,
+                billableOnly: input.billableOnly,
+                chapter: input.chapter ?? null,
+            },
+        });
+        const wasTruncated = codes.length >= cap;
+        ctx.enrich({ truncated: wasTruncated, shown: codes.length, cap });
+        if (codes.length === 0) {
+            ctx.enrich.notice(`No codes matched "${input.query.trim()}"${input.system ? ` in ${input.system}` : ''}. ` +
+                'Broaden the terms, drop the filters, or try clinical synonyms.');
+            ctx.log.info('Search returned no matches', { query: input.query });
+            return { codes };
+        }
+        ctx.log.info('Search completed', { query: input.query, count: codes.length });
+        return { codes };
+    },
+    format: (result) => {
+        if (result.codes.length === 0) {
+            return [{ type: 'text', text: 'No matching codes.' }];
+        }
+        const lines = [`## ${result.codes.length} matching code(s)`, ''];
+        for (const c of result.codes)
+            lines.push(renderCodeLine(c));
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=search-codes.tool.js.map

package/dist/mcp-server/tools/definitions/search-codes.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-codes.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-codes.tool.ts"],"names":[],"mappings":"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"}

package/dist/services/code-index/code-index-service.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview The code-index service — the single source of truth for the
+ * server. Opens the bundled SQLite + FTS5 database read-only at startup and
+ * exposes typed query methods the six tools compose: decode, search, validate,
+ * crosswalk, and hierarchy-browse. No network, no tenant state — the corpus is
+ * global, read-only, and built at package-build time.
+ * @module services/code-index/code-index-service
+ */
+import { type BuildMetaRow, type CheckStatus, type CodeRow, type MapDirection, type PcsAxisRow, type SystemId } from './types.js';
+/** A decoded code with display form and derived flags, the shape tools return. */
+export interface DecodedCode {
+    billable: boolean;
+    chapter: string | null;
+    code: string;
+    description: string | null;
+    header: boolean;
+    shortDescription: string | null;
+    system: SystemId;
+}
+/** A decoded code plus its immediate hierarchy neighbours. */
+export interface DecodedCodeWithHierarchy extends DecodedCode {
+    children: DecodedCode[];
+    parent: string | null;
+}
+/** Result of a validity check — discriminated status plus optional why-not. */
+export interface CheckResult {
+    code: string;
+    status: CheckStatus;
+    system: SystemId;
+    whyNot?: string;
+}
+/** One crosswalk hit with the edge/provenance that produced it. */
+export interface MapHit {
+    description?: string;
+    /** The system or relationship that answered (e.g. 'ICD10CM', 'has_ingredient'). */
+    source: string;
+    system: SystemId | null;
+    value: string;
+}
+/** A FTS search hit. */
+export interface SearchHit extends DecodedCode {
+}
+/**
+ * Read-only handle over the bundled medical-codes index. Constructed once in
+ * `setup()`. All query methods are synchronous SQLite reads — fast enough to
+ * call inline from handlers.
+ */
+export declare class CodeIndexService {
+    private readonly db;
+    readonly dbPath: string;
+    private constructor();
+    /**
+     * Open the bundled DB read-only and assert it is a populated build. Fails fast
+     * (throws) on a missing file, an unreadable DB, or an empty `build_meta` — a
+     * broken bundle should crash loudly at startup, not serve empty results.
+     */
+    static open(): Promise<CodeIndexService>;
+    /** Map a raw `codes` row (snake_case, 0/1 ints) to a typed CodeRow. */
+    private static toCodeRow;
+    /** Project a CodeRow into the display shape tools return. */
+    private static decode;
+    /** Lexically-plausible systems for a raw code (no DB hit). */
+    detectSystem(rawCode: string): SystemId[];
+    /** Fetch the raw row for a code in a specific system, or null. */
+    private getRow;
+    /**
+     * Find which systems actually contain a code string. Narrows by lexical shape
+     * first (cheap), then confirms membership in the DB. The lexical candidates
+     * may overlap (a letter+4-digit code is shaped like both ICD-10-CM and HCPCS);
+     * DB membership is the real disambiguator — a code present in exactly one
+     * system is unambiguous regardless of shape overlap.
+     */
+    private resolveSystems;
+    /**
+     * Decode one code. Returns `{ kind: 'found' }` with the row, `'ambiguous'`
+     * with the colliding systems, or `'not_found'`. When `system` is given it is
+     * authoritative; otherwise membership across detected systems decides.
+     */
+    getByCode(rawCode: string, system?: SystemId): {
+        kind: 'found';
+        row: CodeRow;
+    } | {
+        kind: 'ambiguous';
+        systems: SystemId[];
+    } | {
+        kind: 'not_found';
+    };
+    /** Immediate children of a code within its system (prefix hierarchy). */
+    childrenOf(system: SystemId, parentCode: string): DecodedCode[];
+    /** Decode with parent + immediate children attached. */
+    getByCodeWithHierarchy(row: CodeRow): DecodedCodeWithHierarchy;
+    /**
+     * Full-text search over code descriptions. Translates the user's text into a
+     * safe FTS5 MATCH expression (every token required, prefix-matched), applies
+     * the system/billable/chapter filters, and caps at `limit`.
+     */
+    searchFts(queryText: string, filters: {
+        system?: SystemId;
+        billableOnly?: boolean;
+        chapter?: string;
+        limit: number;
+    }): SearchHit[];
+    /**
+     * Validate a code's existence, currency, and billability. Existence vs.
+     * validity are split: a non-billable or terminated code is a *successful*
+     * status with a why-not, NOT a failure. Only a code absent from every detected
+     * system is `unknown`.
+     */
+    checkCode(rawCode: string, system?: SystemId): {
+        kind: 'resolved';
+        result: CheckResult;
+    } | {
+        kind: 'ambiguous';
+        systems: SystemId[];
+    };
+    /**
+     * Crosswalk a value across systems or within a hierarchy. v1 supports the
+     * hierarchy directions (`parents`/`children`); the drug directions resolve
+     * against the RxNorm tables, which are empty until phase 2 — the tool guards
+     * for that before calling.
+     */
+    mapCode(from: string, direction: MapDirection, system?: SystemId): {
+        kind: 'ok';
+        hits: MapHit[];
+        resolvedSystem: SystemId | null;
+    } | {
+        kind: 'ambiguous';
+        systems: SystemId[];
+    } | {
+        kind: 'source_not_found';
+    };
+    /** Whether the RxNorm tables carry any rows (i.e. phase 2 is bundled). */
+    hasRxNorm(): boolean;
+    /** RxNorm crosswalk resolution. */
+    private mapDrug;
+    /** True when `direction` needs the RxNorm tables. */
+    static isDrugDirection(direction: MapDirection): boolean;
+    /**
+     * Browse a system's hierarchy. With no `node`: top-level entries (3-char
+     * ICD-10-CM categories grouped by chapter letter, HCPCS range buckets, PCS
+     * section axis values). With a `node`: that node's children — for ICD-10-PCS,
+     * the valid next-position axis values rather than prefix children.
+     */
+    browse(system: SystemId, node: string | undefined, limit: number): {
+        kind: 'codes';
+        codes: DecodedCode[];
+    } | {
+        kind: 'axes';
+        axes: PcsAxisRow[];
+    } | {
+        kind: 'unknown_node';
+    };
+    /**
+     * PCS axis browse. Only the position-1 Section axis is baked into `pcs_axes`
+     * (positions 2-7 are context-dependent on the full preceding axis path and a
+     * flat table can't represent them without storing wrong meanings — see
+     * `parseIcd10pcsAxes`). So the top level (no node) returns the 17 Sections;
+     * a partial code asks for a deeper position, which has no rows — the caller
+     * gets an explicit notice (handled in the tool), not silent-empty or wrong data.
+     */
+    private browsePcs;
+    /** Provenance for every bundled system. */
+    listSystems(): BuildMetaRow[];
+    /** Expose the decode projection for tools that already hold a CodeRow. */
+    static project(row: CodeRow): DecodedCode;
+}
+/**
+ * Translate free user text into a safe FTS5 MATCH expression. Strips FTS5
+ * operator characters, splits into tokens, and ANDs prefix-matched tokens so
+ * "diabetic neuropathy" requires both stems. Returns null when nothing usable
+ * remains (caller treats that as an empty result, not an error).
+ */
+export declare function toFtsMatch(text: string): string | null;
+/**
+ * Escape SQL LIKE wildcards (`%`, `_`) and the escape char (`\`) in a
+ * user-supplied substring so it matches literally inside a `LIKE '%…%'` pattern.
+ * Pair with `ESCAPE '\'` in the query. Without this a value like `%` would match
+ * every row; `_` would match any single character.
+ */
+export declare function escapeLike(value: string): string;
+/** Open the bundled index and cache the handle. Called once from `setup()`. */
+export declare function initCodeIndexService(): Promise<void>;
+/** Return the initialized service, throwing if `setup()` hasn't run. */
+export declare function getCodeIndexService(): CodeIndexService;
+//# sourceMappingURL=code-index-service.d.ts.map

package/dist/services/code-index/code-index-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-index-service.d.ts","sourceRoot":"","sources":["../../../src/services/code-index/code-index-service.ts"],"names":[],"mappings":"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"}