Neon3 AI Authoring MCP

Teach an AI to build Neon3 interfaces correctly, then let Neon3 prove the result.

An MCP server, detailed authoring Skill, and Python/Node starter kit for Neon3. It combines three layers:

Skill                 durable NUI Flow rules and design boundaries
MCP resources/tools   searchable references, live capability discovery, orchestration
Neon3 runtime         authoritative parser, compiler, revision, and renderer feedback

The MCP never invents a second UI language. neon3_nui_validate invokes the production neon-ui-runtime parser/compiler, while live mutations use the existing length-prefixed neon3.rpc contract.

Highlights

Requirements

• Node.js 20 or newer.

• Neon3 checked out at D:\Neon3 on Windows, or NEON3_ROOT set to another checkout.

• Build the Neon3 authoring probe once:

cd D:\Neon3
cargo build -p neon-ui-runtime --bin neon3_authoring_probe

The probe is the compatibility bridge between this MCP package and the exact Neon3 checkout. It returns structured JSONL and uses the same parser/compiler as the running UI runtime.

Install From Source

git clone https://github.com/unco999/neon3-ai-authoring-mcp.git
cd neon3-ai-authoring-mcp
npm install
npm link

The command is now available as neon3-mcp.

Install From npm

Once published:

npm install -g @neon3/ai-authoring-mcp
neon3-mcp

For a pinned local install:

npm install --save-dev @neon3/ai-authoring-mcp
npx neon3-mcp

OpenCode Configuration

Add an MCP entry to your OpenCode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "neon3": {
      "type": "local",
      "command": ["neon3-mcp"],
      "enabled": true,
      "environment": {
        "NEON3_ROOT": "D:\\Neon3",
        "NEON3_UI_ENDPOINT": "127.0.0.1:39102",
        "NEON3_WGPU_ENDPOINT": "127.0.0.1:39103",
        "NEON3_PROJECTD_ENDPOINT": "127.0.0.1:39104"
      }
    }
  }
}

Copy skill/SKILL.md into the host's skill directory, or add this repository as a skill source. The Skill is separate from the MCP server so its authoring rules remain available when Neon3 is offline.

The MCP also exposes the same material as resources:

neon3://skill
neon3://references/overview
neon3://references/grammar
neon3://references/components
neon3://references/statecharts
neon3://references/interactions
neon3://references/diagnostics

Claude Desktop / MCP Clients

{
  "mcpServers": {
    "neon3": {
      "command": "neon3-mcp",
      "env": {
        "NEON3_ROOT": "D:\\Neon3",
        "NEON3_UI_ENDPOINT": "127.0.0.1:39102"
      }
    }
  }
}

Tools

The Authoring Loop

reference -> capabilities -> generate NUI -> validate -> inspect -> submit -> diagnose

Example of valid, typed, semantic NUI:

version 1
surface surface.example revision 1
budget nodes=32 bindings=16 instances=16 text=16 glyphs=1024 events=8 clips=64
input title text default text:empty
input can_save bool default false
surface root column w 520 h 240 gap 8 pad 16
  text heading value $title
  button save value "Save" enabled $can_save event document.save

NUI Flow must not contain fetch, callbacks, Python code, file paths, coordinates, GPU handles, or arbitrary expressions.

Templates

templates/python-app and templates/node-app include:

• neon3.app.json application metadata

• ui/main.nui typed declarative UI

• a minimal length-prefixed RPC client

• a deterministic protocol test or syntax check

The neon3_app_init tool only writes below NEON3_APP_ROOT (or the current working directory when that variable is unset).

Validate NUI Without a Live Runtime

$source = [string]::Join("`n", (Get-Content .\templates\node-app\ui\main.nui))
$request = @{ request_id = "manual-1"; operation = "validate"; sequence = 1; source = $source } | ConvertTo-Json -Compress
$request | cargo run --quiet -p neon-ui-runtime --manifest-path D:\Neon3\Cargo.toml --bin neon3_authoring_probe

The process emits JSONL. A parser or compiler failure returns exit code 1 and includes stable diagnostics and source spans.

Start Neon3 Headless Services

Use the existing Neon3 launcher. The MCP does not silently create a second renderer:

cd D:\Neon3
scripts\run-neon-services.ps1

Then call neon3_capabilities, neon3_ui_snapshot, or neon3_nui_submit from the AI client.

Configuration

All live endpoints must be loopback endpoints. The MCP does not expose an arbitrary shell command tool.

Troubleshooting

The authoring probe cannot start

cd D:\Neon3
cargo build -p neon-ui-runtime --bin neon3_authoring_probe
$env:NEON3_ROOT = 'D:\Neon3'

revision_conflict

Call neon3_ui_snapshot, use the returned authoritative revision, and submit again. Do not blindly retry a stale mutation.

A service is unreachable

Check the endpoint in neon3_capabilities. Start Neon3 with scripts\run-neon-services.ps1 or use neon-dev for a windowed case.

Development

npm install
npm test
node --check src/index.js
npm pack --dry-run

The protocol test uses a deterministic local fake Neon3 endpoint and verifies request IDs, framing, and structured JSON output. The real NUI boundary is verified by neon3_authoring_probe in the Neon3 repository.

Project Relationship

This repository is the AI integration layer. Neon3 remains the owner of the protocol, NUI grammar, UI runtime, WGPU runtime, and project authority:

• MCP: https://github.com/unco999/neon3-ai-authoring-mcp

• Neon3: https://github.com/unco999/Neon3-CiJian

License

MIT. See LICENSE.