@yichus/mcp 0.1.0 → 0.1.1

package/README.md

@@ -4,45 +4,57 @@ MCP server that exposes the [Yichus](https://yich.us) calculators and the
 in-browser Bosatsu playground to any agent that speaks the Model Context
 Protocol.
 
-It bundles the local WebMCP relay and adds calculator discovery/opening tools.
+It bundles the local WebMCP relay and adds calculator discovery, opening, and saving tools.
 A connected agent works with the same page the user can see: source edits,
 compiler diagnostics, results, and program diagrams.
 
 ## Install and connect
 
-Node 20 or newer. The relay does not need Java.
-
-```sh
-npm install -g @yichus/mcp
-```
-
-Configure your MCP client to launch this stdio server:
+Node 20 or newer; the relay does not need Java. `@yichus/mcp` 0.1.0 is on
+npm. Configure your MCP client to launch it as a stdio server:
 
 ```json
 {
   "mcpServers": {
     "yichus": {
       "command": "npx",
-      "args": ["-y", "@yichus/mcp"]
+      "args": ["-y", "@yichus/mcp@0.1.0"]
     }
   }
 }
 ```
 
-A global install can use `"command": "yichus-mcp"` instead of `npx`.
-
-To work on the relay from a checkout of this repository:
+Version 0.1.0 predates this README, which describes 0.1.1. It has no
+calculator saving tool (`yichus_save_calculator`) and lacks later relay
+fixes. Until 0.1.1 is published, build the current relay from a checkout
+with Node 20+ and pnpm:
 
 ```sh
 pnpm install
 pnpm run yichus-mcp:build
-node packages/yichus-mcp/dist/cli.js
+```
+
+and launch it by your checkout's absolute path:
+
+```json
+{
+  "mcpServers": {
+    "yichus": {
+      "command": "node",
+      "args": ["/absolute/path/to/yichus/packages/yichus-mcp/dist/cli.js"]
+    }
+  }
+}
 ```
 
 Open the desired page with `?webmcp=1`. Keep it open, call
-`webmcp_list_sources`, and select the source id for that tab. Discover its
-schemas with `webmcp_list_tools`, then use `webmcp_call_tool` with `sourceId`,
-`name`, and `arguments`. The relay and browser must run on the same computer.
+`webmcp_list_sources`, and identify that tab. Discover its schemas and public
+tool names with `webmcp_list_tools`, matching each tool's `sources` to the tab.
+Use `webmcp_call_tool` with `name` and `arguments`. The relay and browser must run on the same computer.
+
+The relay waits up to two minutes for a browser tool call, including cold
+compilation. Keep the tab open while it runs. An MCP client may enforce its
+own shorter timeout.
 For a local site, set `--base-url` to the origin you opened.
 
 A browser host with native WebMCP support can call page tools without this
@@ -72,6 +84,9 @@ relay. See [connection instructions](https://yich.us/reference/agent.html).
 - **Standalone calculator**: `yichus_list_inputs`, `yichus_set_inputs`,
   `yichus_list_outputs`, `yichus_explain_output`. These operate the running
   calculator; use an editable source drawer or the editor to change code.
+  An explanation is plain data: the formula in the page's labels, the same
+  formula with current values, the inputs and outputs it reads, and the
+  unlabeled steps in between.
 - **Explorer and state-machine spec editors**: `yichus_autocomplete_*`
   provides suggestions for the user to accept. The user then runs the page's
   checker. These tools do not execute a check themselves. For a complete agent edit/run loop, use page edit/action/feedback below.
@@ -82,7 +97,9 @@ relay. See [connection instructions](https://yich.us/reference/agent.html).
 
 The static `yichus_list_calculators` tool lists curated demo URLs;
 `yichus_open_calculator` opens a chosen slug with the relay flag. The
-`playground` slug opens the standalone calculator editor.
+`playground` slug opens the standalone calculator editor. On a machine with
+no browser opener (a container or headless box) it answers `opened: false`
+with the link for a person to open by hand.
 
 ## Agent editing loop
 
@@ -102,6 +119,46 @@ The user accepts the ghost text with Tab or dismisses it with Escape.
 `yichus_autocomplete_list_editors`, `yichus_autocomplete_get_context`, and
 `yichus_autocomplete_dismiss` support inspection and cancellation.
 
+## Save a browser-compiled calculator
+
+The [agent QuickStart](https://yich.us/start/quickstart.html) walks through a
+calculator change, compilation, Why feedback, and local execution.
+
+Use `webmcp_list_sources` to identify that page, then `webmcp_list_tools`
+to find its tools by their `sources`. Call the returned public `name`:
+when two tabs publish the same tool, the tab the relay saw first keeps
+the plain name and later tabs' copies gain a tab-id suffix. The
+`webmcp_call_tool` arguments are `name` and `arguments`; it does not accept
+a `sourceId` parameter.
+
+After testing the calculator, call the relay's `yichus_save_calculator`
+directly with:
+
+```json
+{
+  "exportToolName": "yichus_example_export",
+  "exampleId": "event_budget",
+  "expectedRevision": 2,
+  "outputDirectory": "/absolute/path/to/project/event-budget"
+}
+```
+
+Substitute the public export tool name and revision you actually read.
+The parent directory must exist; the output directory must not. The tool
+transfers bounded chunks from the browser, pins them to one compilation,
+and validates the complete artifact before creating any files. It saves
+the Bosatsu sources and generated HTML and returns paths and byte sizes,
+keeping generated HTML out of the agent's context. A filesystem write
+failure is reported as an error and may leave a partial new directory;
+the tool never overwrites an existing destination.
+
+Open the HTML or serve its directory with a static server. It starts at
+the configured defaults, and supporting scripts and styles still load
+from the exported site's URL, so internet access is required. The save
+tool does not execute the program. In other browser hosts, use the page's
+**Save calculator HTML** button or implement the paged
+`yichus_example_export` contract (`nextOffset` and `expectedExportId`).
+
 ## CLI
 
 ```text
@@ -135,9 +192,12 @@ node packages/yichus-mcp/dist/cli.js --base-url http://localhost:8000
 This package is a thin yichus-curated wrapper around
 `@mcp-b/webmcp-local-relay`. It does not fork or reimplement the relay;
 it constructs a `LocalRelayMcpServer` from the relay package and registers
-two extra static tools on it. The relay version is pinned exactly so an
-upstream rename of an internal field is a deliberate audit step rather
-than a silent breakage.
+curated discovery, opening, and file-saving tools on it. Tab naming and
+coalesced `tools/list_changed` notices extend the relay's public classes.
+Adding the curated tools uses two fields the relay does not make public;
+the relay version is pinned exactly and those fields are checked when the
+server is made, so an upstream rename fails at startup rather than when an
+agent calls a tool.
 
 For the underlying relay itself (its CLI flags, security model, and
 runtime compatibility), see the