add Phase 8.8 generator --mcp scaffold emission

`fhir-gen generate --mcp <dir>` (or GeneratorOptions.mcpOutDir
programmatically) writes an MCP server scaffold alongside the typed
client output: mcp.config.json seeded with the bound IG's resource
types and safe defaults (writes=[], confirmWrites=true,
defaultSearchCount=20, maxResponseBytes=65536), a server.ts shim that
loads the config and reads FHIR_BASE_URL/FHIR_TOKEN at runtime, and a
README pointing at the launch incantation.

Together with --ig, one fhir-gen generate command can now emit both
the typed FHIR client and a ready-to-launch MCP server for the same
upstream + IG.

Author: awbx

packages/cli/src/commands/generate.ts

@@ -15,6 +15,7 @@ export const generateCommand = new Command("generate")
   .option("--include-spec", "Emit markdown spec files alongside types for AI/LLM context")
   .option("--validator <target>", "Emit Standard Schema validators using: zod | native")
   .option("--strict-extensible", "Treat extensible bindings as closed enums in validators")
+  .option("--mcp <dir>", "Emit an MCP server scaffold (server.ts + mcp.config.json) into this directory")
   .action(async (opts) => {
     const resources = opts.resources ? opts.resources.split(",").map((r: string) => r.trim()) : undefined;
 
@@ -35,5 +36,6 @@ export const generateCommand = new Command("generate")
       includeSpec: opts.includeSpec,
       validator,
       strictExtensible: opts.strictExtensible,
+      mcpOutDir: opts.mcp ? resolve(opts.mcp) : undefined,
     });
   });

packages/generator/src/generator.ts

@@ -80,6 +80,14 @@ export interface GeneratorOptions {
   validator?: ValidatorTarget | undefined;
   /** Treat extensible bindings as closed enums in validators (default: open). */
   strictExtensible?: boolean | undefined;
+  /**
+   * Phase 8.8 — when set, emit an MCP server scaffold under this directory
+   * containing `mcp.config.json` (resource list, IG reference) and a
+   * `server.ts` shim that calls `@fhir-dsl/mcp`'s `createServer`. The
+   * scaffold reads the upstream base URL from the FHIR_BASE_URL env var
+   * at runtime so the generated artefacts stay portable.
+   */
+  mcpOutDir?: string | undefined;
 }
 
 export async function generate(options: GeneratorOptions): Promise<void> {
@@ -427,6 +435,16 @@ export async function generate(options: GeneratorOptions): Promise<void> {
     }
   }
 
+  // --- Phase 8.8: MCP server scaffold ---
+  if (options.mcpOutDir) {
+    await emitMcpScaffold({
+      outDir: options.mcpOutDir,
+      version,
+      igRefs: igPackages,
+      resourceTypes: resourceModels.map((r) => r.name),
+    });
+  }
+
   // --- Spec index ---
   if (options.includeSpec) {
     const specDir = join(versionDir, "spec");
@@ -483,3 +501,96 @@ async function fileExists(path: string): Promise<boolean> {
     return false;
   }
 }
+
+interface McpScaffoldOptions {
+  outDir: string;
+  version: string;
+  igRefs: readonly string[];
+  resourceTypes: readonly string[];
+}
+
+async function emitMcpScaffold(opts: McpScaffoldOptions): Promise<void> {
+  await mkdir(opts.outDir, { recursive: true });
+
+  const config = {
+    version: opts.version,
+    igRefs: [...opts.igRefs],
+    resourceTypes: [...opts.resourceTypes].sort(),
+    writes: [] as string[],
+    confirmWrites: true,
+    dryRun: false,
+    defaultSearchCount: 20,
+    maxResponseBytes: 65536,
+  };
+  await writeFile(join(opts.outDir, "mcp.config.json"), `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+
+  const serverContents = `import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { createServer, JsonLogAuditSink, stdioTransport } from "@fhir-dsl/mcp";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const config = JSON.parse(readFileSync(resolve(__dirname, "mcp.config.json"), "utf-8"));
+
+const baseUrl = process.env.FHIR_BASE_URL;
+if (!baseUrl) {
+  console.error("Set FHIR_BASE_URL to the upstream FHIR endpoint before launching the MCP server.");
+  process.exit(1);
+}
+
+const token = process.env.FHIR_TOKEN;
+
+const server = createServer({
+  name: "${opts.igRefs[0]?.replace(/[@/]/g, "-") ?? `fhir-${opts.version}`}-mcp",
+  version: "0.1.0",
+  baseUrl,
+  resourceTypes: config.resourceTypes,
+  audit: new JsonLogAuditSink(),
+  ...(config.writes && config.writes.length > 0 ? { writes: config.writes } : {}),
+  ...(config.confirmWrites ? { confirmWrites: true } : {}),
+  ...(config.dryRun ? { dryRun: true } : {}),
+  ...(config.defaultSearchCount !== undefined ? { defaultSearchCount: config.defaultSearchCount } : {}),
+  ...(config.maxResponseBytes !== undefined ? { maxResponseBytes: config.maxResponseBytes } : {}),
+  ...(token ? { auth: { kind: "bearer" as const, token } } : {}),
+});
+
+console.error(\`[fhir-dsl-mcp] starting stdio server for \${baseUrl} (\${config.resourceTypes.length} resource type(s))\`);
+await server.listen(stdioTransport());
+`;
+  await writeFile(join(opts.outDir, "server.ts"), serverContents, "utf-8");
+
+  const readme = `# Generated FHIR MCP server
+
+This directory was emitted by \`fhir-gen generate --mcp <out>\` and is
+ready to launch as an MCP stdio server.
+
+## Run
+
+\`\`\`sh
+FHIR_BASE_URL=https://your-fhir-server/baseR${opts.version.replace(/^r/i, "").toUpperCase()} \\
+FHIR_TOKEN=optional-bearer-token \\
+node --experimental-strip-types server.ts
+\`\`\`
+
+(or compile \`server.ts\` to JS first if your runtime doesn't support
+type stripping).
+
+## Configuration
+
+\`mcp.config.json\` controls the resource surface, write gating, and
+token-economy defaults. Edit it to:
+
+- Add a \`writes\` whitelist (e.g. \`["create", "update"]\`) to expose
+  write tools.
+- Tighten or relax \`maxResponseBytes\` and \`defaultSearchCount\`.
+- Disable \`confirmWrites\` if your agent doesn't need explicit
+  confirmation on every write.
+
+## IGs bound
+
+${opts.igRefs.length > 0 ? opts.igRefs.map((r) => `- \`${r}\``).join("\n") : "_(no IGs — base FHIR ${opts.version})_"}
+`;
+  await writeFile(join(opts.outDir, "README.md"), readme, "utf-8");
+
+  console.info(`Generated MCP scaffold in ${opts.outDir}`);
+}

packages/generator/test/e2e/mcp-scaffold.e2e.test.ts

@@ -0,0 +1,61 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { generate } from "../../src/generator.js";
+
+const FIXTURES_DIR = join(__dirname, "..", "fixtures", "terminology");
+
+describe("generate --mcp <out> scaffold", () => {
+  let outDir: string;
+  let mcpDir: string;
+
+  beforeAll(async () => {
+    outDir = mkdtempSync(join(tmpdir(), "fhir-dsl-mcp-out-"));
+    mcpDir = mkdtempSync(join(tmpdir(), "fhir-dsl-mcp-scaffold-"));
+    await generate({
+      version: "r4",
+      outDir,
+      localSpecDir: FIXTURES_DIR,
+      mcpOutDir: mcpDir,
+    });
+  });
+
+  afterAll(() => {
+    if (outDir) rmSync(outDir, { recursive: true, force: true });
+    if (mcpDir) rmSync(mcpDir, { recursive: true, force: true });
+  });
+
+  it("emits mcp.config.json, server.ts, and README.md", () => {
+    expect(existsSync(join(mcpDir, "mcp.config.json"))).toBe(true);
+    expect(existsSync(join(mcpDir, "server.ts"))).toBe(true);
+    expect(existsSync(join(mcpDir, "README.md"))).toBe(true);
+  });
+
+  it("seeds mcp.config.json with the generated resourceTypes and safe defaults", () => {
+    const cfg = JSON.parse(readFileSync(join(mcpDir, "mcp.config.json"), "utf-8"));
+    expect(cfg.version).toBe("r4");
+    expect(Array.isArray(cfg.resourceTypes)).toBe(true);
+    expect(cfg.resourceTypes.length).toBeGreaterThan(0);
+    expect(cfg.resourceTypes).toEqual([...cfg.resourceTypes].sort());
+    expect(cfg.writes).toEqual([]);
+    expect(cfg.confirmWrites).toBe(true);
+    expect(cfg.dryRun).toBe(false);
+    expect(cfg.defaultSearchCount).toBe(20);
+    expect(cfg.maxResponseBytes).toBe(65536);
+  });
+
+  it("writes a server.ts shim that calls @fhir-dsl/mcp's createServer", () => {
+    const src = readFileSync(join(mcpDir, "server.ts"), "utf-8");
+    expect(src).toContain('import { createServer, JsonLogAuditSink, stdioTransport } from "@fhir-dsl/mcp"');
+    expect(src).toContain("process.env.FHIR_BASE_URL");
+    expect(src).toContain("mcp.config.json");
+    expect(src).toContain("await server.listen(stdioTransport())");
+  });
+
+  it("README references the FHIR_BASE_URL env var", () => {
+    const readme = readFileSync(join(mcpDir, "README.md"), "utf-8");
+    expect(readme).toContain("FHIR_BASE_URL");
+    expect(readme).toContain("fhir-gen generate --mcp");
+  });
+});