@yichus/mcp 0.1.0 → 0.1.1

package/dist/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 
+// src/cli.ts
+import { parseArgs } from "util";
+import { z as z3 } from "zod";
+
 // src/server.ts
-import { LocalRelayMcpServer } from "@mcp-b/webmcp-local-relay";
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/calculators.ts
 var DEFAULT_BASE_URL = "https://yich.us";
@@ -19,6 +22,12 @@ var CALCULATORS = [
     description: "How much water does one rainfall event collect, and how much overflows the tank?",
     path: "demos/simulation/rainwater.html"
   },
+  {
+    slug: "rainwater-history",
+    title: "Rainwater through a dry spell",
+    description: "Run NOAA weather observations through an inspectable daily tank model. Change capacity and demand, inspect captured data, and share a saved report.",
+    path: "demos/simulation/rainwater-history.html"
+  },
   {
     slug: "battery-runtime",
     title: "Battery runtime",
@@ -168,44 +177,272 @@ function openUrlInBrowser(rawUrl) {
     command = "xdg-open";
     args = [validated];
   }
-  spawn(command, args, { detached: true, stdio: "ignore" }).unref();
-  return { command, args };
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.once("spawn", () => {
+      child.unref();
+      resolve({ command, args, opened: true });
+    });
+    child.on("error", (error) => resolve({ command, args, opened: false, error: error.message }));
+  });
+}
+
+// src/relay.ts
+import {
+  LocalRelayMcpServer,
+  RelayBridgeServer,
+  RelayRegistry,
+  buildPublicToolName
+} from "@mcp-b/webmcp-local-relay";
+var REMEMBERED_TABS = 256;
+var FirstTabNamingRegistry = class extends RelayRegistry {
+  firstSeen = /* @__PURE__ */ new Map();
+  tabByConnection = /* @__PURE__ */ new Map();
+  seen = 0;
+  upsertSource(connectionId, hello) {
+    super.upsertSource(connectionId, hello);
+    this.tabByConnection.set(connectionId, hello.tabId);
+    this.remember(hello.tabId);
+  }
+  removeConnection(connectionId) {
+    super.removeConnection(connectionId);
+    this.tabByConnection.delete(connectionId);
+  }
+  listTools() {
+    return this.named().map(({ tool }) => tool).sort((a, b) => a.name.localeCompare(b.name));
+  }
+  resolveInvocation(options) {
+    const entry = this.named().find(({ tool }) => tool.name === options.toolName);
+    if (!entry) return null;
+    const resolved = super.resolveInvocation({ ...options, toolName: entry.relayName });
+    return resolved && { ...resolved, publicToolName: entry.tool.name };
+  }
+  // Each relay tool with the name an agent sees: the plain name for the
+  // copy published by the first-seen tab among those publishing it.
+  named() {
+    const tools = super.listTools();
+    const owners = /* @__PURE__ */ new Map();
+    for (const tool of tools) {
+      for (const source of tool.sources) {
+        const order = this.order(source.tabId);
+        owners.set(tool.originalName, Math.min(owners.get(tool.originalName) ?? order, order));
+      }
+    }
+    return tools.map((tool) => {
+      const owned = tool.sources.some((source) => this.order(source.tabId) === owners.get(tool.originalName));
+      const name = owned ? buildPublicToolName({ originalToolName: tool.originalName }) : tool.name;
+      return { relayName: tool.name, tool: { ...tool, name } };
+    });
+  }
+  order(tabId) {
+    return this.firstSeen.get(tabId) ?? Number.POSITIVE_INFINITY;
+  }
+  remember(tabId) {
+    if (this.firstSeen.has(tabId)) return;
+    this.firstSeen.set(tabId, this.seen++);
+    const open = new Set(this.tabByConnection.values());
+    for (const tab of this.firstSeen.keys()) {
+      if (this.firstSeen.size - open.size <= REMEMBERED_TABS) break;
+      if (!open.has(tab)) this.firstSeen.delete(tab);
+    }
+  }
+};
+var TOOL_LIST_CHANGED = "notifications/tools/list_changed";
+var isToolListChanged = (message) => "method" in message && message.method === TOOL_LIST_CHANGED && !("id" in message);
+var ToolListChangedCoalescer = class {
+  constructor(inner, windowMs) {
+    this.inner = inner;
+    this.windowMs = windowMs;
+    inner.onmessage = (message, extra) => this.onmessage?.(message, extra);
+    inner.onerror = (error) => this.onerror?.(error);
+    inner.onclose = () => {
+      this.drop();
+      this.onclose?.();
+    };
+  }
+  inner;
+  windowMs;
+  onclose;
+  onerror;
+  onmessage;
+  pending = null;
+  get sessionId() {
+    return this.inner.sessionId;
+  }
+  setProtocolVersion(version) {
+    this.inner.setProtocolVersion?.(version);
+  }
+  start() {
+    return this.inner.start();
+  }
+  async send(message, options) {
+    if (!isToolListChanged(message)) return this.inner.send(message, options);
+    if (this.pending) return;
+    this.pending = setTimeout(() => {
+      this.pending = null;
+      this.inner.send(message, options).catch((error) => this.onerror?.(error));
+    }, this.windowMs);
+    this.pending.unref?.();
+  }
+  close() {
+    this.drop();
+    return this.inner.close();
+  }
+  drop() {
+    if (this.pending) clearTimeout(this.pending);
+    this.pending = null;
+  }
+};
+var CoalescingRelayServer = class extends LocalRelayMcpServer {
+  constructor(options, windowMs) {
+    super(options);
+    this.windowMs = windowMs;
+  }
+  windowMs;
+  connect(transport) {
+    return super.connect(new ToolListChangedCoalescer(transport, this.windowMs));
+  }
+};
+var PageAnswerBridge = class extends RelayBridgeServer {
+  pageContent = /* @__PURE__ */ new WeakMap();
+  async invokeTool(...call) {
+    const result = await super.invokeTool(...call);
+    this.pageContent.set(result, result.content);
+    return result;
+  }
+  /** The content a page answered with, for an answer this bridge carried. */
+  pageAnswer(result) {
+    return this.pageContent.get(result);
+  }
+};
+
+// src/saveCalculator.ts
+import { mkdir, writeFile } from "fs/promises";
+import { isAbsolute, join } from "path";
+import { z } from "zod";
+var saveCalculatorInput = z.object({
+  exportToolName: z.string().regex(/^yichus_example_export(?:_[a-zA-Z0-9_-]+)?$/).describe("Public export tool name from webmcp_list_tools, matched to the intended tab."),
+  exampleId: z.string().min(1),
+  expectedRevision: z.number().int().nonnegative(),
+  outputDirectory: z.string().refine(isAbsolute, "Use an absolute output directory.").describe("A new directory under an existing parent. Existing directories are refused; files are never overwritten.")
+});
+var chunkSchema = z.object({
+  exampleId: z.string(),
+  revision: z.number().int(),
+  exportId: z.string().min(1),
+  assetBaseUrl: z.url(),
+  sources: z.array(z.object({ fileName: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.bosatsu$/), source: z.string().max(1e6) })).min(1).max(16),
+  html: z.object({
+    fileName: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.html$/),
+    content: z.string().min(1).max(32768),
+    offset: z.number().int().nonnegative(),
+    totalLength: z.number().int().positive().max(32 * 1024 * 1024),
+    nextOffset: z.number().int().nonnegative().nullable()
+  })
+});
+async function saveCalculator(rawArgs, invoke) {
+  const args = saveCalculatorInput.parse(rawArgs);
+  const content = [];
+  let first;
+  let offset = 0;
+  for (; ; ) {
+    const response = z.object({ isError: z.boolean().optional(), structuredContent: z.unknown().optional() }).parse(await invoke(args.exportToolName, {
+      exampleId: args.exampleId,
+      expectedRevision: args.expectedRevision,
+      offset,
+      ...first ? { expectedExportId: first.exportId } : {}
+    }));
+    if (response.isError) throw new Error("Browser export failed. Read the current example feedback before retrying.");
+    const chunk = chunkSchema.parse(response.structuredContent);
+    if (chunk.exampleId !== args.exampleId || chunk.revision !== args.expectedRevision || chunk.html.offset !== offset) throw new Error("Export does not match the requested example, revision, or offset.");
+    if (first && (chunk.exportId !== first.exportId || chunk.assetBaseUrl !== first.assetBaseUrl || chunk.html.fileName !== first.html.fileName || chunk.html.totalLength !== first.html.totalLength || JSON.stringify(chunk.sources) !== JSON.stringify(first.sources))) throw new Error("Export changed during transfer. Nothing was saved; start again.");
+    first ??= chunk;
+    const end = offset + chunk.html.content.length;
+    if (end > chunk.html.totalLength || (chunk.html.nextOffset === null ? end !== chunk.html.totalLength : chunk.html.nextOffset !== end || end >= chunk.html.totalLength)) throw new Error("Incomplete or inconsistent export chunk. Nothing was saved.");
+    content.push(chunk.html.content);
+    if (chunk.html.nextOffset === null) break;
+    offset = chunk.html.nextOffset;
+  }
+  const files = [...first.sources.map((s) => ({ fileName: s.fileName, content: s.source })), { fileName: first.html.fileName, content: content.join("") }];
+  if (new Set(files.map((f) => f.fileName.toLowerCase())).size !== files.length) throw new Error("Export file names must be unique.");
+  await mkdir(args.outputDirectory);
+  for (const file of files) await writeFile(join(args.outputDirectory, file.fileName), file.content, { encoding: "utf8", flag: "wx" });
+  return {
+    ok: true,
+    directory: args.outputDirectory,
+    revision: first.revision,
+    exportId: first.exportId,
+    assetBaseUrl: first.assetBaseUrl,
+    files: files.map((f) => ({ fileName: f.fileName, path: join(args.outputDirectory, f.fileName), bytes: Buffer.byteLength(f.content) })),
+    htmlPath: join(args.outputDirectory, first.html.fileName),
+    note: "The HTML starts from configured defaults and loads supporting assets from the site. It requires network access. No program was executed."
+  };
 }
 
 // src/server.ts
 var PACKAGE_NAME = "yichus-mcp";
-var PACKAGE_VERSION = "0.1.0";
+var PACKAGE_VERSION = "0.1.1";
 function createYichusMcpServer(options = {}) {
   const baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://yich.us");
   const bridgeOverrides = options.bridgeOverrides ?? {};
-  const server = new LocalRelayMcpServer({
+  const bridge = new PageAnswerBridge({
+    host: bridgeOverrides.host,
+    port: bridgeOverrides.port,
+    label: bridgeOverrides.label ?? "Yichus",
+    // The pair every page hints the widget (web/webmcp-autocomplete.js,
+    // the generated calculators); the widget rejects any other hello.
+    workspace: bridgeOverrides.workspace ?? "yichus",
+    relayId: bridgeOverrides.relayId ?? "yichus",
+    allowedOrigins: [baseUrl],
+    // Cold browser compilation can outlast the relay's 25-second default.
+    // Keep a deadline so an unresponsive tab still fails explicitly.
+    invokeTimeoutMs: 12e4
+  }, new FirstTabNamingRegistry());
+  const server = new CoalescingRelayServer({
     serverName: PACKAGE_NAME,
     serverVersion: PACKAGE_VERSION,
-    bridgeOptions: {
-      host: bridgeOverrides.host,
-      port: bridgeOverrides.port,
-      label: bridgeOverrides.label ?? "Yichus",
-      // The pair every page hints the widget (web/webmcp-autocomplete.js,
-      // the generated calculators); the widget rejects any other hello.
-      workspace: bridgeOverrides.workspace ?? "yichus",
-      relayId: bridgeOverrides.relayId ?? "yichus",
-      allowedOrigins: [baseUrl]
-    }
-  });
+    bridge
+  }, TOOL_LIST_CHANGED_WINDOW_MS);
   registerYichusTools(server, { baseUrl, disableOpener: options.disableOpener ?? false });
+  answerRefusalsAsThePageWroteThem(server, bridge);
   return server;
 }
-function asInternal(server) {
-  return server;
-}
+var TOOL_LIST_CHANGED_WINDOW_MS = 100;
+var isFunction = (field) => typeof field === "function";
+var StaticToolFields = z2.object({
+  mcpServer: z2.object({
+    registerTool: z2.custom(isFunction),
+    // The MCP SDK's record of each registered tool; the relay's
+    // webmcp_call_tool is wrapped there (answerRefusalsAsThePageWroteThem).
+    _registeredTools: z2.object({ webmcp_call_tool: z2.object({ handler: z2.custom(isFunction) }) })
+  }),
+  staticToolData: z2.instanceof(Map)
+});
+var StaticToolHost = z2.custom(
+  (value) => StaticToolFields.safeParse(value).success,
+  { error: "@mcp-b/webmcp-local-relay no longer has mcpServer.registerTool, a registered webmcp_call_tool handler and staticToolData" }
+);
 function registerYichusTools(server, ctx) {
-  const internal = asInternal(server);
-  registerStatic(internal, {
+  const host = StaticToolHost.parse(server);
+  registerStatic(host, {
+    name: "yichus_save_calculator",
+    description: "Save a browser-compiled example and its Bosatsu sources to a NEW local directory. Pass the public yichus_example_export tool name for the intended tab and its current source revision. Transfers bounded chunks internally and returns file paths, not generated HTML. Does not execute the program. Requires the browser tab to stay open.",
+    annotations: { readOnlyHint: false, destructiveHint: false },
+    input: saveCalculatorInput,
+    handler: async (args) => {
+      try {
+        const payload = await saveCalculator(args, (name, params) => server.bridge.invokeTool(name, params));
+        return { content: [{ type: "text", text: JSON.stringify(payload) }], structuredContent: payload };
+      } catch (error) {
+        return { isError: true, content: [{ type: "text", text: String(error) }] };
+      }
+    }
+  });
+  registerStatic(host, {
     name: "yichus_list_calculators",
     description: "List the curated Yichus calculator demos and the playground editor available on the configured Yichus origin. Returns a slug, title, description, and absolute URL for each.",
     annotations: { readOnlyHint: true, idempotentHint: true },
-    inputSchemaJson: { type: "object", properties: {}, additionalProperties: false },
-    inputSchemaZod: {},
+    input: z2.object({}),
     handler: async () => {
       const entries = listCalculators().map((calc) => ({
         slug: calc.slug,
@@ -220,24 +457,16 @@ function registerYichusTools(server, ctx) {
       };
     }
   });
-  registerStatic(internal, {
+  registerStatic(host, {
     name: "yichus_open_calculator",
     description: "Open a curated Yichus calculator (or the playground) in the user's default browser with WebMCP enabled (?webmcp=1). After opening, the relay tools below will see the page's tools (yichus_list_inputs, yichus_set_inputs, yichus_list_outputs, yichus_explain_output for calculators; yichus_playground_* for the playground). Use yichus_list_calculators to discover slugs.",
     annotations: { openWorldHint: true },
-    inputSchemaJson: {
-      type: "object",
-      properties: {
-        slug: {
-          type: "string",
-          description: 'Calculator slug from yichus_list_calculators (for example "loan", "investment", "tax", "playground").'
-        }
-      },
-      required: ["slug"],
-      additionalProperties: false
-    },
-    inputSchemaZod: { slug: z.string() },
-    handler: async (rawArgs) => {
-      const args = z.object({ slug: z.string() }).parse(rawArgs);
+    input: z2.object({
+      slug: z2.string().describe(
+        'Calculator slug from yichus_list_calculators (for example "loan", "investment", "tax", "playground").'
+      )
+    }),
+    handler: async (args) => {
       const calc = findCalculator(args.slug);
       if (!calc) {
         const known = listCalculators().map((c) => c.slug).join(", ");
@@ -252,10 +481,7 @@ function registerYichusTools(server, ctx) {
         };
       }
       const url = withWebMcpFlag(calculatorUrl(calc, ctx.baseUrl));
-      let opener = null;
-      if (!ctx.disableOpener) {
-        opener = openUrlInBrowser(url);
-      }
+      const attempt = ctx.disableOpener ? null : await openUrlInBrowser(url);
       const payload = {
         calculator: {
           slug: calc.slug,
@@ -263,35 +489,39 @@ function registerYichusTools(server, ctx) {
           description: calc.description
         },
         url,
-        opened: !ctx.disableOpener,
-        opener
+        opened: attempt?.opened ?? false,
+        opener: attempt && { command: attempt.command, args: attempt.args },
+        ...attempt?.error === void 0 ? {} : { openerError: attempt.error }
       };
       return {
-        content: [
-          {
-            type: "text",
-            text: ctx.disableOpener ? `Would open ${calc.title} at ${url} (browser opener disabled).` : `Opening ${calc.title} at ${url}.`
-          }
-        ],
+        content: [{ type: "text", text: openAnswer(calc, url, attempt) }],
         structuredContent: payload
       };
     }
   });
 }
-function registerStatic(internal, spec) {
-  const config = {
-    description: spec.description,
-    inputSchema: spec.inputSchemaZod
+function openAnswer(calc, url, attempt) {
+  if (attempt === null) return `Would open ${calc.title} at ${url} (browser opener disabled).`;
+  if (attempt.opened) return `Opening ${calc.title} at ${url}.`;
+  return `Could not open a browser on this machine (${attempt.error}). Open this link in a browser yourself to load ${calc.title}: ${url}`;
+}
+function answerRefusalsAsThePageWroteThem(server, bridge) {
+  const callTool = StaticToolHost.parse(server).mcpServer._registeredTools.webmcp_call_tool;
+  const relayHandler = callTool.handler;
+  callTool.handler = async (...call) => {
+    const result = await relayHandler(...call);
+    const page = bridge.pageAnswer(result);
+    return result.isError === true && page !== void 0 ? { ...result, content: page } : result;
   };
-  if (spec.annotations && Object.keys(spec.annotations).length > 0) {
-    config.annotations = spec.annotations;
-  }
-  internal.mcpServer.registerTool(spec.name, config, spec.handler);
-  internal.staticToolData.set(spec.name, {
-    name: spec.name,
-    description: spec.description,
-    inputSchema: spec.inputSchemaJson,
-    ...spec.annotations && Object.keys(spec.annotations).length > 0 ? { annotations: spec.annotations } : {}
+}
+function registerStatic(host, spec) {
+  const { name, description, annotations, input, handler } = spec;
+  host.mcpServer.registerTool(name, { description, inputSchema: input.shape, annotations }, handler);
+  host.staticToolData.set(name, {
+    name,
+    description,
+    inputSchema: z2.toJSONSchema(input, { unrepresentable: "any" }),
+    annotations
   });
 }
 function normalizeBaseUrl(raw) {
@@ -299,59 +529,37 @@ function normalizeBaseUrl(raw) {
 }
 
 // src/cli.ts
+var Port = z3.coerce.number().int().min(1).max(65535);
 function parseFlags(argv) {
-  const flags = {};
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    const next = () => {
-      const value = argv[i + 1];
-      if (value === void 0) {
-        throw new Error(`Missing value for ${arg}`);
-      }
-      i += 1;
-      return value;
-    };
-    switch (arg) {
-      case "--base-url":
-        flags.baseUrl = next();
-        break;
-      case "--host":
-        flags.host = next();
-        break;
-      case "--port": {
-        const value = next();
-        const parsed = Number.parseInt(value, 10);
-        if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
-          throw new Error(`Invalid --port value: ${value}`);
-        }
-        flags.port = parsed;
-        break;
-      }
-      case "--label":
-        flags.label = next();
-        break;
-      case "--workspace":
-        flags.workspace = next();
-        break;
-      case "--relay-id":
-        flags.relayId = next();
-        break;
-      case "--help":
-      case "-h":
-        printHelp();
-        process.exit(0);
-      // eslint-disable-next-line no-fallthrough
-      default:
-        throw new Error(`Unknown flag: ${arg}`);
-    }
+  const { values } = parseArgs({ args: argv, strict: true, options: {
+    "base-url": { type: "string" },
+    host: { type: "string" },
+    port: { type: "string" },
+    label: { type: "string" },
+    workspace: { type: "string" },
+    "relay-id": { type: "string" },
+    help: { type: "boolean", short: "h" }
+  } });
+  if (values.help) {
+    printHelp();
+    process.exit(0);
   }
-  return flags;
+  const port = values.port === void 0 ? void 0 : Port.safeParse(values.port);
+  if (port && !port.success) throw new Error(`Invalid --port value: ${values.port}`);
+  return {
+    baseUrl: values["base-url"],
+    host: values.host,
+    port: port?.data,
+    label: values.label,
+    workspace: values.workspace,
+    relayId: values["relay-id"]
+  };
 }
 function printHelp() {
   process.stdout.write(`yichus-mcp [options]
 
-Yichus MCP server: bundles the WebMCP local relay with two extra static
-tools (yichus_list_calculators, yichus_open_calculator) so an MCP client
+Yichus MCP server: bundles the WebMCP local relay with three static tools
+(yichus_list_calculators, yichus_open_calculator, yichus_save_calculator) so an MCP client
 can drive any deployed Yichus calculator end to end.
 
 Options:
@@ -369,13 +577,14 @@ Options:
                  built to hint the same values.
   --help, -h     Show this help.
 
-Add to your MCP client config (Claude Desktop, Cursor, etc.):
+Build from the checkout: pnpm install && pnpm run yichus-mcp:build
+Then add to your MCP client config (replace the absolute checkout path):
 
   {
     "mcpServers": {
       "yichus": {
-        "command": "npx",
-        "args": ["-y", "@yichus/mcp"]
+        "command": "node",
+        "args": ["/absolute/path/to/yichus/packages/yichus-mcp/dist/cli.js"]
       }
     }
   }