Use Lispex with an AI Assistant

Before you connect

Install the Native product from Downloads and check it:

lispex --version

The MCP server is part of that executable. Reference, evaluation, diagnostics, and the built-in tree/Rust comparison need no repository checkout, Node package, network service, route companion, or API key.

Add the server

In an assistant that accepts an MCP command, add this local stdio server:

{
  "mcpServers": {
    "lispex": {
      "command": "lispex",
      "args": ["mcp", "serve"]
    }
  }
}

The exact settings filename differs between assistants. The important contract is the command and arguments: lispex mcp serve. Do not add a URL, workspace root, source path, or route path.

After reconnecting, the assistant should see exactly four tools:

• lispex_reference checks forms, procedures, reader spellings, resources, and the route overview.
• lispex_eval runs bounded source with the built-in Rust tree reference.
• lispex_diagnostic explains one exact diagnostic code such as E302.
• lispex_compare_routes runs one named closed comparison court and reports agreement or disagreement without choosing an answer.

A useful first request

Ask:

Use the Lispex tools. Check that if is admitted, write a rule that returns approve when the input is at least 10 and review otherwise, run it with input 12, and repair any diagnostic before answering.

The assistant can confirm the form, evaluate the program, and use the diagnostic catalog if its first attempt is wrong. This is more reliable than asking it to remember a Scheme dialect: Lispex requires an else arm on if, has no #; datum comment, and treats only #f as false.

What leaves your machine

Nothing is sent by the Lispex server over a network. It uses local stdio and grants submitted programs no file, clock, random, network, database, or host callback capability. The server returns a source hash, observations, and diagnostics; it does not return, log, cache, or retain the submitted source.

The surrounding assistant application has its own data policy. If the assistant itself is remote, text you type into that application may still be sent to its provider. The Lispex server neither adds nor hides that fact.

Compare execution routes

The built-in court needs no setup:

{
  "court": "tree-rust",
  "source": "(+ input 1)",
  "input": "41"
}

It compares the tree reference and Rust VM over the same source, input, Core IR, bytecode, and resource request. The two optional courts require exact companion products selected when the server starts:

{
  "command": "lispex",
  "args": [
    "mcp", "serve",
    "--topaz-vm", "/absolute/path/to/topaz-vm",
    "--topaz-compiler", "/absolute/path/to/topaz-compiler",
    "--rust-tools", "/absolute/path/to/rust-tools"
  ]
}

Then rust-topaz compares the two VMs, while all-four adds the tree route and a fresh AOT product built only for that request. A missing companion makes the requested court unavailable. It never turns all-four into a smaller comparison.

Limits and honest failures

One request admits at most 65,536 source bytes and 16,384 input bytes. Evaluation has a 1 MiB result and five-second wall-clock bound. Route comparison has a 4 MiB result bound; all-four has a bounded eleven-minute window because it builds a fresh compiled product. The language's fixed transition and control limits still apply. Timeout, cancellation, malformed input, unavailable courts, build failure, cleanup failure, and an unknown tool remain visible.

The server validates optional products only from the absolute startup paths. It never discovers, installs, repairs, substitutes, retries, or falls back to another route. Comparison results are authoring observations, not Vouch evidence, a gate grant, or a proof of semantic equivalence.

Verify the installed loop

After setup, give the assistant this short request:

List the Lispex tools. Confirm that if and + exist and that eval does not. Run (+ input 1) with input 41, explain any diagnostic by its code, then compare the same program with tree-rust.

A complete installation reports exactly four tools, returns 42, and reports the two-route court as completed. If an optional court is unavailable, the result has no attempted routes. If routes disagree, the result says agreement: false while partial_comparison and answer_selected remain false. That is the intended result: the assistant reports the disagreement instead of choosing a convenient answer.

Stop the MCP client or disconnect the server when you finish. Stdio closure ends the local process; there is no background service or retained project state to clean up.

Next

Keep the MCP Tool Reference open when building an integration. For ordinary language learning, return to the Learning Path.