fhirhydrant 0.1.0

package/.out/server.js

@@ -0,0 +1,457 @@
+#!/usr/bin/env node
+
+// ts/server.ts
+import { readFileSync as readFileSync2, watch } from "fs";
+import { basename, dirname as dirname2, join as join2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
+
+// ts/config.ts
+var get = (key) => {
+  const val = process.env[key];
+  if (!val) throw new Error(`Missing required env var: ${key}`);
+  return val;
+};
+var opt = (key) => process.env[key];
+var parseTransport = () => {
+  const val = (opt("MCP_TRANSPORT") ?? "http").toLowerCase();
+  if (val !== "http" && val !== "stdio")
+    throw new Error(
+      `Invalid MCP_TRANSPORT="${val}" \u2014 must be "http" or "stdio"`
+    );
+  return val;
+};
+var parsePort = () => {
+  const raw = opt("PORT") ?? "5000", port = parseInt(raw, 10);
+  if (!Number.isFinite(port) || port < 1 || port > 65535)
+    throw new Error(`Invalid PORT="${raw}" \u2014 must be 1\u201365535`);
+  return port;
+};
+var parseAllowedHosts = () => opt("ALLOWED_HOSTS")?.split(",").map((s) => s.trim()).filter(Boolean) || void 0;
+var config = {
+  fhirBaseUrl: get("FHIR_BASE_URL").replace(/\/$/, ""),
+  get fhirServerUrl() {
+    return opt("FHIR_SERVER_URL") ?? `${this.fhirBaseUrl}/api/FHIR/R4`;
+  },
+  get fhirTokenEndpoint() {
+    return opt("FHIR_TOKEN_URL") ?? `${this.fhirBaseUrl}/oauth2/token`;
+  },
+  fhirClientId: get("FHIR_CLIENT_ID"),
+  fhirPrivateKey: get("FHIR_PRIVATE_KEY"),
+  fhirJwksUrl: opt("FHIR_JWKS_URL"),
+  fhirKeyId: opt("FHIR_KEY_ID"),
+  port: parsePort(),
+  bindHost: opt("BIND_HOST") ?? "127.0.0.1",
+  allowedHosts: parseAllowedHosts(),
+  transport: parseTransport(),
+  debug: opt("DEBUG")?.toLowerCase() === "true"
+};
+
+// ts/fhir/auth.ts
+import FHIRStarter from "fhirstarterjs";
+
+// ts/fhir/definitions.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import * as z from "zod";
+
+// ts/fhir/validate-definitions.ts
+var text = (value) => typeof value === "string" && value.trim() ? value.trim() : void 0;
+var validateDefinitions = (raw) => {
+  const errors = [];
+  if (!Array.isArray(raw))
+    return errors.push("definitions.json must be a JSON array"), { entries: [], errors };
+  const seen = /* @__PURE__ */ new Set(), entries = [];
+  for (const value of raw) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      errors.push("definitions.json entries must be objects");
+      continue;
+    }
+    const entry = value, searchParams = entry["searchParams"];
+    if (searchParams !== void 0 && (!searchParams || typeof searchParams !== "object" || Array.isArray(searchParams))) {
+      errors.push(
+        `Invalid entry for resourceType "${text(entry["resourceType"]) ?? "(missing)"}": searchParams must be an object when provided`
+      );
+      continue;
+    }
+    const rt = text(entry["resourceType"]), name = text(entry["toolName"]), desc = text(entry["description"]);
+    if (!rt || !name || !desc || typeof entry.supportsDirectRead !== "boolean") {
+      errors.push(
+        `Invalid entry for resourceType "${rt ?? "(missing)"}": requires resourceType, toolName, description (non-empty strings) and supportsDirectRead (boolean)`
+      );
+      continue;
+    }
+    if (seen.has(name)) {
+      errors.push(`Duplicate toolName "${name}"`);
+      continue;
+    }
+    seen.add(name);
+    const params = searchParams ?? {};
+    for (const [key, val] of Object.entries(params))
+      if (typeof key !== "string" || typeof val !== "string")
+        errors.push(`"${name}": searchParams keys and values must be strings (got key="${key}")`);
+    if (!entry.supportsDirectRead && Object.keys(params).length === 0) {
+      errors.push(`"${name}" has no searchParams and supportsDirectRead is false`);
+      continue;
+    }
+    const rawRequire = entry["requireOneOf"], requireOneOf = Array.isArray(rawRequire) && rawRequire.length > 0 && rawRequire.every((v) => typeof v === "string" && v.trim()) ? rawRequire : void 0;
+    if (rawRequire !== void 0 && !requireOneOf)
+      errors.push(`"${name}": requireOneOf must be a non-empty array of strings when provided`);
+    if (requireOneOf) {
+      const paramKeys = new Set(Object.keys(params));
+      for (const key of requireOneOf)
+        if (!paramKeys.has(key))
+          errors.push(`"${name}": requireOneOf key "${key}" is not in searchParams`);
+    }
+    entries.push({
+      resourceType: rt,
+      toolName: name,
+      description: desc,
+      supportsDirectRead: entry["supportsDirectRead"],
+      searchParams: Object.keys(params).length > 0 ? params : void 0,
+      requireOneOf
+    });
+  }
+  return { entries, errors };
+};
+
+// ts/fhir/definitions.ts
+var packaged = join(dirname(fileURLToPath(import.meta.url)), "../..", "definitions.json");
+var getDefinitionsPath = () => {
+  const cwd = join(process.cwd(), "definitions.json");
+  return existsSync(cwd) ? cwd : packaged;
+};
+var parse = () => {
+  const raw = JSON.parse(
+    readFileSync(getDefinitionsPath(), "utf8")
+  ), result = validateDefinitions(raw);
+  if (result.errors.length > 0)
+    throw new Error(`definitions.json: ${result.errors.join("; ")}`);
+  const seen = /* @__PURE__ */ new Set(), definitions = result.entries.map((entry) => {
+    if (seen.has(entry.toolName))
+      throw new Error(
+        `definitions.json: duplicate toolName "${entry.toolName}"`
+      );
+    seen.add(entry.toolName);
+    const params = entry.searchParams ?? {}, shape = Object.fromEntries(
+      Object.entries(params).map(([key, desc]) => [
+        key,
+        z.string().optional().describe(desc)
+      ])
+    );
+    if (entry.supportsDirectRead && !shape["_id"]) {
+      shape["_id"] = z.string().optional().describe(
+        `${entry.resourceType} resource ID \u2014 performs direct read when provided alone`
+      );
+      console.warn(
+        `[definitions] "${entry.toolName}": auto-injected _id for supportsDirectRead`
+      );
+    }
+    const schema = z.object(shape);
+    return {
+      resourceType: entry.resourceType,
+      toolName: entry.toolName,
+      description: entry.description,
+      supportsDirectRead: entry.supportsDirectRead,
+      requireOneOf: entry.requireOneOf,
+      searchSchema: schema
+    };
+  }), scopes = definitions.map(
+    (d) => d.supportsDirectRead ? `system/${d.resourceType}.rs` : `system/${d.resourceType}.s`
+  );
+  return { definitions, scopes };
+};
+var snapshot = parse();
+var getDefinitions = () => snapshot.definitions;
+var getScopes = () => snapshot.scopes;
+var reloadDefinitions = () => {
+  try {
+    snapshot = parse();
+    return true;
+  } catch (err) {
+    console.error(
+      "[definitions] Reload failed \u2014 keeping last valid snapshot:",
+      err instanceof Error ? err.message : err
+    );
+    return false;
+  }
+};
+
+// ts/fhir/auth.ts
+var starter;
+var startAuth = async () => {
+  starter = new FHIRStarter({
+    clientId: config.fhirClientId,
+    privateKey: config.fhirPrivateKey,
+    tokenEndpointUrl: config.fhirTokenEndpoint,
+    scopes: getScopes(),
+    ...config.fhirJwksUrl && { jwksUrl: config.fhirJwksUrl },
+    ...config.fhirKeyId && { keyId: config.fhirKeyId }
+  });
+  await starter.start();
+};
+var stopAuth = () => {
+  starter?.stop();
+};
+var restartAuth = async () => {
+  stopAuth();
+  await startAuth();
+};
+var getTokenResponse = () => starter.tokenResponse();
+
+// ts/fhir/registry.ts
+import { z as z2 } from "zod";
+
+// ts/fhir/client.ts
+import FHIR from "fhirclient";
+var smart = FHIR({});
+var createFhirClient = () => smart.client({
+  serverUrl: config.fhirServerUrl,
+  tokenResponse: getTokenResponse()
+});
+
+// ts/fhir/registry.ts
+var retryable = (err) => {
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    return msg.includes("econnreset") || msg.includes("epipe") || msg.includes("etimedout") || msg.includes("socket hang up") || msg.includes("forcibly closed") || msg.includes("network") || msg.includes("fetch failed");
+  }
+  return false;
+};
+var withRetry = async (label, fn, attempts = 3) => {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (i + 1 >= attempts || !retryable(err)) throw err;
+      const delay = 1e3 * 2 ** i;
+      console.warn(`[fhir] ${label} transient error, retrying in ${delay}ms (${i + 1}/${attempts})`);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+  throw new Error("unreachable");
+};
+var buildSearchUrl = (resourceType, args) => {
+  const params = new URLSearchParams();
+  for (const [key, val] of Object.entries(args))
+    val !== void 0 && val !== "" && params.append(key, String(val));
+  const qs = params.toString();
+  return qs ? `${resourceType}?${qs}` : resourceType;
+};
+var isDirectRead = (args, supportsDirectRead) => {
+  if (!supportsDirectRead) return void 0;
+  const id = typeof args["_id"] === "string" && args["_id"] ? args["_id"] : void 0;
+  if (!id) return void 0;
+  const otherKeys = Object.entries(args).some(
+    ([k, v]) => k !== "_id" && v !== void 0 && v !== ""
+  );
+  return otherKeys ? void 0 : id;
+};
+var makeHandler = (def) => async (args) => {
+  const directId = isDirectRead(args, def.supportsDirectRead);
+  if (!directId && def.requireOneOf) {
+    const ok = def.requireOneOf.some((k) => {
+      const v = args[k];
+      return typeof v === "string" && v !== "";
+    });
+    if (!ok)
+      return {
+        content: [{ type: "text", text: `Search requires at least one of: ${def.requireOneOf.join(", ")}` }],
+        isError: true
+      };
+  }
+  try {
+    const client = createFhirClient(), url = directId ? `${def.resourceType}/${directId}` : buildSearchUrl(def.resourceType, args), op = directId ? "read" : "search";
+    config.debug ? console.log(`[fhir] ${def.resourceType} ${op} \u2192 ${url}`) : console.log(`[fhir] ${def.resourceType} ${op}`);
+    const result = await withRetry(`${def.resourceType} ${op}`, () => client.request(url)), summary = result && typeof result === "object" && result.resourceType === "Bundle" ? `Bundle total=${result.total ?? "?"}` : result?.resourceType ?? "ok";
+    console.log(`[fhir] ${def.resourceType} OK ${summary}`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }
+      ]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[fhir] ${def.resourceType} ERR ${message}`);
+    return {
+      content: [{ type: "text", text: message }],
+      isError: true
+    };
+  }
+};
+var registerAll = (server) => {
+  for (const def of getDefinitions())
+    server.registerTool(
+      def.toolName,
+      { description: def.description, inputSchema: def.searchSchema },
+      makeHandler(def)
+    );
+};
+var validatePageUrl = (url) => {
+  const baseHref = config.fhirServerUrl.replace(/\/?$/, "/"), serverUrl = new URL(baseHref), nextUrl = new URL(url, baseHref);
+  if (nextUrl.origin !== serverUrl.origin)
+    throw new Error(
+      `Pagination URL origin "${nextUrl.origin}" does not match FHIR server origin "${serverUrl.origin}"`
+    );
+  if (!nextUrl.pathname.startsWith(serverUrl.pathname))
+    throw new Error(
+      `Pagination URL path "${nextUrl.pathname}" is outside FHIR server base path "${serverUrl.pathname}"`
+    );
+  return nextUrl.toString();
+};
+var registerCoreTools = (server) => {
+  server.registerTool(
+    "fhir_fetch_page",
+    {
+      description: `Fetch a single page of FHIR Bundle results using a pagination URL. The url must come from a FHIR Bundle's link array where relation is "next". Do not construct pagination URLs manually \u2014 only use links returned by the FHIR server.`,
+      inputSchema: z2.object({
+        url: z2.string().describe(
+          "Pagination URL from a FHIR Bundle link[rel=next].url value"
+        )
+      })
+    },
+    async (args) => {
+      try {
+        const validatedUrl = validatePageUrl(args.url), client = createFhirClient();
+        config.debug ? console.log(`[fhir] fetch_page \u2192 ${validatedUrl}`) : console.log("[fhir] fetch_page");
+        const result = await withRetry("fetch_page", () => client.request(validatedUrl)), summary = result && typeof result === "object" && result.resourceType === "Bundle" ? `Bundle total=${result.total ?? "?"}` : "ok";
+        console.log(`[fhir] fetch_page OK ${summary}`);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[fhir] fetch_page ERR ${message}`);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${message}
+
+Retry with the same url to resume from this page.`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+};
+
+// ts/server.ts
+var { version: pkgVersion } = JSON.parse(
+  readFileSync2(join2(dirname2(fileURLToPath2(import.meta.url)), "..", "package.json"), "utf8")
+);
+var SERVER_INFO = { name: "fhirhydrant", version: pkgVersion };
+var SERVER_INSTRUCTIONS = readFileSync2(
+  join2(dirname2(fileURLToPath2(import.meta.url)), "..", "instructions.md"),
+  "utf8"
+).trim();
+var makeServer = () => {
+  const s = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
+  registerAll(s);
+  registerCoreTools(s);
+  return s;
+};
+var restartingAuth = false;
+var startDefinitionsWatcher = () => {
+  const defPath = getDefinitionsPath(), watchDir = dirname2(defPath), watchFile = basename(defPath);
+  let debounce;
+  watch(watchDir, (_eventType, filename) => {
+    if (filename !== watchFile) return;
+    clearTimeout(debounce);
+    debounce = setTimeout(async () => {
+      const prevScopes = getScopes().join(","), ok = reloadDefinitions();
+      if (!ok) return;
+      console.log(`[definitions] Reloaded from ${watchFile}`);
+      if (getScopes().join(",") !== prevScopes) {
+        if (restartingAuth)
+          return void console.log(
+            "[definitions] Auth restart already in progress \u2014 skipping"
+          );
+        restartingAuth = true;
+        try {
+          console.log(
+            "[definitions] Scopes changed \u2014 restarting auth..."
+          );
+          await restartAuth();
+          console.log("[definitions] Auth restarted with new scopes");
+        } catch (err) {
+          console.error(
+            "[definitions] Auth restart failed:",
+            err instanceof Error ? err.message : err
+          );
+        } finally {
+          restartingAuth = false;
+        }
+      }
+    }, 300);
+  });
+  console.log(`[definitions] Watching ${watchFile} for changes`);
+};
+var startHttp = async () => {
+  const { createMcpExpressApp } = await import("@modelcontextprotocol/express"), { NodeStreamableHTTPServerTransport } = await import("@modelcontextprotocol/node"), app = createMcpExpressApp(
+    config.allowedHosts ? { allowedHosts: config.allowedHosts } : void 0
+  ), server = makeServer(), transport = new NodeStreamableHTTPServerTransport({
+    sessionIdGenerator: void 0
+  });
+  await server.connect(transport);
+  app.get("/health", (_req, res) => res.json({ status: "ok" }));
+  app.all("/mcp", async (req, res) => {
+    const body = req.body, method = body?.method ?? req.method;
+    method && console.log(`[mcp] ${method}`);
+    await transport.handleRequest(req, res, req.body);
+  });
+  app.use((err, _req, res, _next) => {
+    console.error("[http] Request error:", err.message);
+    res.status(400).json({
+      jsonrpc: "2.0",
+      error: { code: -32700, message: "Parse error" },
+      id: null
+    });
+  });
+  const httpServer = app.listen(
+    config.port,
+    config.bindHost,
+    () => console.log(`fhirhydrant listening on ${config.bindHost}:${config.port}`)
+  );
+  return () => new Promise((resolve) => {
+    void transport.close();
+    void server.close();
+    httpServer.close(() => resolve());
+    setTimeout(() => resolve(), 5e3);
+  });
+};
+var startStdio = async () => {
+  console.log = (...args) => console.error(...args);
+  const server = makeServer(), transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.log("fhirhydrant running in stdio mode");
+  return async () => {
+    await transport.close();
+    await server.close();
+  };
+};
+await startAuth();
+var close = config.transport === "stdio" ? await startStdio() : await startHttp();
+process.env["NODE_ENV"] !== "production" && startDefinitionsWatcher();
+var shutdownInProgress = false;
+var shutdown = async (code = 0) => {
+  if (shutdownInProgress) return;
+  shutdownInProgress = true;
+  console.log("Shutting down...");
+  stopAuth();
+  await close();
+  process.exit(code);
+};
+process.on("SIGINT", () => void shutdown(0));
+process.on("SIGTERM", () => void shutdown(0));

package/LICENSE.md

@@ -0,0 +1,21 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
+software, either in source code form or as a compiled binary, for any purpose,
+commercial or non-commercial, and by any means.
+
+In jurisdictions that recognize copyright laws, the author or authors of this
+software dedicate any and all copyright interest in the software to the public
+domain. We make this dedication for the benefit of the public at large and to
+the detriment of our heirs and successors. We intend this dedication to be an
+overt act of relinquishment in perpetuity of all present and future rights to
+this software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,271 @@
+# fhirHydrant
+
+An MCP server for connecting AI clients to FHIR APIs.
+
+Authenticates via SMART Backend Services, exposes configurable resource tools
+with FHIR Bundle pagination, and supports both Streamable HTTP and stdio
+transports.
+
+## Requirements
+
+- Node.js ≥ 24
+- A FHIR R4 server with SMART Backend Services (client credentials) support
+- An RSA-2048 private key and a publicly hosted JWKS
+
+## Install
+
+### npm / npx (recommended)
+
+```sh
+npm install -g fhirhydrant
+# or run directly:
+npx fhirhydrant
+```
+
+### From source
+
+```sh
+git clone https://github.com/faulkj/fhirhydrant.git
+cd fhirhydrant
+npm install
+npm run build
+```
+
+### Docker
+
+```sh
+docker build -t fhirhydrant .
+docker run \
+   -v /host/path/key.pem:/run/secrets/fhir-key.pem:ro \
+   -e FHIR_BASE_URL=https://fhir.example.org \
+   -e FHIR_CLIENT_ID=your-client-id \
+   -e FHIR_PRIVATE_KEY=/run/secrets/fhir-key.pem \
+   -p 5000:5000 \
+   fhirhydrant
+```
+
+> **Docker key mounting:** `FHIR_PRIVATE_KEY=./private.pem` will not resolve
+> inside the container. Mount the key file and use the container path as shown.
+
+## Setup
+
+Generate a private key if you don't have one:
+
+```sh
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
+```
+
+Host the corresponding public JWKS somewhere reachable by your FHIR auth server
+(e.g. a GitHub Gist), and register it along with your `FHIR_CLIENT_ID`.
+
+**From source:** copy `.env.example` to `.env` and fill in your values — `npm run dev` loads it automatically.
+
+**npm / npx (HTTP mode):** set env vars in your shell or process manager before running.
+
+**stdio mode:** pass env vars via the MCP client config's `env` block (see [Stdio](#stdio) below).
+
+## Environment
+
+See [.env.example](.env.example) for all variables.
+
+### Required
+
+| Variable           | Description                                                                 |
+| ------------------ | --------------------------------------------------------------------------- |
+| `FHIR_BASE_URL`    | FHIR server base — `/api/FHIR/R4` and `/oauth2/token` are derived from this |
+| `FHIR_CLIENT_ID`   | Client ID registered with your FHIR auth server                             |
+| `FHIR_PRIVATE_KEY` | Path to your RSA private key PEM file (relative to cwd or absolute)         |
+
+### Commonly required
+
+| Variable        | Description                                           |
+| --------------- | ----------------------------------------------------- |
+| `FHIR_JWKS_URL` | Public JWKS URL registered with your FHIR auth server |
+| `FHIR_KEY_ID`   | `kid` value in your JWKS matching the private key     |
+
+### Optional
+
+| Variable                  | Default               | Description                                                       |
+| ------------------------- | --------------------- | ----------------------------------------------------------------- |
+| `FHIR_SERVER_URL`         | `<base>/api/FHIR/R4`  | Override the derived FHIR API URL for non-standard server layouts |
+| `FHIR_TOKEN_URL`          | `<base>/oauth2/token` | Override the derived token endpoint URL                           |
+| `MCP_TRANSPORT`           | `http`                | `http` for Streamable HTTP, `stdio` for stdio                     |
+| `PORT`                    | `5000`                | HTTP listener port (1–65535)                                      |
+| `BIND_HOST`               | `127.0.0.1`           | Bind address for HTTP listener — set to `0.0.0.0` for container/LAN access |
+| `ALLOWED_HOSTS`           | —                     | Comma-separated hostnames for DNS rebinding protection            |
+| `DEBUG`                   | `false`               | Enable verbose FHIR request logging (**may log PHI** — see below) |
+
+When both a derived URL and an explicit override are available, the explicit
+override takes precedence.
+
+## Definitions
+
+fhirHydrant uses a `definitions.json` file to map FHIR resource types to MCP
+tools. The resolution order is:
+
+1. `./definitions.json` in the current working directory (if it exists)
+2. Packaged default definitions
+
+Edit `definitions.json` directly when customizing resources.
+
+### Definitions schema
+
+| Field                | Type                     | Description                                                                                     |
+| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `resourceType`       | `string`                 | FHIR resource type (e.g. `AllergyIntolerance`)                                                  |
+| `toolName`           | `string`                 | MCP tool name — must be unique across all entries                                               |
+| `description`        | `string`                 | Human-readable tool description shown to the AI client                                          |
+| `supportsDirectRead` | `boolean`                | Enable `/ResourceType/{id}` reads when `_id` is provided alone                                  |
+| `searchParams`       | `Record<string, string>` | Key = FHIR search param, value = parameter description (optional if supportsDirectRead is true) |
+| `requireOneOf`       | `string[]` (optional)    | At least one of these search params must be provided for non-direct-read calls |
+
+### Direct read behavior
+
+When `supportsDirectRead` is `true` and the caller supplies `_id` as the
+**only** non-empty argument, fhirHydrant performs a direct
+`GET /ResourceType/{id}` read instead of a search. If `_id` is combined with
+other parameters, a search is performed so intent is not silently discarded.
+
+If `supportsDirectRead` is `true` but `_id` is not listed in `searchParams`, it
+is auto-injected into the tool's input schema.
+
+### Hot-reload (dev mode)
+
+In development (`NODE_ENV` is not `production`), fhirHydrant watches the active
+definitions file for changes:
+
+- Invalid JSON keeps the last valid snapshot
+- When scopes change, auth restarts automatically
+- New tools are available on the next MCP request
+
+In production, definitions are read once at startup.
+
+### Safe onboarding checklist
+
+1. Update `definitions.json` with your resources
+2. Confirm generated SMART scopes match your intended access
+3. Update/re-register your backend client with the FHIR authorization server if
+   required scopes changed
+4. Test with least-privilege access
+5. Deploy
+
+### Limitations
+
+- All `searchParams` values are string-only — no type enforcement or enums
+- `requireOneOf` enforces "at least one of" — it does not cover complex
+  conditional requirements or exact-one-of constraints
+- No full FHIR capability negotiation — `searchParams` are tool input hints, not
+  a FHIR capability model
+- Vendor-specific search rules may still apply
+
+## Transport
+
+### HTTP (default)
+
+Stateless Streamable HTTP — no session management required.
+
+```
+POST http://localhost:5000/mcp
+Accept: application/json, text/event-stream
+Content-Type: application/json
+```
+
+MCP client config:
+
+```json
+{
+   "mcpServers": {
+      "fhirhydrant": {
+         "url": "http://localhost:5000/mcp"
+      }
+   }
+}
+```
+
+### Stdio
+
+Set `MCP_TRANSPORT=stdio` to use stdio transport. In stdio mode, stdout is
+reserved for the MCP protocol — all logging is redirected to stderr.
+
+MCP client config:
+
+```json
+{
+   "mcpServers": {
+      "fhirhydrant": {
+         "command": "npx",
+         "args": ["fhirhydrant"],
+         "env": {
+            "MCP_TRANSPORT": "stdio",
+            "FHIR_BASE_URL": "https://fhir.example.org",
+            "FHIR_CLIENT_ID": "your-client-id",
+            "FHIR_PRIVATE_KEY": "/path/to/private-1.pem",
+            "FHIR_JWKS_URL": "https://example.org/.well-known/jwks.json",
+            "FHIR_KEY_ID": "key-1"
+         }
+      }
+   }
+}
+```
+
+Prefer stdio for local desktop clients, HTTP for remote/networked clients.
+
+## Tools
+
+### Resource tools
+
+Defined in [definitions.json](definitions.json). The default set:
+
+| Tool          | Resource    | Direct read |
+| ------------- | ----------- | ----------- |
+| `patient`     | Patient     | Yes         |
+| `observation` | Observation | Yes         |
+| `condition`   | Condition   | Yes         |
+| `encounter`   | Encounter   | Yes         |
+
+### Built-in tools
+
+| Tool              | Description                                                       |
+| ----------------- | ----------------------------------------------------------------- |
+| `fhir_fetch_page` | Fetch a single page of FHIR Bundle results using a pagination URL |
+
+Search results are FHIR Bundles that may include pagination links. When a Bundle
+contains a `link` with `relation: "next"`, call `fhir_fetch_page` with that
+link's `url` to fetch the next page. Repeat until no `next` link is present.
+
+## Dev
+
+```sh
+npm run dev
+```
+
+Watches `ts/server.ts` with native Node TS stripping. Edits to the active
+definitions file are picked up live without restart; if scopes change, auth
+restarts automatically.
+
+## Build & run
+
+```sh
+npm run build
+npm start
+```
+
+Output goes to `.out/server.js`.
+
+## Security notes
+
+- **TLS:** Use a reverse proxy (nginx, Caddy) to terminate TLS for HTTP mode
+- **ALLOWED_HOSTS:** Set this when exposing HTTP mode on a public network
+- **Private keys:** Keep keys outside the package/project repo — `.gitignore`
+  already excludes `*.pem` and `*.key`
+- **PHI in logs:** Default logging does not include FHIR query parameters.
+  Setting `DEBUG=true` enables verbose URLs which **may contain
+  PHI** (patient names, identifiers, dates). Treat all logs as PHI-sensitive in
+  production environments.
+- **Pagination URL validation:** The `fhir_fetch_page` tool validates that URLs
+   match the configured FHIR server origin before fetching.
+- **PHI in tool responses:** FHIR resource data returned through MCP tool calls
+  contains PHI. Ensure your MCP client’s transcript storage and retention
+  policies meet your compliance requirements.
+- **Health endpoint:** `GET /health` returns `{"status":"ok"}` for liveness
+  probes. No authentication, no PHI.

package/definitions.json

@@ -0,0 +1,59 @@
+[
+   {
+      "resourceType": "Patient",
+      "toolName": "patient",
+      "description": "Search for or read a FHIR Patient resource. For direct read, provide _id alone. For search, many FHIR servers require one of these minimum data sets: (1) identifier (MRN or FHIR ID), (2) given + family + birthdate, or (3) given + family + legal-sex + telecom. Searching by name alone may not be sufficient.",
+      "supportsDirectRead": true,
+      "searchParams": {
+         "_id": "Patient resource ID — performs direct read when provided alone",
+         "family": "Family (last) name",
+         "given": "Given (first) name",
+         "birthdate": "Date of birth in YYYY-MM-DD format",
+         "identifier": "Business identifier in system|value format"
+      }
+   },
+   {
+      "resourceType": "Observation",
+      "toolName": "observation",
+      "description": "Search for or read a FHIR Observation resource. For direct read, provide _id alone. For search, patient is required. Optionally filter by category (e.g. laboratory, vital-signs, core-characteristics) and/or code (LOINC). Use category=core-characteristics with code 76516-4 (gestational age) or 8339-4 (birth weight) for core characteristic lookups.",
+      "supportsDirectRead": true,
+      "searchParams": {
+         "_id": "Observation resource ID — performs direct read when provided alone",
+         "patient": "Patient resource ID or reference — required for search",
+         "category": "Observation category (e.g. laboratory, vital-signs, core-characteristics)",
+         "code": "LOINC or other observation code",
+         "date": "Date or date range (e.g. ge2024-01-01)",
+         "status": "Observation status (e.g. final, preliminary)"
+      },
+      "requireOneOf": ["patient"]
+   },
+   {
+      "resourceType": "Condition",
+      "toolName": "condition",
+      "description": "Search for or read a FHIR Condition resource covering both problem list items and encounter diagnoses. For direct read, provide _id alone. For search, provide patient or encounter (at least one required). Use category=problem-list-item for the patient's problem list (clinical-status: active, resolved, inactive) or category=encounter-diagnosis for diagnoses documented during encounters. Omitting category returns both types.",
+      "supportsDirectRead": true,
+      "searchParams": {
+         "_id": "Condition resource ID — performs direct read when provided alone",
+         "patient": "Patient resource ID or reference — required unless encounter is provided",
+         "encounter": "Encounter resource ID — use instead of patient to get diagnoses for a specific encounter",
+         "category": "problem-list-item for problem list entries, encounter-diagnosis for encounter diagnoses; omit for both",
+         "code": "Condition code (ICD-10, SNOMED, etc.)",
+         "clinical-status": "Clinical status: active, resolved, or inactive"
+      },
+      "requireOneOf": ["patient", "encounter"]
+   },
+   {
+      "resourceType": "Encounter",
+      "toolName": "encounter",
+      "description": "Search for or read a FHIR Encounter resource. Provide an _id for direct read, or search by patient, status, class, or date.",
+      "supportsDirectRead": true,
+      "searchParams": {
+         "_id": "Encounter resource ID — performs direct read when provided alone",
+         "patient": "Patient resource ID or reference",
+         "status": "Encounter status (e.g. finished, in-progress, planned)",
+         "class": "Encounter class (e.g. AMB, IMP, EMER)",
+         "date": "Encounter date or date range (e.g. ge2024-01-01)"
+      },
+      "requireOneOf": ["patient"]
+   }
+]

package/instructions.md

@@ -0,0 +1,23 @@
+# fhirHydrant
+
+fhirHydrant's tools expose FHIR R4 endpoints over MCP.
+
+Use these tools to search for or read clinical resources from the configured
+FHIR server.
+
+Prefer search first when the user describes a patient, encounter, condition,
+observation, or other clinical concept without a known FHIR resource ID. Use
+search results to identify the relevant resource IDs, then use those IDs for
+direct reads when a tool supports `_id`.
+
+Each tool maps to one FHIR resource type from `definitions.json`. Use `_id` for
+direct reads when supported, or provide search parameters for FHIR search.
+
+Tool results are returned as raw FHIR JSON and may include Bundles for searches
+or resources for direct reads.
+
+Search results are FHIR Bundles that may contain a `link` array. If a `link`
+entry has `relation: "next"`, more results are available. Call `fhir_fetch_page`
+with that entry's `url` to fetch the next page. Repeat until no `next` link is
+present. Never construct pagination URLs manually — only use URLs returned by
+the FHIR server.

package/package.json

@@ -0,0 +1,71 @@
+{
+   "name": "fhirhydrant",
+   "version": "0.1.0",
+   "description": "An MCP server for connecting AI clients to FHIR APIs.",
+   "author": "Joshua Faulkenberry <j@joshuafaulkenberry.com> (https://joshuafaulkenberry.com/)",
+   "license": "Unlicense",
+   "type": "module",
+   "bin": {
+      "fhirhydrant": "./.out/server.js"
+   },
+   "repository": {
+      "type": "git",
+      "url": "git+https://github.com/faulkj/fhirhydrant.git"
+   },
+   "bugs": {
+      "url": "https://github.com/faulkj/fhirhydrant/issues"
+   },
+   "homepage": "https://github.com/faulkj/fhirhydrant#readme",
+   "keywords": [
+      "fhir",
+      "mcp",
+      "model-context-protocol",
+      "smart-on-fhir",
+      "backend-services",
+      "hl7",
+      "healthcare",
+      "ehr",
+      "fhirclient",
+      "fhirstarterjs"
+   ],
+   "files": [
+      ".out",
+      "definitions.json",
+      "instructions.md"
+   ],
+   "publishConfig": {
+      "access": "public",
+      "registry": "https://registry.npmjs.org/"
+   },
+   "engines": {
+      "node": ">=24"
+   },
+   "scripts": {
+      "check": "tsc --noEmit",
+      "build": "tsup ts/server.ts --format esm --out-dir .out --no-splitting --platform node --clean",
+      "prepublishOnly": "npm run build",
+      "start": "node .out/server.js",
+      "dev": "node --env-file=.env --experimental-strip-types --watch ts/server.ts",
+      "inspector": "npx @modelcontextprotocol/inspector"
+   },
+   "dependencies": {
+      "@cfworker/json-schema": "^4.1.1",
+      "@modelcontextprotocol/express": "2.0.0-alpha.2",
+      "@modelcontextprotocol/node": "2.0.0-alpha.2",
+      "@modelcontextprotocol/server": "2.0.0-alpha.2",
+      "express": "^5.2.1",
+      "fhirclient": "^2.6.3",
+      "fhirstarterjs": "^1.0.5",
+      "zod": "^4.4.3"
+   },
+   "devDependencies": {
+      "@types/express": "^5.0.6",
+      "@types/node": "^25.9.3",
+      "tsup": "^8.5.1",
+      "typescript": "^6.0.3"
+   },
+   "overrides": {
+      "uuid": ">=11.1.1"
+   }
+}
+