Guide

Connect your agent

Pick the job; each route names the one package it needs.

Check a program

@yichus/api-mcp, the Node engine server (not the @yichus/mcp browser relay), runs the engine in Node 20+, with no Java or build step. Check that it starts:

npx -y -p @yichus/api-mcp@0.1.11 yichus-api-mcp --help

Put this entry in your MCP client’s configuration:

{
  "mcpServers": {
    "yichus-api": {
      "command": "npx",
      "args": ["-y", "-p", "@yichus/api-mcp@0.1.11", "yichus-api-mcp"]
    }
  }
}

Restart the client, list its tools, and call api_guide. If the process exits, run the configured command in a terminal and resolve its startup error. Check the Node version and that npx is on the client’s path.

Local Lean proof host

Install the pinned slim Lean WebAssembly release in a new private directory and start the npm API MCP server with it. It needs nothing beyond npm:

npx -y -p @yichus/api-mcp@0.1.11 yichus-lean-wasm-install \
  --output /absolute/private/lean-wasm
npx -y -p @yichus/api-mcp@0.1.11 yichus-api-mcp \
  --lean-wasm-root /absolute/private/lean-wasm

Node runs the supported Bool and structural list translations. Its receipt is a distinct lean-wasm-law-run: Lean accepted the generated theorems and the axiom audit, while independentKernelReplay is false. Read the method and completion fields before describing a result; unsupported laws and FiniteObligation remain inconclusive. The Node command-line equivalent is yichus lean FILE --lean-wasm-root DIRECTORY.

The configured toolchain is a trusted local input. The checker hashes it before and after each run, but a concurrent writer to its directory can defeat that check; keep that installation private and immutable while proving. A receipt must be rechecked against current sources for a later build.

Work in a live app page

The tools run in your tab, so you watch the map, evaluations and app while the agent works. For a first project, use the QuickStart.

Browsers with native site tools

For Lean proofs, open the Lean Wasm page directly and wait for its ready status. Its isolated worker requires shared memory and may reload once. The runtime is downloaded on the first proof. The regular workbench below continues to offer the other catalog tools.

In Codex’s built-in browser, open api-mcp.html as the top-level page and wait for the catalog-ready status. Select Site tools in the address bar, then Available site tools, and ask the agent to call api_guide. No MCP server configuration or ?webmcp=1 is needed for this route. Keep the tab open.

Yichus registers on document.modelContext when supported, otherwise navigator.modelContext. When both are present, the document registry takes precedence over the navigator polyfill. Codex currently discovers tools only in the top-level document: a hosting viewer that embeds this page in an iframe hides its tools. Serve the page directly, including from localhost during development. See the official site-tools documentation for availability and browser permissions.

For private pages hosted on Valet, add __valet_webmcp=1 to the normal artifact URL. Valet's direct mode places the artifact at the top level on its isolated content origin while retaining authentication. This is distinct from Yichus's webmcp=1 relay flag below. See Valet's WebMCP guide.

Any other browser: the local relay

To call api_lean_check through the relay, open the Lean Wasm page with WebMCP enabled and discover its registered source. The steps below use the main workbench for the other tools.

  1. Configure a compatible WebMCP host or the @yichus/mcp browser relay in your MCP client.
  2. Open the workbench with WebMCP enabled and wait for its ready status.
  3. Through the local relay, call webmcp_list_sources, then webmcp_list_tools. Match each tool’s sources to this tab and call its returned public name (which may have a tab suffix). It is registered as yichus-api-mcp.
  4. Call api_guide through the discovered tool. A returned guide confirms that the engine and connection both work.

An ordinary browser tab cannot receive MCP calls by itself. It needs a host that supports native site tools or the relay. Keep the tab open while the agent works.

Add the local relay to your client

With Node 20+ installed, add this entry to your MCP client’s configuration. The client starts the relay with npx:

{
  "mcpServers": {
    "yichus-browser": {
      "command": "npx",
      "args": ["-y", "@yichus/mcp@0.1.4"]
    }
  }
}

Restart the client and repeat the discovery check above. The relay’s README documents origin and local-development options.

If the tab is missing: confirm ?webmcp=1 is in its URL, leave it open, and reconnect the client to the relay. If the engine fails to load: reload the page before retrying discovery.

What changes on the page

For a ready-made starting point, use a tool request from the before-and-after examples. Each request includes its complete source. The request’s sources field is an array of file objects. Use the types in the tool schema for its other parameters.

App testing tools
TaskPage tools
List views and call a routeyichus_app_views, yichus_app_call
Inspect stored rowsyichus_app_rows
Interrupt writes and restartyichus_app_crash_after_writes, yichus_app_restart
Exercise token verificationyichus_app_mint_token, yichus_app_set_token

The page tools have their own schemas. yichus_app_open currently takes sources as a JSON-encoded string and string-valued options; the catalog’s api_frontend takes a native source array. Route calls take a path and JSON arguments. The dev adapter uses user_id; the bearer adapter verifies the configured token. The page’s test issuer can mint valid, expired, forged, and unknown-key tokens. A memory store is lost on restart; local:<name> stores table data in localStorage. These tools require a page and are not part of the Node catalog.

Build or port an app

Add the studio to your agent once; it asks you the product questions and checks the app after every change.

claude mcp add yichus -- npx -y yichus@0.3.9 studio

Setup for other agents

How the pieces fit

Both the engine server and the browser page run the same checked Yichus/Mcp::catalog; the page adds its own yichus_app_* tools. The relay must run on the same computer as the tab; the engine server runs wherever Node does.

The main browser workbench runs the pure engine. For browser proof checks, open the dedicated isolated Lean Wasm page. It exposes api_lean_check through WebMCP, compiles the supplied Bosatsu source in the shared engine, and runs pinned Lean in a browser worker. Its source-bound local receipt records that independent native leanchecker replay was not run.

Experimental, not yet released: JVM hosts for TLC and Lean

Both hosts need the Yichus fat JAR, which is not distributed yet.

TLC host

api_tlc_check checks the same protocol case as api_protocol_check with pinned TLC 1.7.4. You need Java 17, the JVM Yichus fat JAR and the pinned tla2tools.jar. Its sha256 is 936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88, and nixpkgs' tlaplus 1.7.4 ships exactly this file. Start the npm API MCP server with both flags:

npx -y -p @yichus/api-mcp@0.1.11 yichus-api-mcp \
  --tlc-host /absolute/path/to/yichus.jar \
  --tlc-jar /absolute/path/to/tla2tools.jar

The host lowers the compiled handlers to a TLA+ module and runs TLC once for the safety invariants and once for each required witness. It reports a counterexample only after the native scheduler replays its schedule to the same violation. Without a host, the tool answers errorKind: host-not-configured, as the browser does. The command-line equivalent is yichus tlc --case case.json --tlc-jar tla2tools.jar files.bosatsu.

JVM Lean host

The JVM host needs Java 17, the fat JAR and the pinned Lean toolchain in a private, read-only location. Start the npm API MCP server with both --proof-host /absolute/path/to/yichus.jar and --lean-toolchain /absolute/path/to/lean. The host checks exact source bytes in a supervised worker and returns a compact, source-bound local-run view by default. Pass its fullReceiptSha256 back as receipt_sha256 to the same server to fetch the exact full receipt; compact rows distinguish a law the translator did not admit from a generated proof that was not verified. Neither is a proof or a counterexample. The server retains a bounded in-memory cache, so a cache miss requires a fresh check. The full receipt carries diagnostic reasons omitted from the compact view. The digest names this host's exact output bytes, so use it with the host that produced it. This method covers direct Bool laws and the documented structural List[Bool] law and witness, and it separately replays with leanchecker.

Set JAVA_HOME to the absolute Java 17 installation. The server runs that installation's bin/java instead of resolving a java command through PATH.

npx -y -p @yichus/api-mcp@0.1.11 yichus-api-mcp \
  --proof-host /absolute/path/to/yichus.jar \
  --lean-toolchain /private/read-only/lean

Where the source goes

The browser performs analysis in the tab and gives the checker no filesystem access. Source arguments and results pass through the relay to your MCP client and agent; Yichus does not upload them to a hosted checker. The Node route sends the same data between the client and local process over stdio.

Follow the inspect–edit–recheck workflow · Tool catalog

Where this fits

What this is about: How the pieces fit