ictrp-mcp-server 0.1.0

package/dist/index.js

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the WHO ICTRP, over stdio.
+ *
+ * This file is the MCP surface and nothing else. It validates arguments,
+ * ensures the Python sidecar is up, forwards the call, and shapes the result.
+ * All domain logic -- the postback chain, the incompleteness accounting, the
+ * local query engine -- lives in Python, where it is tested.
+ *
+ * The one rule that shapes every handler here: **a failure must never be
+ * presented as a successful empty result.** ICTRP's export silently omits
+ * records, so an empty answer and a failed answer are dangerously easy to
+ * confuse. Failures are therefore reported with `isError: true` and a
+ * machine-readable `error_code`, and the incompleteness notice is attached to
+ * every successful result that carries rows.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getEnvReport } from "./runtime/env-probe.js";
+import { callSidecar, pingSidecar, SEARCH_TIMEOUT_MS, toErrorText, } from "./runtime/sidecar-client.js";
+import { ensureSidecar, installShutdownHooks, sidecarLogTail } from "./runtime/supervisor.js";
+const SERVER_NAME = "ictrp-mcp-server";
+const SERVER_VERSION = "0.1.0";
+/**
+ * Attached to every payload that returns rows.
+ *
+ * This is not boilerplate. A model that receives 12 rows and no warning will
+ * say "there are 12 trials"; the measured shortfall against the portal's own
+ * counts reaches 29% for some queries, so that sentence can be badly wrong.
+ */
+const INCOMPLETENESS_NOTICE = "Counts describe retrieved rows only. The ICTRP CSV export is known to omit records " +
+    "the portal itself reports as matches, so absence is not evidence of nonexistence.";
+const ATTRIBUTION_NOTICE = "Source: WHO ICTRP. Attribute as 'WHO ICTRP' and display the processing date. " +
+    "Chinese-registry records must be attributed as 'ChiCTR via WHO ICTRP'.";
+const FILTER_SCHEMA = {
+    type: "array",
+    description: "Filters applied with AND. Multiple filters on the same field are also ANDed.",
+    items: {
+        type: "object",
+        required: ["field", "op"],
+        properties: {
+            field: {
+                type: "string",
+                description: "Normalized field name, e.g. source_register, phase_code, recruitment_status_normalized, " +
+                    "registration_date, target_size_total, countries, condition.",
+            },
+            op: {
+                type: "string",
+                enum: [
+                    "eq",
+                    "ne",
+                    "contains",
+                    "not_contains",
+                    "in",
+                    "not_in",
+                    "gt",
+                    "gte",
+                    "lt",
+                    "lte",
+                    "exists",
+                    "not_exists",
+                    "is_null",
+                    "is_not_null",
+                ],
+            },
+            value: {
+                description: "Comparison value. For `in`/`not_in` supply an array.",
+            },
+        },
+    },
+};
+const TOOLS = [
+    {
+        name: "ictrp_search",
+        description: "Search the WHO ICTRP by keyword and materialize the entire result set locally. " +
+            "This is the only expensive operation: it drives a full CSV export (tens of megabytes) " +
+            "and returns a page plus a set_id. Every later refinement works on that set without " +
+            "touching the network again. IMPORTANT: the returned count is rows retrieved, NOT the " +
+            "number of matching trials -- the export is known to omit records, so never present the " +
+            "count as a total and never treat absence from the result as evidence a trial does not exist.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                keyword: {
+                    type: "string",
+                    description: "Free-text query, e.g. 'pancreatic cancer', 'KRAS', 'IBI343'.",
+                },
+                limit: { type: "number", description: "Rows to return in this page. Default 25." },
+                offset: { type: "number", description: "Rows to skip. Default 0." },
+                refresh: {
+                    type: "boolean",
+                    description: "Ignore any cached export for this exact keyword and re-fetch. Default false.",
+                },
+            },
+            required: ["keyword"],
+        },
+    },
+    {
+        name: "ictrp_filter",
+        description: "Filter, sort and page a materialized set. No upstream request. " +
+            "Filter on normalized fields (phase_code, recruitment_status_normalized) rather than raw " +
+            "strings, because upstream vocabulary is inconsistent in case and wording.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                set_id: { type: "string" },
+                filters: FILTER_SCHEMA,
+                sort_by: { type: "string", description: "Field to sort by." },
+                descending: { type: "boolean", description: "Sort descending. Default false." },
+                limit: { type: "number", description: "Rows to return. Default 25." },
+                offset: { type: "number", description: "Rows to skip. Default 0." },
+            },
+            required: ["set_id"],
+        },
+    },
+    {
+        name: "ictrp_field_query",
+        description: "Distinct values for one field, with how many rows carry each, plus population coverage. " +
+            "Use this before filtering to learn the real vocabulary and whether a field is populated " +
+            "enough to be worth filtering on.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                set_id: { type: "string" },
+                field: { type: "string", description: "Field name." },
+                limit: { type: "number", description: "Maximum distinct values. Default 50." },
+            },
+            required: ["set_id", "field"],
+        },
+    },
+    {
+        name: "ictrp_registry_summary",
+        description: "Composition of a set by registry, phase, recruitment status, registration year and " +
+            "country, plus per-field population coverage. The fastest way to see what a set contains " +
+            "and which fields are too sparse to trust.",
+        inputSchema: {
+            type: "object",
+            properties: { set_id: { type: "string" } },
+            required: ["set_id"],
+        },
+    },
+    {
+        name: "ictrp_find_duplicates",
+        description: "Find the same trial registered in more than one registry, by cross-referencing " +
+            "identifiers. Useful before counting, since the same trial can appear several times.",
+        inputSchema: {
+            type: "object",
+            properties: { set_id: { type: "string" } },
+            required: ["set_id"],
+        },
+    },
+    {
+        name: "ictrp_export",
+        description: "Export a materialized set as csv, json, jsonl or markdown, with a provenance header " +
+            "recording the source and processing date that WHO's terms require.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                set_id: { type: "string" },
+                fmt: { type: "string", enum: ["csv", "json", "jsonl", "markdown"] },
+                filters: FILTER_SCHEMA,
+                fields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Fields to include. Defaults to a standard column set.",
+                },
+                destination: {
+                    type: "string",
+                    description: "File to write. When omitted the content is returned inline.",
+                },
+                include_provenance_header: {
+                    type: "boolean",
+                    description: "Prepend the WHO ICTRP source and processing-date header. Default true; " +
+                        "turn it off only when the consumer adds its own attribution.",
+                },
+            },
+            required: ["set_id"],
+        },
+    },
+    {
+        name: "ictrp_cache_status",
+        description: "List the cached result sets held by the running service, or purge them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["list", "purge"],
+                    description: "List held sets, or delete them. Default list.",
+                },
+                set_id: { type: "string", description: "With action=purge, remove only this set." },
+            },
+        },
+    },
+    {
+        name: "ictrp_snapshot",
+        description: "Write a materialized set to a JSON snapshot file for offline or bundled use, or " +
+            "materialize a keyword and snapshot it in one step.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                keyword: { type: "string", description: "Keyword to snapshot." },
+                set_id: { type: "string", description: "Snapshot an already-materialized set instead." },
+                path: { type: "string", description: "Output path. Defaults to ICTRP_BUNDLE_DIR." },
+                if_stale: {
+                    type: "boolean",
+                    description: "Re-materialize when the existing snapshot is stale. Default true.",
+                },
+            },
+        },
+    },
+    {
+        name: "ictrp_bundle_status",
+        description: "Report which offline snapshots are available and how old they are. Use before " +
+            "relying on a bundled answer, since WHO refreshes ICTRP weekly and a stale snapshot " +
+            "misrepresents the registry.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "ictrp_check_environment",
+        description: "Report whether this server can actually reach ICTRP: Python version, installed " +
+            "dependencies, sidecar status. Call this first when a search fails, to tell an " +
+            "environment problem from an upstream one.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+function asString(args, key, required = false) {
+    const raw = args[key];
+    if (raw === undefined || raw === null) {
+        if (required)
+            throw new InvalidArgs(`missing required argument: ${key}`);
+        return undefined;
+    }
+    if (typeof raw !== "string")
+        throw new InvalidArgs(`argument '${key}' must be a string`);
+    return raw;
+}
+function asNumber(args, key, fallback) {
+    const raw = args[key];
+    if (raw === undefined || raw === null)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new InvalidArgs(`argument '${key}' must be a number`);
+    return n;
+}
+function asBoolean(args, key, fallback) {
+    const raw = args[key];
+    if (raw === undefined || raw === null)
+        return fallback;
+    if (typeof raw === "boolean")
+        return raw;
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    throw new InvalidArgs(`argument '${key}' must be a boolean`);
+}
+function asFilters(args) {
+    const raw = args["filters"];
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new InvalidArgs("argument 'filters' must be an array");
+    return raw.map((item, index) => {
+        if (typeof item !== "object" || item === null || Array.isArray(item)) {
+            throw new InvalidArgs(`filters[${index}] must be an object`);
+        }
+        return item;
+    });
+}
+function asStringArray(args, key) {
+    const raw = args[key];
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!Array.isArray(raw))
+        throw new InvalidArgs(`argument '${key}' must be an array`);
+    return raw.map((v, i) => {
+        if (typeof v !== "string")
+            throw new InvalidArgs(`${key}[${i}] must be a string`);
+        return v;
+    });
+}
+class InvalidArgs extends Error {
+}
+/**
+ * Run a tool call.
+ *
+ * Environment-backed tools (`check_environment`) work without a sidecar. Every
+ * other tool calls `ensureSidecar` first, which starts the Python process on
+ * demand and returns a typed failure rather than throwing.
+ */
+async function dispatch(name, args) {
+    if (name === "ictrp_check_environment") {
+        const report = await getEnvReport(true);
+        const ping = await pingSidecar();
+        return {
+            ...report,
+            sidecar_health: ping.ok
+                ? ping.data
+                : { error_code: ping.code, message: ping.message, log_tail: sidecarLogTail().slice(-10) },
+        };
+    }
+    const ready = await ensureSidecar();
+    if (!ready.ok)
+        throw new SidecarFailure(ready);
+    switch (name) {
+        case "ictrp_search": {
+            const keyword = asString(args, "keyword", true);
+            if (!keyword.trim())
+                throw new InvalidArgs("keyword must not be empty");
+            return call({
+                endpoint: "/search",
+                params: {
+                    keyword,
+                    limit: asNumber(args, "limit", 25),
+                    offset: asNumber(args, "offset", 0),
+                    refresh: asBoolean(args, "refresh", false),
+                },
+                timeoutMs: SEARCH_TIMEOUT_MS,
+            });
+        }
+        case "ictrp_filter":
+            return call({
+                endpoint: "/filter",
+                params: {
+                    set_id: asString(args, "set_id", true),
+                    filters: asFilters(args),
+                    sort_by: asString(args, "sort_by") ?? null,
+                    descending: asBoolean(args, "descending", false),
+                    limit: asNumber(args, "limit", 25),
+                    offset: asNumber(args, "offset", 0),
+                },
+            });
+        case "ictrp_field_query":
+            return call({
+                endpoint: "/field-query",
+                params: {
+                    set_id: asString(args, "set_id", true),
+                    field: asString(args, "field", true),
+                    limit: asNumber(args, "limit", 50),
+                },
+            });
+        case "ictrp_registry_summary":
+            return call({
+                endpoint: "/registry-summary",
+                params: { set_id: asString(args, "set_id", true) },
+            });
+        case "ictrp_find_duplicates":
+            return call({
+                endpoint: "/find-duplicates",
+                params: { set_id: asString(args, "set_id", true) },
+            });
+        case "ictrp_export":
+            return call({
+                endpoint: "/export",
+                params: {
+                    set_id: asString(args, "set_id", true),
+                    fmt: asString(args, "fmt") ?? "csv",
+                    filters: asFilters(args),
+                    fields: asStringArray(args, "fields") ?? null,
+                    include_provenance_header: asBoolean(args, "include_provenance_header", true),
+                },
+            });
+        case "ictrp_cache_status":
+            return call({
+                endpoint: "/cache-status",
+                params: {
+                    action: asString(args, "action") ?? "list",
+                    set_id: asString(args, "set_id") ?? null,
+                },
+            });
+        case "ictrp_snapshot":
+            return call({
+                endpoint: "/snapshot",
+                params: {
+                    keyword: asString(args, "keyword") ?? null,
+                    set_id: asString(args, "set_id") ?? null,
+                    path: asString(args, "path") ?? null,
+                    if_stale: asBoolean(args, "if_stale", true),
+                },
+                timeoutMs: SEARCH_TIMEOUT_MS,
+            });
+        case "ictrp_bundle_status":
+            return call({ endpoint: "/bundle-status", params: {} });
+        default:
+            throw new InvalidArgs(`unknown tool: ${name}`);
+    }
+}
+class SidecarFailure extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+    }
+}
+/**
+ * Forward one call to the sidecar.
+ *
+ * A failed call becomes a thrown error, never a value. This is the same rule
+ * the Python side enforces and it matters for the same reason: a caller that
+ * receives `[]` cannot tell "no matches" from "the export failed".
+ */
+async function call(opts) {
+    const execOpts = {};
+    if (opts.timeoutMs !== undefined)
+        execOpts.timeoutMs = opts.timeoutMs;
+    const result = await callSidecar(opts.endpoint, opts.params, execOpts);
+    if (!result.ok)
+        throw new SidecarFailure(result);
+    const data = result.data;
+    // Attach the notices the service is obliged to surface, without overwriting
+    // anything the Python layer already set.
+    if (data["ok"] !== false) {
+        data["incompleteness_notice"] ??= INCOMPLETENESS_NOTICE;
+        data["attribution_notice"] ??= ATTRIBUTION_NOTICE;
+    }
+    return data;
+}
+function textResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+function errorResult(code, message, hint) {
+    const payload = { status: "error", error_code: code, message };
+    if (hint)
+        payload["hint"] = hint;
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        isError: true,
+    };
+}
+async function main() {
+    installShutdownHooks();
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        try {
+            return textResult(await dispatch(name, args));
+        }
+        catch (err) {
+            if (err instanceof InvalidArgs) {
+                return errorResult("INVALID_ARGUMENT", err.message);
+            }
+            if (err instanceof SidecarFailure) {
+                return errorResult(err.failure.code, err.failure.message, err.failure.hint);
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            // Any other throw is a bug here, not an upstream condition. Saying so
+            // stops the caller from retrying something that will never work.
+            return errorResult("INTERNAL_ERROR", message, "This is a bug in the MCP server, not an upstream failure.");
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Fire-and-forget, stderr only, fully swallowed: a boot-time probe must
+    // never delay the handshake or pollute stdout.
+    void getEnvReport()
+        .then((report) => {
+        process.stderr.write(`[${SERVER_NAME}] ${report.summary}\n`);
+        if (!report.ready) {
+            for (const action of report.actions)
+                process.stderr.write(`  - ${action}\n`);
+        }
+    })
+        .catch(() => { });
+}
+main().catch((err) => {
+    process.stderr.write(`[${SERVER_NAME}] fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exit(1);
+});
+export { toErrorText };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/runtime/bootstrap.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Runtime self-setup: create the private venv and install the vendored package.
+ *
+ * This exists because **a packaged desktop application does not run npm's
+ * `postinstall`**. A dmg or an exe is a copied directory tree; npm lifecycle
+ * scripts ran on the developer's machine, not on the user's. Anything the
+ * package needs at runtime must therefore be able to set itself up on first
+ * use, at runtime, with visible progress and a definite failure mode.
+ *
+ * Two rules govern the whole module:
+ *
+ * 1. **Never roll back a completed step.** Steps are ordered cheapest-first
+ *    (venv, then dependencies, then anything large). Re-running is meant to
+ *    resume, so a failure late in the sequence does not throw away work that
+ *    succeeded earlier.
+ *
+ * 2. **A step that did not run is not a step that failed.** `skipped` is
+ *    reported as its own outcome so the operator can tell "already fine" from
+ *    "we installed it just now" from "we tried and it broke".
+ */
+export interface ProgressEvent {
+    step: string;
+    message: string;
+    percent?: number;
+}
+export type StepOutcome = "ok" | "skipped" | "failed";
+export interface StepResult {
+    step: string;
+    outcome: StepOutcome;
+    message: string;
+    attempts: number;
+    /** Mirrors actually tried, in order. Only present for install steps. */
+    triedMirrors?: string[];
+}
+export interface BootstrapResult {
+    ok: boolean;
+    steps: StepResult[];
+    /** Non-empty when the run did not fully succeed. */
+    errors: string[];
+}
+export type ProgressFn = (event: ProgressEvent) => void;
+/**
+ * PyPI mirrors, most-likely-to-work first for the users this ships to.
+ *
+ * The fallback chain is not a nicety. A mirror can fail in a way that looks
+ * exactly like "this package does not exist" -- notably a 403 on a modern pip
+ * user-agent surfaces as `from versions: none`, which sends the operator
+ * hunting for a typo instead of a mirror problem. Trying the next mirror turns
+ * that misdiagnosis into a non-event.
+ */
+export declare const PYPI_MIRRORS: Record<string, string>;
+/**
+ * Build the mirror order: the preferred mirror first, then everything else
+ * except the official index, then the official index last as the backstop.
+ *
+ * `official` is pinned last on purpose. It is the most correct source and the
+ * slowest / most-blocked from the networks this is expected to run on, so it
+ * is the fallback rather than the default.
+ */
+export declare function mirrorChain(preferred?: string): Array<{
+    name: string;
+    url: string;
+}>;
+interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Run a child process, streaming its output to `onLine`.
+ *
+ * Exit codes follow the convention the installer relies on:
+ *   124 -- the step timed out and was killed
+ *   130 -- the run was aborted by the caller
+ *   127 -- the executable could not be spawned at all
+ */
+export declare function execStreaming(cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onLine?: (line: string) => void;
+}): Promise<ExecResult>;
+/** Find a usable system Python, newest acceptable version first. */
+export declare function discoverPython(): Promise<{
+    cmd: string;
+    version: string;
+} | undefined>;
+/**
+ * Bring the environment to a usable state.
+ *
+ * Returns rather than throws: the caller (`setup` CLI, or the MCP layer's
+ * lazy bootstrap) needs the step list to report *what* went wrong.
+ */
+export declare function bootstrapEnvironment(opts?: {
+    mirror?: string;
+    onProgress?: ProgressFn;
+    signal?: AbortSignal;
+}): Promise<BootstrapResult>;
+export {};