MCP Server

How it works

• Transport: a hand-rolled, zero-dependency JSON-RPC 2.0 session over stdio, with newline-delimited messages per the 2025-06-18 MCP specification.
• Clean streams: stdout carries protocol messages only; logs go to stderr, so nothing a tool does can corrupt the session.
• In-process: compiles and builds run inside the server using the installed compiler — the same code paths as wizz build.
• Dual output: every tool returns human-readable text plus a structuredContent JSON payload for programmatic use.

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18",...}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},...}}
→ {"jsonrpc":"2.0","method":"notifications/initialized"}
→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"build_project","arguments":{}}}

Registering the server

Any MCP client that supports stdio servers can launch it:

{
  "command": "wizz",
  "args": ["mcp", "--root", "/path/to/project", "--allow-write"]
}

This documentation site is developed with the server running inside WSL, registered in the project's .mcp.json:

{
  "mcpServers": {
    "wizz": {
      "type": "stdio",
      "command": "wsl.exe",
      "args": [
        "-d", "Ubuntu", "--",
        "/home/you/.local/bin/wizz", "mcp",
        "--root", "/mnt/c/Users/you/Develop/wizz-documentation",
        "--allow-write"
      ]
    }
  }
}

The six tools

project_overview

Surveys the application. Start every session here.

{ "inputDirectory": "src" }   // optional, default "src"

{
  "root": "/mnt/c/Users/dunca/Develop/wizz-documentation",
  "inputDirectory": "src",
  "versions": { "compiler": "1.17.0", "syntax": "1.4.1", "output": "1.8.2" },
  "documentShell": true,
  "distPresent": true,
  "adapters": ["node"],
  "components": [
    { "file": "App.wizz", "route": "/" },
    { "file": "pages/docs/routing.wizz", "route": "/docs/routing" }
  ],
  "apiRoutes": [{ "routePath": "/api/greet", "filePath": "server/api/greet.js" }]
}

component_diagnostics

Compiles without writing anything and returns WIZZ-P/WIZZ-G records. Targets exactly one of a project file, inline source, or every component.

// exactly one target:
{ "path": "src/components/Toc.wizz" }
{ "source": "<main><p>{f()}</p></main>", "path": "src/Probe.wizz" }   // path labels inline source
{ "all": true, "inputDirectory": "src" }

{
  "target": "src/Probe.wizz",
  "ok": false,
  "diagnostics": [{
    "code": "WIZZ-P033",
    "severity": "error",
    "message": "Template Expression Error at src/Probe.wizz:1:13 - Unexpected token (",
    "file": "src/Probe.wizz",
    "line": 1,
    "column": 13
  }]
}

build_project

Runs the wizz build equivalent in-process with a silent logger and returns the wizz-build-diagnostics@1 envelope plus compiled/failed counts.

{ "inputDirectory": "src", "outputDirectory": "dist", "adapter": "node" }   // all optional

{
  "format": "wizz-build-diagnostics@1",
  "ok": true,
  "compiledCount": 24,
  "failedCount": 0,
  "diagnostics": [],
  "files": [
    { "file": "App.wizz", "serverRenderable": true },
    { "file": "components/TopNav.wizz", "serverRenderable": true }
  ]
}

language_contract

Takes no arguments. Returns the component language contract as text — file structure, the reactive script boundary, the expression subset, directives, imports and props, and the stable diagnostic codes — with the version triple as structured data. The text ships inline in the CLI, so it can never drift from the installed compiler.

dev_workflow

Takes no arguments. Returns the real commands and defaults for wizz init, dev, build, the node adapter deploy recipe, API routes, the .env.server rule, and the update flow.

create_or_update_component

Creates or replaces a .wizz file — but only after the proposed source compiles. A failing source is refused with its diagnostic records echoed, and the target is left byte-identical.

{
  "path": "src/components/Badge.wizz",
  "source": "<script>\n  export let label = \"New\";\n</script>\n\n<span class=\"badge\">{label}</span>\n",
  "overwrite": false
}

• Requires the server to be started with --allow-write; otherwise it refuses with guidance.
• Targets must end in .wizz and stay inside the root, outside dist/, node_modules/, .git/, release/, and vscode-extension/.
• overwrite defaults to false; sources cap at 256 KiB.

A typical agent loop

1. Orient with project_overview, then read language_contract before authoring.
2. Draft a component and check it with component_diagnostics using inline source.
3. Fix by switching on the diagnostic code and its line/column — never by parsing prose.
4. Write with create_or_update_component; it re-runs the compile gate.
5. Verify the whole project with build_project and check serverRenderable for each file.

Security model

• Fixed root: set by --root (default: the startup directory) and never changeable over the wire. Every path is checked lexically and through the real filesystem, so symlinks cannot escape.
• Opt-in writes: --allow-write is required, and every write is compile-gated.
• Race-hardened writes: the target opens with O_NOFOLLOW and its parent directory is re-verified against its realpath immediately before and after the open.
• Bounded work: every compile of agent- or project-supplied source caps at 256 KiB, and parser depth budgets (WIZZ-P053/P054) turn pathological nesting into diagnostics instead of stack overflows.
• Untrusted input: __proto__ keys are stripped at parse time and message lines cap at 2 MiB.