The compiler is an API.

Connect any agent: astra mcp v0.13

astra mcp serves the whole toolchain over the Model Context Protocol, so any MCP client can call it, whichever model drives it.

Its tools are verify, fix, run, build, format, explain and test, and each answers with exactly the JSON the matching command prints. Programs run in a separate process with a time limit and capped output, and paths outside the folder the server started in are refused. The model reads the developer guide once, from the resource astra://guide; astra://errors lists every code.

The commands an agent calls

An agent needs only these commands, each with a stable exit code.

Rust callers can skip the CLI entirely:

let report = astra::compiler::verify(source);
let result = astra::compiler::compile_to_result(source);

The diagnostic JSON shape

One object per invocation. Fields are stable; new fields may be added, existing ones are never repurposed.

{
  "success": false,
  "diagnostics": [
    {
      "phase": "typecheck",       // "parse" | "typecheck" | "codegen"
      "kind": "TypeError",        // coarse class
      "error_code": "E0002",      // stable, catalogue below
      "message": "Type error: Undefined variable 'total'",
      "file": null,
      "line": 4,                  // 1-based; null if unresolvable
      "column": 12,               // 1-based; null if unresolvable
      "severity": "error",
      "suggestion": "Declare 'total' with let before use, e.g. let total = ...;"
    }
  ]
}

• Parse errors always carry line and column of the offending token.
• Typecheck errors: every type error in the main file carries the line and column of the statement that raised it (human output ends with (line N, column M)); a function reports all of its independent errors in one run, not just the first; capability errors (E0014) point at the offending built-in call. Errors in imported modules and in function signatures still have no line (null, never 0).
• suggestion is a human/LLM-readable repair hint, name-aware where possible.
• Success shape: {"success": true, "diagnostics": []}.

Machine-applicable fixes v0.12

When the repair is unambiguous, a diagnostic also carries a fix: text edits that repair the error without an LLM call. Each edit replaces the text from line/column up to, not including, end_line/end_column (1-based) with text. This is real output from main:

{
  "phase": "typecheck",
  "error_code": "E0002",
  "message": "Type error: Undefined variable 'totl'; did you mean 'total'?",
  "line": 4,
  "column": 17,
  "fix": {
    "edits": [
      { "line": 4, "column": 17, "end_line": 4, "end_column": 21, "text": "total" }
    ]
  }
}

• Fixed since v0.12: misspelt variable and function names (E0002, E0003) and a missing or extra mut at a call (E0022).
• Next: a missing match arm (E0021) and a missing trait method (E0020).
• No fix field means no unambiguous repair is known; hand the diagnostic to the model as before.

Canonical integration pattern

The whole integration is one loop: generate, verify, repair from the JSON, then compile.

# pseudocode for any agent framework
source = llm.generate(task)

for attempt in 1..MAX_REPAIRS:
    report = run("astra verify --error-format=json", source)
    if report.success:
        break                                # verified, safe to compile
    source = llm.repair(source, report.diagnostics)
                                             # feed error_code + line +
                                             # column + suggestion back in

binary = run("astra compile --error-format=json", source)
execute(binary)                              # native, already typechecked

Apply the compiler's own fixes first, and spend a model call only on what remains:

for attempt in 1..MAX_REPAIRS:
    report = run("astra verify --error-format=json", source)
    if report.success:
        break
    if any(d.fix for d in report.diagnostics):
        run("astra fix", source)          # apply edits, re-verify, repeat
        continue                             # no LLM call for these errors
    source = llm.repair(source, report.diagnostics)

Why this converges better than a Python retry loop:

• Diagnostics are positional: the model repairs one pinpointed line instead of regenerating the file.
• Codes are categorical: frameworks can route E0002 to the compiler's own fix and reserve the LLM for E0004/E0011.
• Verification takes 4–5 ms: cheaper than any token round-trip, so verify after every single edit.
• Whole error classes cannot escape to runtime, so the expensive failure mode (bad code executing) is structurally removed.

Stable error codes

Codes are permanent identifiers, safe to branch on, cache repair strategies against, or fine-tune with. astra explain E#### returns the long-form description for any of them.

Runtime error codes v0.13

When a program stops with an error, astra run --error-format=json, the run tool of astra mcp and the playground all report one of these.