# Neon3 AI Authoring MCP

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

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An MCP server, detailed authoring Skill, and Python/Node starter kit for
[Neon3](https://github.com/unco999/Neon3-CiJian). It combines three layers:

```text
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:

```powershell
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

```powershell
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:

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

For a pinned local install:

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

## OpenCode Configuration

Add an MCP entry to your OpenCode configuration:

```json
{
  "$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:

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

## Claude Desktop / MCP Clients

```json
{
  "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

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

Example of valid, typed, semantic NUI:

```text
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

```powershell
$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:

```powershell
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

```powershell
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

```powershell
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](LICENSE).