@autoview/cli 0.1.0

package/prompts/AUTOVIEW_REVIEW.md

@@ -0,0 +1,60 @@
+You are the UI Review phase of the AutoView agent.
+
+You receive the product plan, the SDK domain map, and per-screen
+metadata from the Render phase (rationale, attempt count, whether
+parsing eventually succeeded). Your single job is to produce one
+markdown file — `wiki/sdk-feedback.md` — that captures the honest,
+operator-facing assessment of what the SDK is like to build a frontend
+on top of. The whole reason AutoView exists is to surface API quality
+problems through the act of consuming the API; this is where that
+signal lands.
+
+You do not see screenshots and you do not run the application. Visual
+verification happens later, by the operator on the Sandbox deploy. Your
+review is a code-and-spec audit, not a visual audit.
+
+## What "sdk-feedback" must contain
+
+A markdown document with these sections in order:
+
+1. **Summary** — 2–4 sentences in the operator's voice. What kind of
+   product is this, how cleanly did the SDK shape it, and is the API
+   ready to ship to a human?
+2. **What worked well** — bullets. Concrete instances where the SDK
+   made a flow easy: well-named resources, clear pagination, sane
+   defaults, helpful JSDoc.
+3. **What's awkward** — bullets. The whole point of the document.
+   Each bullet calls out one specific API decision that made the
+   frontend awkward: redundant endpoints, missing list filters,
+   inconsistent naming, types that force casts, flows that require
+   round-trips the UI shouldn't need, missing pagination, unclear
+   actor boundaries. Be specific — name the resource or accessor.
+4. **What's missing** — bullets. Functionality the product needed but
+   the SDK does not expose. Reference the intentional-omission list
+   from the product plan and add anything new the Render phase
+   stumbled on.
+5. **Pages that broke** — bullets. List every screen where
+   `ok === false` in the render metadata. One bullet each:
+   path, ui pattern, attempts spent, the parser diagnostic. These
+   are the pages the operator should look at first when deploying
+   to Sandbox.
+
+If a section has nothing to report, write "None observed" — do not
+delete the section.
+
+## Mindset
+
+- Be specific and short. Operator-facing markdown, not LLM prose.
+- Name resources and accessors. "shoppings.customers.orders.create
+  forces a two-step round-trip because…" is signal. "Some endpoints
+  felt awkward" is noise.
+- Do not invent problems. If the SDK is clean, write "the API is
+  clean; the awkwardness is in the product, not the platform."
+- Do not write Korean. The Sandbox operator reading this is the
+  same team that reads the rest of `wiki/`.
+
+## Output
+
+Call `writeSdkFeedback` exactly once with the complete markdown body
+and a one-sentence narrative summary. The orchestrator drops the
+markdown into `frontend/wiki/sdk-feedback.md` verbatim.

package/prompts/AUTOVIEW_SDK_STUDY.md

@@ -0,0 +1,89 @@
+You are the SDK Study phase of the AutoView agent.
+
+Your single job is to read an entire TypeScript SDK and produce a domain
+map that the downstream Product Plan phase can use to design a real
+frontend product. You are not designing screens, components, or user
+flows yet — only mapping the surface area honestly.
+
+## Inputs you will receive
+
+- A list of TypeScript files from the SDK (paths + contents), generated
+  by AutoBE (or `@samchon/shopping-api` when the agent is exercised
+  against the bundled reference).
+- Every JSDoc comment in those files is authoritative — treat it as the
+  source of truth for purpose, constraints, and actor expectations.
+- An OpenAPI document derived from the SDK, attached for cross-reference
+  only. When the SDK and the OpenAPI disagree, the SDK wins.
+
+## What "resources" mean
+
+A resource is a coherent group of endpoints organized around the same
+namespace prefix and the same noun. `shoppings.customers.sales.*` is one
+resource (`sales`) viewed by the customer actor. `shoppings.admins.sales.*`
+is the same resource viewed by the admin actor — list them as one
+resource and record both actor views.
+
+For each resource, record:
+
+- `name`: short noun (e.g. `sales`, `orders`, `channels`, `categories`).
+- `namespace`: dotted accessor path (e.g. `shoppings.customers.sales`).
+  If the resource is exposed under multiple namespaces (per actor),
+  list the customer-facing one first and mention the others in
+  `notes`.
+- `purpose`: one short sentence in the operator's voice. **Why** does
+  this resource exist in the product? Not "CRUD on Sale" — "Browse and
+  buy products that sellers have published".
+- `actorsInvolved`: subset of the actors you identified.
+- `notes`: anything subtle worth carrying into the product plan —
+  pagination shape, multi-actor exposure, soft-delete semantics, etc.
+
+## What "actors" mean
+
+Actors are roles the SDK serves. Infer them from:
+
+1. Namespace segmentation (`customers`, `sellers`, `admins`, `guests`).
+2. Authentication shape (`IAuthorized<"customer">` vs. `IAuthorized<"admin">`).
+3. JSDoc references to operator types.
+
+Common actors: `customer`, `seller`, `administrator`, `guest`. Do not
+invent actors the SDK does not support. If only one actor is present,
+record exactly one.
+
+For each actor, record:
+
+- `name`: lower-case role identifier (e.g. `customer`).
+- `journeys`: 1–5 end-to-end goals this actor accomplishes by
+  composing several endpoints. Phrase each as an arrow chain
+  (`sign up → browse catalog → add to cart → checkout`). These are the
+  raw material the Product Plan phase uses to decide which screens
+  exist.
+
+## What "notable constraints" mean
+
+Things a frontend developer needs to know up-front that are not
+obvious from a single endpoint signature:
+
+- Soft-delete vs. hard-delete behavior.
+- Pagination conventions (cursor vs. offset; default page size).
+- Authentication scopes and where they are required.
+- Idempotency keys, optimistic-concurrency tokens, or audit fields.
+- Anything the SDK comments call out as a footgun.
+
+List these as standalone strings. One sentence each. Do not
+fabricate constraints you cannot point to in the SDK.
+
+## What you must NOT do
+
+- Do **not** design screens. No "Catalog page", "Cart page", or
+  navigation. That is the Product Plan phase's job.
+- Do **not** invent endpoints the SDK does not expose.
+- Do **not** drop resources that look noisy. Record them all; the
+  Product Plan phase decides what to omit.
+- Do **not** write Korean — output is consumed by downstream prompts
+  and must stay in English.
+
+## Output
+
+Call the `buildSdkMap` function exactly once with the full domain map.
+The next phase reads the map verbatim — make it complete, accurate, and
+brief.

package/src/AutoViewAgent.ts

@@ -0,0 +1,222 @@
+import { OpenApi } from "@typia/interface";
+import { IAgenticaVendor, MicroAgentica } from "@agentica/core";
+
+import {
+  AutoBeFunctionCallingMetric,
+  IAutoBeCompiler,
+  IAutoBeTokenUsageJson,
+} from "./typings";
+
+import { AutoViewInterfaceCompiler } from "./compiler/AutoViewInterfaceCompiler";
+import {
+  AutoViewDispatchEvent,
+  IAutoViewAgentContext,
+  IAutoViewConversateProps,
+  IAutoViewConversateResult,
+} from "./context/IAutoViewAgentContext";
+import { orchestrateAutoView } from "./orchestrate/orchestrateAutoView";
+
+/**
+ * Standalone entry point for the AutoView agent.
+ *
+ * Generates a runnable Next.js + shadcn/ui frontend from any
+ * {@link OpenApi.IDocument} — typically produced by passing a third party
+ * `swagger.json` through `@autobe/utils.invertOpenApiDocument`. Does not
+ * require `@autobe/agent`; the only requirement is an {@link IAgenticaVendor}
+ * (model + API key) and a compiler instance for SDK writing.
+ *
+ * Backward compat: `@autobe/agent`'s `AutoBeAgent.runAutoView()` still works as
+ * before — it bypasses this class and hands its own context to the same
+ * `orchestrateAutoView` directly.
+ */
+export interface IAutoViewAgentProps {
+  /**
+   * The OpenAPI document the frontend will be generated against. For a
+   * third-party Swagger payload, run it through `invertOpenApiDocument` from
+   * `@autobe/utils` first.
+   */
+  document: OpenApi.IDocument;
+
+  /**
+   * Agentica vendor — model + API key + optional semaphore. Same shape
+   * `@autobe/agent` accepts; the agent's quota-tracker / mistral-shim helpers
+   * are not wired here because they are AutoBE-specific.
+   */
+  vendor: IAgenticaVendor;
+
+  /**
+   * Optional design theme passed through to the Product Plan + Render phases.
+   * Empty / undefined means "prototype-first, content-first defaults".
+   */
+  designTheme?: string;
+
+  /**
+   * Compiler instance used to write the SDK files. Falls back to a fresh
+   * `AutoBeCompiler` when not provided. Pass your own instance if you want to
+   * share one across multiple AutoViewAgent runs in the same process.
+   */
+  compiler?: IAutoBeCompiler;
+
+  /** Concurrency cap for the per-screen render batch. Defaults to 8. */
+  semaphore?: number;
+
+  /**
+   * Live backend the generated frontend should connect to. When given, the
+   * scaffold wires `connection.ts` with `simulate: false` so the dev server
+   * renders real data on first boot — the standalone CLI's reason to exist.
+   *
+   * Omit to fall back to simulator mode (only useful for swaggers that
+   * genuinely have no backend). `extractBackendFromSwagger(payload)` in this
+   * package is a small helper for pulling the URL out of a swagger's
+   * `servers[0].url` field automatically.
+   */
+  backend?: { host: string } | null;
+
+  /**
+   * Opt into Phase 6 runtime audit: after typecheck, boot `next dev`, walk
+   * every page with Playwright, and re-render any page that console-errored /
+   * crashed / failed to navigate. Catches the class of bugs `tsc --noEmit`
+   * cannot see (`obj?.array.method(...)` undefined-access, react render crashes
+   * on simulator data).
+   *
+   * Defaults to `false` because it installs Playwright + Chromium (~150MB) and
+   * boots `next dev` twice per agent run, adding ~10–20 minutes.
+   */
+  runtimeAudit?: boolean;
+
+  /**
+   * Opt into workflow verification: after typecheck, boot the generated app in
+   * a real headless browser and walk the derived user workflows, writing
+   * `wiki/verification.md`. Proves the app works for a user, not just compiles.
+   * Heavy (Chromium + `next dev`); defaults to `false`.
+   */
+  verify?: boolean;
+
+  /**
+   * Path globs to KEEP — only endpoints whose path matches become screens.
+   * Slices a large swagger to one actor surface, e.g.
+   * `["shoppings/customers/**"]`. Empty/absent means "all".
+   */
+  include?: string[];
+
+  /** Path globs to DROP after include, e.g. `["**​/monitors/**"]`. */
+  exclude?: string[];
+
+  /**
+   * Optional callback for every event the orchestrators dispatch
+   * (`autoViewStart`, `autoViewSdkStudy`, `autoViewProductPlan`,
+   * `autoViewScaffold`, per-page `autoViewRenderPage`, `autoViewReview`,
+   * `autoViewComplete`). Useful for progress bars, structured logging, etc.
+   */
+  onEvent?: (event: AutoViewDispatchEvent) => void;
+}
+
+/** Public result of {@link AutoViewAgent.run}. */
+export interface IAutoViewAgentResult {
+  /** Path → content map of the generated frontend project. */
+  files: Record<string, string>;
+}
+
+export class AutoViewAgent {
+  public constructor(private readonly props: IAutoViewAgentProps) {}
+
+  /**
+   * Drive every AutoView phase end-to-end and return the assembled frontend
+   * project as a flat `path → content` map.
+   *
+   * Mutates nothing on disk; serialize the map to ZIP, push it to a Sandbox, or
+   * write it out directly with `@autobe/filesystem` — your choice. The CLI
+   * binary (`bin/autoview`) does the disk-write step.
+   */
+  public async run(): Promise<IAutoViewAgentResult> {
+    const compiler: IAutoBeCompiler = this.props.compiler ?? {
+      interface: new AutoViewInterfaceCompiler(),
+    };
+    let captured: Record<string, string> = {};
+    const ctx: IAutoViewAgentContext = {
+      state: () => ({
+        interface: { document: this.props.document, step: 0 },
+      }),
+      compiler: async () => compiler,
+      vendor: { semaphore: this.props.semaphore ?? 8 },
+      dispatch: (event: AutoViewDispatchEvent) => {
+        if (event.type === "autoViewComplete") {
+          captured = event.files;
+        }
+        this.props.onEvent?.(event);
+        return event;
+      },
+      conversate: (cprops) => this.conversate(cprops),
+    };
+    await orchestrateAutoView(ctx, {
+      source: "interface",
+      designTheme: this.props.designTheme,
+      backend: this.props.backend ?? null,
+      runtimeAudit: this.props.runtimeAudit ?? false,
+      verify: this.props.verify ?? false,
+      include: this.props.include,
+      exclude: this.props.exclude,
+    });
+    return { files: captured };
+  }
+
+  private async conversate(
+    cprops: IAutoViewConversateProps,
+  ): Promise<IAutoViewConversateResult> {
+    // Minimal agentica wiring — no quota tracker, no vendor-specific
+    // shims, no compaction. The full AutoBE agent layers those on for
+    // its own concerns; the standalone path keeps things thin so it
+    // works against any OpenAI-compatible endpoint that supports tool
+    // calling.
+    const agent = new MicroAgentica({
+      vendor: this.props.vendor,
+      config: {
+        executor: { describe: false },
+        stream: cprops.enforceFunctionCall === false,
+      },
+      histories: cprops.histories,
+      controllers: [cprops.controller],
+    });
+    let tokenUsage: IAutoBeTokenUsageJson.IComponent = zeroTokenUsage();
+    const metric: AutoBeFunctionCallingMetric = {
+      attempt: 0,
+      success: 0,
+      invalidJson: 0,
+      validationFailure: 0,
+      consent: 0,
+    };
+    agent.on("call", () => {
+      metric.attempt++;
+    });
+    agent.on("execute", () => {
+      metric.success++;
+    });
+    agent.on("jsonParseError", () => {
+      metric.invalidJson++;
+    });
+    agent.on("validate", () => {
+      metric.validationFailure++;
+    });
+    await agent.conversate(cprops.userMessage);
+    const usage = agent.getTokenUsage().aggregate;
+    tokenUsage = {
+      total: usage.total,
+      input: usage.input,
+      output: usage.output,
+    };
+    return { metric, tokenUsage };
+  }
+}
+
+function zeroTokenUsage(): IAutoBeTokenUsageJson.IComponent {
+  return {
+    total: 0,
+    input: { total: 0, cached: 0 },
+    output: {
+      total: 0,
+      reasoning: 0,
+      accepted_prediction: 0,
+      rejected_prediction: 0,
+    },
+  };
+}

package/src/agent/emitMcpServer.integration.test.ts

@@ -0,0 +1,168 @@
+import { spawnSync } from "child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import http from "http";
+import { join } from "path";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { OpenApiConverter } from "@typia/utils";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { emitMcpServer } from "./emitMcpServer";
+
+/**
+ * End-to-end proof that the emitted MCP server speaks the real MCP protocol:
+ * spawn it over stdio, drive it with an actual MCP `Client` (listTools +
+ * callTool), and exercise the producer→consumer chain (list → take an id from
+ * the response → detail) against a LOCAL mock backend (deterministic, no
+ * network). Distinct from the string-shape unit tests in emitMcpServer.test.ts.
+ */
+function doc(paths: Record<string, unknown>, schemas: Record<string, unknown> = {}) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0", info: { title: "Shop", version: "1.0.0" }, paths, components: { schemas },
+  } as never);
+}
+
+const param = (n: string) => ({ name: n, in: "path", required: true, schema: { type: "string" } });
+const fixture = doc(
+  {
+    "/sales": { get: { operationId: "index", summary: "List sales.", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Sale" } } } } } } } },
+    "/sales/{saleId}": { get: { operationId: "at", summary: "Get a sale.", parameters: [param("saleId")], responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Sale" } } } } } } },
+    // a nested resource — its id is produced by the questions list, which itself
+    // needs the saleId produced by the sales list (a genuine 2-hop chain).
+    "/sales/{saleId}/questions": { get: { operationId: "qIndex", summary: "List questions on a sale.", parameters: [param("saleId")], responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Question" } } } } } } } },
+    "/sales/{saleId}/questions/{questionId}": { get: { operationId: "qAt", summary: "Get one question.", parameters: [param("saleId"), param("questionId")], responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Question" } } } } } } },
+  },
+  {
+    Sale: { type: "object", properties: { id: { type: "string" }, title: { type: "string" } }, required: ["id"] },
+    Question: { type: "object", properties: { id: { type: "string" }, body: { type: "string" } }, required: ["id"] },
+  },
+);
+
+const SALES = [{ id: "sale_1", title: "MacBook" }, { id: "sale_2", title: "iPhone" }];
+const QUESTIONS: Record<string, Array<{ id: string; body: string }>> = {
+  sale_2: [{ id: "q_9", body: "Is the iPhone unlocked?" }],
+};
+
+describe("emitMcpServer — real MCP protocol round-trip", () => {
+  let backend: http.Server;
+  let base = "";
+  let client: Client;
+  let transport: StdioClientTransport;
+  const tmpDirs: string[] = [];
+
+  // Temp dirs live UNDER the repo so the spawned ESM server resolves this repo's
+  // @modelcontextprotocol/sdk by walking up to node_modules (ESM ignores NODE_PATH).
+  const mkTmp = (prefix: string): string => {
+    const dir = mkdtempSync(join(process.cwd(), prefix));
+    tmpDirs.push(dir);
+    return dir;
+  };
+
+  beforeAll(async () => {
+    // 1. local mock backend
+    backend = http.createServer((req, res) => {
+      const u = (req.url ?? "").split("?")[0];
+      res.writeHead(200, { "content-type": "application/json" });
+      if (u === "/sales") return res.end(JSON.stringify(SALES));
+      const qOne = u!.match(/^\/sales\/([^/]+)\/questions\/([^/]+)$/);
+      if (qOne) return res.end(JSON.stringify((QUESTIONS[qOne[1]!] ?? []).find((q) => q.id === qOne[2]) ?? {}));
+      const qList = u!.match(/^\/sales\/([^/]+)\/questions$/);
+      if (qList) return res.end(JSON.stringify(QUESTIONS[qList[1]!] ?? []));
+      const one = u!.match(/^\/sales\/([^/]+)$/);
+      return res.end(JSON.stringify(one ? SALES.find((s) => s.id === one[1]) ?? {} : {}));
+    });
+    await new Promise<void>((ok) => backend.listen(0, "127.0.0.1", () => ok()));
+    base = `http://127.0.0.1:${(backend.address() as { port: number }).port}`;
+
+    // 2. write the emitted server to a temp dir under the repo
+    const dir = mkTmp(".tmp-mcp-");
+    const files = emitMcpServer(fixture, { backend: base, title: "Shop" });
+    for (const [name, content] of Object.entries(files)) writeFileSync(join(dir, name), content);
+
+    // 3. spawn it as a real MCP server over stdio and connect a real MCP client.
+    transport = new StdioClientTransport({
+      command: process.execPath,
+      args: [join(dir, "server.mjs")],
+      env: { ...process.env, API_HOST: base },
+    });
+    client = new Client({ name: "test", version: "1.0.0" }, { capabilities: {} });
+    await client.connect(transport);
+  }, 30000);
+
+  afterAll(async () => {
+    await client?.close();
+    backend?.close();
+    for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  it("listTools returns the surface with read/write annotations over MCP", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.length).toBeGreaterThan(0);
+    const list = tools.find((t) => t.name === "sales.get");
+    expect(list).toBeDefined();
+    expect(list!.annotations?.readOnlyHint).toBe(true);
+  });
+
+  it("callTool executes the live API and drives a producer→consumer chain", async () => {
+    // list
+    const listRes = (await client.callTool({ name: "sales.get", arguments: {} })) as {
+      content: Array<{ text: string }>;
+      isError?: boolean;
+    };
+    expect(listRes.isError ?? false).toBe(false);
+    const sales = JSON.parse(listRes.content[0]!.text) as Array<{ id: string; title: string }>;
+    expect(sales.length).toBe(2);
+
+    // take an id from the list response, call detail with it
+    const detailRes = (await client.callTool({
+      name: "sales.getBySaleid",
+      arguments: { saleId: sales[1]!.id },
+    })) as { content: Array<{ text: string }>; isError?: boolean };
+    expect(detailRes.isError ?? false).toBe(false);
+    const sale = JSON.parse(detailRes.content[0]!.text) as { title: string };
+    expect(sale.title).toBe("iPhone");
+  });
+
+  it("drives a 2-hop nested chain, threading two path params from prior responses", async () => {
+    const call = async (name: string, args: Record<string, unknown>) =>
+      (await client.callTool({ name, arguments: args })) as {
+        content: Array<{ text: string }>;
+        isError?: boolean;
+      };
+
+    // hop 0: list sales → saleId
+    const sales = JSON.parse((await call("sales.get", {})).content[0]!.text) as Array<{ id: string }>;
+    const saleId = sales[1]!.id; // sale_2
+
+    // hop 1: list that sale's questions (needs saleId) → questionId
+    const qList = await call("sales.questions.getBySaleid", { saleId });
+    expect(qList.isError ?? false).toBe(false);
+    const questions = JSON.parse(qList.content[0]!.text) as Array<{ id: string }>;
+    expect(questions.length).toBe(1);
+    const questionId = questions[0]!.id; // q_9
+
+    // hop 2: get the question detail (needs BOTH saleId and questionId)
+    const qDetail = await call("sales.questions.getBySaleidAndQuestionid", { saleId, questionId });
+    expect(qDetail.isError ?? false).toBe(false);
+    const question = JSON.parse(qDetail.content[0]!.text) as { body: string };
+    expect(question.body).toContain("iPhone");
+  });
+
+  it("declares the multi-hop producer chain on the nested tool", async () => {
+    const { tools } = await client.listTools();
+    const nested = tools.find((t) => t.name === "sales.questions.getBySaleidAndQuestionid");
+    expect(nested).toBeDefined();
+    // both path params are required inputs
+    expect(nested!.inputSchema).toMatchObject({ required: expect.arrayContaining(["saleId", "questionId"]) });
+  });
+
+  it("the generated server.mjs is valid JS (node --check)", () => {
+    const dir = mkTmp(".tmp-mcp-chk-");
+    const files = emitMcpServer(fixture, { backend: base, title: "Shop" });
+    const path = join(dir, "server.mjs");
+    writeFileSync(path, files["server.mjs"]!);
+    const r = spawnSync(process.execPath, ["--check", path], { encoding: "utf8" });
+    expect(r.status).toBe(0);
+  });
+});

package/src/agent/emitMcpServer.test.ts

@@ -0,0 +1,51 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { emitMcpServer } from "./emitMcpServer";
+
+function doc(paths: Record<string, unknown>, schemas: Record<string, unknown> = {}) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0",
+    info: { title: "Shop", version: "1.0.0" },
+    paths,
+    components: { schemas },
+  } as never);
+}
+
+const fixture = doc(
+  {
+    "/sales": {
+      get: { operationId: "index", summary: "List sales.", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Sale" } } } } } } },
+    },
+    "/sales/{saleId}": {
+      get: { operationId: "at", summary: "Get a sale.", parameters: [{ name: "saleId", in: "path", required: true, schema: { type: "string" } }], responses: { 200: { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Sale" } } } } } },
+    },
+  },
+  { Sale: { type: "object", properties: { id: { type: "string" }, title: { type: "string" } }, required: ["id"] } },
+);
+
+describe("emitMcpServer", () => {
+  const files = emitMcpServer(fixture, { backend: "http://127.0.0.1:37001", title: "Shop" });
+
+  it("emits a runnable MCP project", () => {
+    expect(Object.keys(files).sort()).toEqual(["README.md", "package.json", "server.mjs"]);
+    const pkg = JSON.parse(files["package.json"]!);
+    expect(pkg.dependencies["@modelcontextprotocol/sdk"]).toBeDefined();
+    expect(pkg.type).toBe("module");
+  });
+
+  it("server wires the MCP request handlers and bakes the tools + backend", () => {
+    const server = files["server.mjs"]!;
+    expect(server).toContain("ListToolsRequestSchema");
+    expect(server).toContain("CallToolRequestSchema");
+    expect(server).toContain("StdioServerTransport");
+    // the tool surface is baked in, with the default backend and an HTTP executor
+    expect(server).toContain('"sales.get"');
+    expect(server).toContain("http://127.0.0.1:37001");
+    expect(server).toContain("await fetch(url");
+  });
+
+  it("is deterministic", () => {
+    expect(emitMcpServer(fixture, { backend: null })).toEqual(emitMcpServer(fixture, { backend: null }));
+  });
+});