Guide
Connect your agent
Pick the job; each route names the one package it needs.
- Check a program: the Node engine server.
- Work in a live app page: your browser tab and, if needed, the relay.
- Build or port an app: install the studio.
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.
- Configure a compatible WebMCP host or the
@yichus/mcpbrowser relay in your MCP client. - Open the workbench with WebMCP enabled and wait for its ready status.
- Through the local relay, call
webmcp_list_sources, thenwebmcp_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 asyichus-api-mcp. - Call
api_guidethrough 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
api_abstraction_mapdraws the supplied program’s dependency map.api_whyfills the evaluator with its inputs, output, and evidence.api_organizereturns a text lens;lens: "stack"also draws the engine’s stack picture.yichus_app_open, a page tool not in the Node server, runs a generated app that you can also use.
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
| Task | Page tools |
|---|---|
| List views and call a route | yichus_app_views, yichus_app_call |
| Inspect stored rows | yichus_app_rows |
| Interrupt writes and restart | yichus_app_crash_after_writes, yichus_app_restart |
| Exercise token verification | yichus_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
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