Skip to content

RFC-0016 — AI-assisted creation: an MCP server and a skill for building worlds

Status: draft · proposed 2026-10-15; open questions resolved 2026-10-15 (below); phase E1 built (as built). It builds on the builder and world folders of RFC-0014, the objects and placements of RFC-0011, the data sources and bindings of RFC-0013, companions in RFC-0010, personal quests in RFC-0012, the registry of RFC-0015 and the grant model of RFC-0003 and RFC-0007. It also sets rules that the builder’s next phases (the world wizard, primitives and materials, data-driven behaviours) follow, so that an assistant can drive them as well as a person can.

A user tells an AI assistant “a cosy rooftop garden at sunset with three screens and a CPU tower that glows”, and the world appears in Hyprune, built step by step while they watch, ready to walk, keep, change and release. The same works for smaller requests: “make the bar by the door follow my CI queue”, “give me a companion that walks slowly”, “a quest to tidy my inbox”.

  • Any assistant. Hyprune ships an MCP server, hyprune mcp, over stdio. Any MCP client can use it; Hyprune hosts no model and sends nothing to one itself.
  • End-user operations only. Every tool is something the user could do in the Director or with the hyprune CLI. The assistant gets no power the user’s own UI lacks, and none of the desktop: no windows, no input, no workspaces, no camera, no configuration or code.
  • Reversible. Every change lands in a world folder (pending until Save, then in git) or in the user layout with a backup. Publishing, running a command and entering a secret stay the user’s actions inside Hyprune.
  • Seen and checked. The assistant can look at what it built (rendered previews) and read the builder’s checklist, so it can fix its own mistakes before handing over.
  • Private. No window title, window content, application id or focus history reaches the assistant. Previews draw windows as placeholders.

Non-goals: generating 3D models or textures (the assistant uses primitives, the libraries, the registry and files the user or the client downloads); editing Hyprune’s code, configuration or installed packages; remote MCP transports; any operation in the user’s live desktop outside Hyprune’s own data.

Term Meaning
Assistant An AI agent in an MCP client (a chat app, a coding tool, an IDE) that the user runs.
MCP server hyprune mcp, a local process the MCP client starts. Part of @hyprune/sdk.
Pairing The user’s approval that connects an MCP server to core with the assistant profile.
assistant profile The fixed set of methods and the filtered state a paired connection gets.
Operation One SDK function or IPC method that the Director, the CLI and the MCP server all call.
Key A caller-chosen stable name for something in a world folder (cpu-tower).
Journal The MCP server’s list of the changes it made in this session, with their inverses.
Skill Instructions and examples that turn a description into a plan and a build.
MCP client ──stdio──► hyprune mcp (SDK, local, same user)
(any assistant) ├─ world folders: SDK builder library (create, sky, materials, save, history)
├─ core IPC, paired, assistant profile (place, edit, behaviours, companion, quests)
├─ data sources: SDK sources library (sources.json + the helper's control channel)
├─ registry: SDK registry client (search, install from the configured indexes)
└─ previews: core offscreen render, or the SDK's CPU renderer of the folder

The MCP server is a thin adapter: each tool validates its arguments, calls one operation and returns the operation’s result or error. It never writes a world folder, sources.json or the user layout by code of its own. When Hyprune is not running, world-folder operations still work (they need no core) and in-world operations return assistant.offline.

These rules apply to every operation the MCP server exposes, and so to the builder’s world wizard, primitives, materials and behaviours (RFC-0014 amendments) as they are built.

  1. One operation, three front ends. The Director, the CLI (--json) and the MCP server call the same SDK function or IPC method. A change that only one front end can make is a bug.
  2. Stable handles. Everything created in a world folder (placements, materials, behaviours, areas, data sources) has a generated id that is never reused, and may carry a key: a slug of 1 to 48 characters, unique per world folder and kind, stored in the project file. Operations accept {id} or {key}. The Director shows keys as names.
  3. Idempotent. A create with a key that exists fails with -32005 rule key.taken and the existing id, or updates it when called with ifExists: "update". Edits are absolute (a pose, a size, a material), never relative. Removing a missing handle succeeds with {removed: false}. Retrying any call after a timeout never makes a second copy.
  4. Dry run. Every mutating operation takes dryRun: true: it runs the full validation, the placement rules and the budget checks and returns what it would change, writing nothing.
  5. Clear errors. Errors carry the JSON-RPC code and error.data {rule, message, field?, hint?, retryable}. rule is a stable documented id, message one plain sentence, hint how to fix it (“move it 0.4 m away from the screen’s front”). The MCP server returns them as tool errors unchanged.
  6. Undo through the folder. No operation saves by itself. The folder’s pending changes, Discard (all or per file) and History with Revert are the undo; the journal adds undo of the assistant’s own last steps within a session (at most 256), each as the inverse operation. A change outside a world folder (the user layout, sources.json, the companion choice) takes an RFC-0014 backup first.
  7. Readable state. One read returns a bounded summary (at most 64 KiB) of the open world folder: placements with keys, refs, poses, sizes, materials and behaviours; areas, spawn and sky; sources without secrets; the checklist; pending changes. It never includes window data.
  8. Metres, degrees, world axes. Tool arguments use metres, degrees (yaw, pitch, roll) and the world frame (+Y up; the starter’s spawn faces −Z). A position may be given relative to a key ({relativeTo: "desk", offset: [0, 0.75, 0]}) or on a face of it ({on: "desk", face: "top"}), resolved from bounds before the call. Results always report absolute poses.

The MCP client starts hyprune mcp, so it has no launch token from Hyprune’s supervisor (RFC-0003). It connects to core’s socket and asks to be paired:

  1. session.pair {client: {id: "com.hyprune.mcp", name}, agent, profile: "assistant"}, allowed before session.hello on an unauthenticated connection, at most one pending request per connection and 3 per minute per user. agent is the MCP client’s name and version as it reported them to the server (a label, not proof).
  2. Core asks the user in the HUD and the Director: “ wants to build in Hyprune: world folders, objects, behaviours, companions and quests. It can’t see or use your windows.” The prompt says that the name is declared by the client itself. Allow once, Always allow, Deny. No answer in 120 s is a denial.
  3. On Allow, core answers with a one-use token for that connection; session.hello with it binds the assistant profile. On Deny, -32002 rule pair.denied.
  4. Always allow stores {clientId, agent, profile, approvedAt} in $XDG_STATE_HOME/hyprune/approvals.json (0600; never a token). A later pairing that matches it is approved at once, with a notice. Director → Connected assistants lists approvals and live connections, with Disconnect and Revoke.

Same-user processes are not isolated from each other (RFC-0003), so pairing is consent and visibility, not a barrier against local malware. It stops an assistant from acting in Hyprune without the user knowing, and limits what a well-behaved one can do.

Allowed Methods (when implemented)
Read, filtered state.snapshot/state.subscribe limited to builder, objects, live (values, no raw strings over 64 characters), quests, companion, jobs, zone names and the player’s position; objects.catalog, paths.list, libraries.list. Never surfaces, workspaces, focus, window titles or app ids.
Build objects.place, objects.transform, objects.configure, objects.remove, objects.hide, paths.set/paths.remove, world.load of a world folder or an installed world, and the builder.* methods core gains.
Characters and quests companion.set, companion.mode, companion.clear; quests.create, .update, .delete, .track.
Previews preview.render (below).

Everything else is refused with -32002, including surface.*, workspace.*, input.*, camera.*, movement.*, travel.*, shell.*, ui.*, runtime.*, settings.set, recording.*, data.publish and the pocket. The profile is a fixed method allowlist plus a filtered state projection in core, not a new combination of the RFC-0003 grants.

  • Files. The server writes only through operations: world folders under the projects directory, the user’s object folder (imports), sources.json entries it created, and the library install directory. It reads a local file only to import it or use it as a sky or texture; the path must be a regular file of the user, not under a dot-directory, and the importer must accept its format.
  • Commands. A command data source proposed by the assistant is written with "confirm": "pending". The helper never runs a pending entry, and its test op refuses one. The Director shows “An assistant proposed a command for ” with the exact argument vector, Test, Allow and Remove. HTTP sources need no confirmation: they only fetch, under the helper’s existing local-address rules.
  • Secrets. A source may name a secret; the assistant can see whether a name resolves and where (env, file, keyring), never its value, and can’t set one. The Director asks the user.
  • Publishing. No release, remote, push, registry submission or export is exposed. release_prepare opens the Builder page’s Release form filled in, for the user to press. Save is exposed: it makes a local commit that Revert undoes, with the message prefixed “Assistant: “.
  • Registry. Search and install from the configured official and community indexes only; adding a source stays a user action. Installed packages are data only (RFC-0015).
  • Visibility. While a paired connection is open the HUD shows an Assistant chip with the number of changes this session, Pause (operations return assistant.paused, retryable) and Disconnect. The Builder page lists the session’s changes from the journal.
  • Limits. At most 20 mutations per second and 5,000 per session; previews at most one per second. Over a limit: -32008, retryable.
  • The server exposes few, well-described tools; each maps to operations as above. Names are snake case; every mutating tool takes dryRun.

    Group Tools
    Worlds world_list, world_create (name, starter, sky preset or image, floor material, spawn), world_open (edit or play), world_describe, world_set_sky, world_set_floor, spawn_set, area_set, area_remove
    Building catalog_search, place (a primitive, a library or user object, or a workspace screen; key, pose, size, material), edit, remove, material_set, import (a local model or image, with licence, author and source)
    Machines source_list, source_set_http, source_propose_command, source_test, behaviour_set, behaviour_remove
    Checking look, checklist, make_world, save, discard, history, undo, release_prepare
    Characters companion_list, companion_choose, companion_mode, companion_name (E2)
    Quests quest_list, quest_create, quest_update, quest_delete
    Registry and assets registry_search, registry_install, asset_fetch (E2, allowlisted hosts)

    Resources: hyprune://world/current (the summary of rule 7), hyprune://catalog, hyprune://guide/building (the builder guide). Prompts: build_a_world (the skill, below).

    look. {from: "spawn" | "overview" | <key> | {position, yaw, pitch}, fov?, size?} returns a PNG (at most 1,024 px on the long side) as image content, plus the pose used. With Hyprune running and the world loaded, core renders it offscreen (preview.render): never in the render pass and never by moving the user’s camera, windows drawn as RFC-0005 placeholders. Otherwise the SDK renders the world folder on the CPU with the import helper’s software rasteriser (flat shading, base colours and textures, the sky), which is enough to judge layout. overview is a three-quarter view framing the folder’s bounds.

    Shipped twice from one source: as the MCP prompt build_a_world (any client) and as an agent skill folder (skills/hyprune-world-builder/: SKILL.md and examples) in the SDK package, which hyprune mcp --install-skill <dir> copies. It tells the assistant to:

    1. Ask only what changes the build: mood and time of day, size, how many screens, what data the machines show. Everything else gets a default.
    2. Plan first and show the plan: areas with sizes and what each is for, how they connect, one or two vistas, levels, the sky, a palette of materials, at least two screens with generous standing space in front, and the machines with their data. The user’s answer to the plan is the go-ahead.
    3. Use what is there: primitives and materials for blockout, library and registry objects for detail, the user’s own files when given. External assets only under CC0 or CC-BY, with author and source recorded at import; no names, marks or likenesses of existing games, films or brands.
    4. Build in passes, looking after each: blockout (floors, walls, ramps, levels), screens, props, materials, behaviours and sources, sky. After each pass, look from the spawn, the overview and two other angles, read the checklist, and fix what is wrong before going on.
    5. Hold the design rules: windows and screens never inside walls; space in front of every screen; distinct places rather than a grid; paths and vistas; the world holds up from every reachable angle, not only the hero view.
    6. Hand over: what was built, what is still open on the checklist, pending changes, and how to undo. Save when the user is happy; Release is theirs.

    Examples cover the rooftop garden at sunset (the demo below), a CI room with a conveyor bar fed by a JSON API, and a quiet study with a CPU tower whose height follows CPU load.

    Repo Change
    core session.pair and the approval prompt hook; the assistant profile (method allowlist and filtered state); approvals.json; preview.render {pose, fov, size} → {path} (a PNG in the runtime directory, deleted after 60 s; offscreen framebuffer prepared with doLater, GL state saved and restored, windows as placeholders); the Connections data in state for the shell. One IPC version.
    schema The IPC version: session.pair, preview.render, the profile name, the connections state key; sources.json confirm; project-file keys (with the builder phases).
    sdk hyprune mcp (stdio, the official MCP TypeScript SDK), the tool and resource adapters, the journal, the CPU look renderer, the skill files; operations shared with the Director as SDK functions (hyprune sources … beside hyprune builder …).
    shell The pairing prompt, the Assistant chip, Connected assistants, the pending-command confirmation on the Data sources page, the Builder page’s session changes.
    sources helper Skip and refuse confirm: "pending" entries.
    docs This RFC, a “Build with an assistant” guide (connecting a client, what it can and can’t do, undo).
    Phase Delivers Proven when
    E1 Pairing and the profile in core; the server with the world, building, machine (HTTP sources), checking and look (both renderers) tools; the journal and undo; the skill and prompt; the shell’s prompt, chip and Connections. In a nested session, the rooftop prompt is built end to end from an MCP client with a clip in the gallery; refused methods (surface.focus, input.set, camera.set, data.publish) fail with -32002; Deny, Revoke and Disconnect work; a server killed mid-build and run again with the same plan finishes with no duplicate placements; undoing every step leaves the folder equal to its last save.
    E2 Command proposals with the Director’s confirmation; companions, quests and registry tools; make_world and the checklist tools as the builder’s Make world lands; release_prepare. A proposed command never runs before Allow; a companion chosen and set to walk by the assistant behaves as one chosen in the Director.

    Decisions (defaults chosen for this draft)

    Section titled “Decisions (defaults chosen for this draft)”
    1. stdio only; no HTTP transport and no listening socket of the server’s own.
    2. Pairing per connection, with optional remembered approval keyed by client id, agent label and profile; no stored tokens.
    3. The assistant may Save (local commits, prefixed); it may not Release, set a remote or publish.
    4. HTTP sources without confirmation; command sources only after the user’s Allow in Hyprune.
    5. Assets: the client may fetch files itself and the server imports them with provenance; the server’s own asset_fetch (E2) is limited to allowlisted hosts.
    6. Previews draw windows as placeholders, always, also when the user is in the world.
    7. Offline (Hyprune not running): world-folder tools work, in-world tools return assistant.offline; look uses the CPU renderer.
    1. Save from an assistant needs no extra prompt: it is a local commit that Revert undoes. Every assistant save is labelled as one in History and counted on the HUD’s Assistant chip.
    2. Asset download: in E2, an asset_fetch tool limited to an allowlist of CC0 and CC-BY hosts (to start, the well-known CC0 texture, model and HDRI libraries). It records the source URL, licence and author automatically, is size-capped, and refuses any other URL.
    3. Remembered approvals are allowed, keyed to the client’s declared name. They are listed under Director → Connected assistants with Revoke, and the pairing prompt says that the name is declared by the client itself.
    4. Companions: E2 adds naming a companion and choosing among installed characters over IPC. Importing a new character stays a user action through Objects → Import.
    5. Placement cap: 512 placements per world folder, with budget warnings from the checklist.

    Also agreed: data-driven behaviours are visual only (collision stays at the rest pose), and the starter is Open Plain (open-plain@0.2), with flat-land@0.1 folders still loading.

    Status: draft · 2026-10-16. E1 is built: pairing and the assistant profile in core, the MCP server with the world, building, machine (HTTP sources) and checking tools, both look renderers, the journal and undo, the skill and the prompt, and the shell’s prompt, chip and Connected assistants. The guide is Build with an assistant.

    IPC 0.33 (draft) (schema). session.pair {protocols, client, agent {name, version?}, profile: "assistant"} before session.hello, answered when the user decides with {token, profile, remembered} or -32002 rule pair.denied; at most one waiting request per connection, 3 prompts a minute (a remembered approval prompts no one and isn’t counted) and 8 waiting at once (-32008 rule pair.limit). connections.answer {requestId, decision: once|always|deny}, .revoke {clientId, agent}, .disconnect {actor} and .pause {actor, paused} for shell.control peers; assistant.report {changes, action?} → {paused, changes} for the assistant (its folder changes reach the HUD chip this way, since core sees only its own methods); preview.render. State key connections {pending, live, approvals} for shell.control peers only. From 0.33 no state key is required.

    The profile is enforced in the daemon’s IPC server, never in the compositor:

    As built
    Methods session.ping, state.subscribe/snapshot/unsubscribe, objects.catalog/place/transform/configure/remove/hide, paths.list/set/remove, libraries.list, world.load, companion.set/mode/clear, quests.list/get/create/update/delete/track, preview.render, assistant.report. Anything else: -32002 rule profile.assistant. The token’s grants are state.read, objects.control, world.control and quest.control, whatever hello asks for.
    State Only builder, objects, live (strings over 64 characters cut), quests, companion, content, world, location and movement.
    Events state.delta only (no HUD, zone, mount, presentation or notice events).
    Limits 20 changes a second and 5,000 a session (-32008 rule assistant.limit); one preview a second (preview.limit); dry runs are free.
    Pause Changes return -32008 rule assistant.paused (retryable); the MCP server refuses its folder changes too.
    Disconnect Closes the connection; the MCP server then refuses in-world tools for the rest of its session (assistant.offline) instead of pairing again behind the user’s back.

    preview.render runs hyprune-preview, a separate process with its own headless GL context (the integrated GPU on a hybrid machine), on a description of the loaded world from the plugin: the package or the folder’s builder/base.json, every active user placement at its rest pose, the pose, the field of view and the size (at most 1,024 px). Windows are never drawn: screens show their empty frames. The PNG lives in $XDG_RUNTIME_DIR/hyprune/previews/ for 60 s. A preview takes about 2–3 s (most of it loading the world).

    The MCP server implements the protocol’s stdio transport and lifecycle itself (revisions 2025-06-18, 2025-03-26 and 2024-11-05: tools, resources, prompts), so the SDK gains no dependency; tests drive it as a client does. It pairs as soon as the client initializes (so the prompt appears when the assistant starts), with the client’s name and version as the agent label. Tools in E1: world_list, world_create, world_open, world_describe, world_set_sky, world_set_floor, spawn_set, catalog_search, place, edit, remove, material_set, import, source_list, source_set_http, source_test, behaviour_set, behaviour_remove, look, checklist, save, discard, history, undo. A yaw is a heading; an object at yaw h faces someone looking along heading h (at 0 its front faces +Z). place and edit resolve on: {key, face} and relativeTo: {key, offset} from the folder’s bounds. In-world tools need the folder open in Hyprune (world.not_open with a hint otherwise).

    The journal keeps each change’s inverse in memory (at most 256): core operations undo with the inverse method (a removal is placed again with its key, pose, scale, workspace and behaviours), sky, floor and spawn changes restore their files byte for byte and reload the folder, a material restores its files and swaps its shapes back. Generated shape folders and copies nobody places any more, and that the last save doesn’t have, are removed. When undo reaches the last save of a folder that was saved then, it ends with Discard, which also restores what inverses can’t (a re-placed placement’s id and its order in the project file): the folder then equals its last save exactly. Creating a world, imports and saves are named and skipped.

    The shell. The Director shows a waiting request on top of every page (Allow once, Always allow, Deny, the seconds left); the HUD shows a banner that sends the user to the Director, and the Assistant chip (name, changes, last action, paused). Director → Builder → Connected assistants lists live assistants (Pause, Disconnect) and remembered ones (Revoke). The Builder page polls the folder while it shows, so an assistant’s folder changes and the checklist appear as they happen.

    Not yet (E2): command proposals (source_propose_command with the Director’s Allow), companions, quests and registry tools, make_world and release_prepare, asset_fetch, and area markers (area_set, area_remove) with the builder’s areas. Previews show placements at rest (behaviours’ display changes are not drawn).

    Status: draft · 2026-10-16. E2 adds the rest of the tool list, in the same IPC draft:

    • Command proposals. source_propose_command {for | id, argv, intervalS?, timeoutS?, output?, map?} writes the entry with "confirm": "pending". The source helper keeps a pending entry out of its running sources (its status says pending: true), refuses one in its test op, and accepts no other confirm value. Objects → Data sources shows it with the exact argument vector: “An assistant proposed this command. It runs only after you allow it”, Allow (the entry written back without confirm), and the usual Test (the user’s test runs it once) and Remove. source_set_http on the same id replaces a proposal (an HTTP source needs no Allow).
    • Companions. companion_list (companion-capable characters and the current companion), companion_choose {ref, name?}, companion_name {name} and companion_mode {mode, pace?, style?}. IPC 0.33: companion.set takes an optional name (1 to 32 characters, null for the character’s own), kept in companion.json with the choice and shown everywhere the companion’s name is. Importing a character stays the user’s (Objects → Import).
    • Quests. quest_list, quest_create {quest, track?}, quest_update and quest_delete over the RFC-0012 methods (undo deletes a created quest; updates and deletions are named, not undone).
    • Registry. registry_search {query, type?} over the official and community indexes as last refreshed (custom sources are left out; refreshing and adding sources stay the user’s), and registry_install {id, type, version?} from those, through the SDK’s installer (data only).
    • make_world makes world.json now (as Save does first) and answers the homes and the checklist; it saves nothing.
    • release_prepare {version?, notes?} sends assistant.report {releaseDraft {projectId, version?, notes?}}; the live connection carries it and Director → Builder shows “ prepared a release v0.2.0: …” with Use it, which fills the Release form. Only the user’s Release press makes the tag.
    • asset_fetch {url, author?, name?} downloads from Poly Haven, ambientCG and Kenney only (https, redirects checked against the same list, at most 256 MiB, images, skies, models and zips), into $XDG_CACHE_HOME/hyprune/assets/, and answers the path with license CC0-1.0, the author and the source URL for import, material_set or world_set_sky.

    Still not built: area markers (area_set, area_remove) wait for the builder’s areas.