AI Agents and MCP

This page describes Topaz v5.17. Before treating it as current, compare /version.json with version 5.17.

Outcome: point a fetch-capable or tool-enabled assistant at this language.

Prerequisite: none for the first section. The MCP server needs the toolchain installed as described in First Program.

Start with one fetch

For an assistant that can retrieve a URL but has no tools configured, the widest common surface is a single self-contained file.

https://topaz.ooo/agents.md

It carries the shape of a file, the forms, the host/profile boundary, and the section that matters most for a model that already knows other languages: an explicit list of non-forms. It warns against Vec<T>, async, try, class syntax, and treating null as universal absence, while preserving the supported T | null data-boundary form. Naming those distinctions prevents confident guesses from becoming invalid source.

Several machine surfaces sit beside it. https://topaz.ooo/llms.txt is the compact index, while https://topaz.ooo/llms-full.txt contains the complete English manual as plain Markdown. Every English page is also available at https://topaz.ooo/docs/<slug>.md, with its title, source route, and covered specification sections preserved in frontmatter. https://topaz.ooo/version.json states which version answers.

If you are configuring an assistant for someone else, giving it that one URL is the whole setup.

The problem the tools solve

Fetching gets an assistant to correct forms. It does not tell it whether the program it just wrote actually compiles.

An assistant writing an unfamiliar language does one of two things. It reads documentation and guesses, or it writes, gets told exactly what is wrong, and fixes it. The second loop produces working code even when documentation is thin. The first produces confident text that does not compile. A reference alone leaves an assistant in the first loop. A checker moves it to the second.

Three published tools

topaz_check is the tool intended to change outcomes. The published native package returns the compiler's own diagnostic, its code, and its source position, unmodified. It reports the exact installed toolchain and compiler selection that answered. An assistant can repair its output from exact evidence instead of a paraphrase.

Why there is no execution tool yet

Topaz routes observable effects through a host or product-profile boundary. That makes a no-capability execution host practical, but it does not turn the ordinary native CLI into a sandbox: native execution can expose filesystem and I/O operations.

topaz_run is therefore not provided. It needs two independent barriers before it can ship: a proven no-capability Topaz host and an operating-system sandbox that denies network and child processes and exposes only ephemeral submitted source. Ordinary unrestricted topaz run is not an acceptable server boundary.

Isolation is still not resource control. A submitted program can loop, allocate, or print without bound, so every run also needs wall-clock, memory, and output ceilings and must leave no child process behind.

The three-tool package does not execute submitted programs. For checking, it sends bounded source through a fresh installed language-server process, retains and logs no source, and keeps no document state between calls.

Machine-readable descriptor

Clients and crawlers can read the server description directly.

https://topaz.ooo/mcp.json

It lists the three implemented tools, their inputs, the exact standalone native distribution command, the language version, and the check-only safety boundary in structured form. It also marks topaz_run unavailable and states the missing isolation boundary.

Current status

topaz-mcp 0.1.1 is available from the public source and release repository. The first native package supports Apple silicon Macs and requires an installed Topaz 5.16 compiler. Topaz 5.17 does not silently relabel that independently versioned package. A later MCP release must rebuild and reverify its embedded reference set against the current language authority before it can name 5.17. The machine descriptor marks the three check-only tools available and continues to mark topaz_run unavailable.

The installed bounded Lispex evaluator does not change this boundary. It runs one fixed Lispex product contract, not arbitrary submitted Topaz source.

Install and connect

Download the archive and checksum file from the 0.1.1 release, then verify the archive before extracting it.

shasum -a 256 -c SHA256SUMS
tar -xzf topaz-mcp-0.1.1-aarch64-apple-darwin.tar.gz

The archive SHA-256 is a5c58d66024d5583c8dfd1a16b8f45905cb1fc1837b0c20c58f24c37068e5135. Configure a local stdio MCP connection with absolute paths to the extracted server and the installed Topaz executable.

{
  "command": "/absolute/path/to/topaz-mcp",
  "args": ["serve", "--topaz", "/absolute/path/to/topaz", "--compiler", "self"]
}

After connecting, the client must discover exactly topaz_spec, topaz_examples, and topaz_check. The verification block in mcp.json provides a known reference section, example concept, and clean source check so a client can confirm the installed server rather than trusting configuration alone.

An execution-capable distribution remains a later product. It ships only after both isolation barriers and the execution usability test pass: an assistant with no prior exposure, given only that server, writes a small program that checks and runs on its second attempt.

Ready to continue when

You can say what each prepared tool answers, why the useful check-only package can publish without topaz_run, and why future execution still needs both the language host boundary and independent operating-system and resource isolation.

For what a program can and cannot reach, see Interop Boundaries. For the forms an assistant will be looking up, see Syntax at a Glance.