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

Area	Included
NUI Flow	V1 grammar, typed inputs, layouts, controls, events, branches, statecharts, drag/drop, world panels
AI workflow	validate, inspect, submit, snapshots, capabilities, diagnostics
Runtime safety	loopback RPC, request IDs, bounded app paths, fixed process profiles, timeouts
Application code	Python and Node templates using the official Neon3 envelope
Documentation	MCP resources plus a standalone OpenCode-compatible Skill

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

Tool	Purpose
neon3_nui_reference	Read a detailed authoritative syntax topic
neon3_nui_validate	Parse and compile without mutating Neon3
neon3_nui_inspect	Return canonical IR, schema, stable nodes, bindings, and budgets
neon3_nui_submit	Validate, then submit through ui-runtime
neon3_capabilities	Query current service capabilities and epochs
neon3_ui_snapshot	Read UI state and revision information
neon3_project_assets	Read project summary and stable AssetRef values
neon3_diagnose	Correlate service snapshots and interaction traces
neon3_app_init	Create a bounded Python or Node application
neon3_app_run	Run a fixed application profile with a timeout
neon3_app_test	Run deterministic local application checks

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

Variable	Default	Meaning
NEON3_ROOT	D:\Neon3	Neon3 checkout used to build/run the authoring probe
NEON3_AUTHORING_PROBE	auto	Absolute probe executable override
NEON3_UI_ENDPOINT	127.0.0.1:39102	UI runtime RPC endpoint
NEON3_WGPU_ENDPOINT	127.0.0.1:39103	WGPU runtime RPC endpoint
NEON3_PROJECTD_ENDPOINT	127.0.0.1:39104	Project authority RPC endpoint
NEON3_APP_ROOT	current directory	Allowed root for generated app processes

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.