npm packages | Gua Reference

Start with your task

For AI control, use gui-mcp on desktop or gua-webmcp in a browser. Import gua-value-tools or gua-world-tools directly when building your own data processing or inspection UI.

gui-mcp

Let AI operate a desktop game

A Bun command that forwards AI requests over WebSocket and returns game state or action results.

MCP server

gua-webmcp

Let AI operate a browser game

Registers AI tools in a Godot Web or Unity WebGL page using the game-provided port in that tab.

Browser WebMCP

gua-value-tools

Validate and compare values from a game

Checks typed JSON and returns a TypeScript value. Includes enum catalogs and order-independent set equality.

Value tools

gua-world-tools

Build tools that read game-world information

Validates published object trees and query results, builds selectors, and supplies read-only tool adapters.

World Object Tree

How Value and World differ

Both provide types and validation for data published by a game. Their units differ: Value handles one typed value, such as a set of inventory items; World handles an object tree, such as doors, their positions, and whether they are locked.

Value: item order does not change a setts

import { parseValue, valuesEqual } from "gua-value-tools";

const actual = parseValue('{"type":"set","elementType":"string","value":["key","map"]}');
const expected = parseValue('{"type":"set","elementType":"string","value":["map","key"]}');
console.log(valuesEqual(actual, expected)); // true

Pass two JSON strings to obtain validated values. valuesEqual returns true because set equality ignores order; list equality includes order.

World: a door tree and a selectorts

import { parseWorldObjectTree, selectorFromArguments } from "gua-world-tools";

const tree = parseWorldObjectTree({
  schemaVersion: 1, sessionEpoch: 1, frameSequence: 12, revision: 2,
  scene: "level-1",
  objects: [{ id: "door", kind: "door", space: "world2d",
    position: { x: 4, y: 2 }, visibleToPlayer: true, active: true,
    agentExposure: "auto", state: { locked: false } }]
});
const selector = selectorFromArguments({ kind: "door", stateKey: "locked", stateValue: false });
console.log(tree.objects[0].id); // "door"
console.log(selector); // { kind: "door", state: { key: "locked", value: false } }

parseWorldObjectTree validates the tree; selectorFromArguments builds an “unlocked door” selector. It does not execute a search. Pass the selector to GuaWorldProvider.findWorldObjects to query the host-approved view. World state uses ordinary string/number/boolean/null values, not typed Value JSON.

Install and combine

For a new setup, these commands request the current npm latest tag. Install only what you need and align the result with the game integration. For an existing game or reproducible MCP setup, use a matching explicit version.

Desktop AI connector (Bun)powershell

bunx gui-mcp@latest mcp

Start the game’s Gua WebSocket bridge and register this command in the AI client. The default endpoint is ws://127.0.0.1:8765; use GUA_BRIDGE_URL to change it. Connection steps

Browser AI connectorpowershell

npm install gua-webmcp@latest

gua-webmcp depends on gua-value-tools and gua-world-tools; a normal installation brings them in. Load the exported game first, wait for its port, then register tools. The browser must support the experimental document.modelContext API. Registration example

Custom data processingpowershell

npm install gua-value-tools@latest gua-world-tools@latest

Both libraries work in browsers. They do not connect to a game or collect a scene automatically; pass data obtained from the game or a connector. gui-mcp bundles the shared libraries, so running it does not require separate installations.

npm install records a dependency range in package.json and resolved versions in package-lock.json. Commit both; use npm ci in CI. It does not make a running app continuously update itself. npm install specification

Implementation and published packages: gui-mcp · gua-webmcp · gua-value-tools · gua-world-tools. World API · Value API