Setup

The server is a standalone Node CLI distributed on npm. Add it to your IDE’s MCP config — there is no project install required, and npx fetches it on demand. It requires Node 18 or newer.

Connect it to your IDE

Claude Code

Register it with one command:

claude mcp add golemui -- npx -y @golemui/gui-mcp

Or paste this into ~/.claude/settings.json (or your project’s .mcp.json):

{
  "mcpServers": {
    "golemui": {
      "command": "npx",
      "args": ["-y", "@golemui/gui-mcp"]
    }
  }
}

Cursor / Windsurf

Add an mcpServers.golemui entry pointing at npx -y @golemui/gui-mcp in your editor’s MCP config:

{
  "mcpServers": {
    "golemui": {
      "command": "npx",
      "args": ["-y", "@golemui/gui-mcp"]
    }
  }
}

VS Code (project)

Create or edit a project-level .mcp.json in your workspace root, then reload the window (Cmd+Shift+P → “Developer: Reload Window”):

{
  "mcpServers": {
    "golemui": {
      "command": "npx",
      "args": ["-y", "@golemui/gui-mcp"]
    }
  }
}

All eight tools appear in your assistant’s tool list once the server is connected.

Verify

The server speaks JSON-RPC over stdio and prints a ready line to stderr on startup:

npx -y @golemui/gui-mcp < /dev/null
# → @golemui/gui-mcp v<version> ready on stdio

Tip

On connect, the server hands your assistant a short set of instructions describing the generate-then-validate workflow, so it uses the tools in the right order automatically. You don’t need to prompt it with the workflow yourself.

CLI subcommands (no MCP client needed)

The two verification tools are also plain subcommands of the same bin, so any shell — a CI step, a git hook, or an AI agent without an MCP connector (for example, one following the GolemUI agent skill) — can verify a form:

npx -y @golemui/gui-mcp validate-json signup-form.json  # JSON definition → bundled schemas
npx -y @golemui/gui-mcp check-dx src/forms/signup.ts    # gui.* code → real @golemui types
npx -y @golemui/gui-mcp --help

Each prints a single JSON result on stdout — the same shape as the corresponding MCP tool (json_validate_form_definition / dx_check_code) — and exits 0 on pass, 1 when problems were found, 2 on a usage or file error. With no subcommand, the bin starts the MCP server on stdio as before.

The package is self-contained (it bundles the schemas and the @golemui type declarations), so both commands work even before GolemUI is installed in the project.

Note

Corporate / restricted environments: where the shell cannot reach the public registry at run time, install the package as a devDependency instead — npm i -D @golemui/gui-mcp. The same npx commands then resolve the project-local bin with no network at run time, and verification rides your normal dependency pipeline (registry mirror, lockfile pinning, security scanning).

Pin a version (optional)

npx -y @golemui/gui-mcp always fetches the latest release. To lock the bundled schemas to a specific GolemUI version, pin the package:

{
  "mcpServers": {
    "golemui": {
      "command": "npx",
      "args": ["-y", "@golemui/gui-mcp@1.2.3"]
    }
  }
}