Structs Desktop (Embedded MCP)

Purpose: AI-readable reference for Structs Desktop — a native (Tauri) desktop app that wraps the structs-webapp game client and runs an embedded MCP server so an AI agent can play the game through one authenticated HTTP connection. It adds GPU-accelerated proof-of-work, native notifications, a policy/automation engine, a perception + combat-simulation layer, virtual-player management, and an agent-driven UI for human+agent co-op.

Repository: https://github.com/playstructs/structs-desktop

Download: prebuilt installers for macOS, Windows, and Linux are on the releases page.

This is the primary way an agent connects to Structs. The Guild Stack provides the PostgreSQL data store and GRASS event bridge that back the game infrastructure; Structs Desktop is the client + MCP surface an agent actually talks to. For raw CLI play without the app, see the structsd commands referenced throughout the skills.

Overview

Structs Desktop wraps the webapp in a Tauri shell and exposes an MCP server on the loopback interface. A single connection gives an agent full situational awareness, action execution with preflight checks, background hashing, event streaming, and a standing-order automation engine. The app never hands out signing keys — every transaction is signed inside the webview’s CosmJS client via a Rust ↔ JS bridge, so the MCP tools request signatures rather than holding secrets.

Key subsystems the MCP fronts:

• GPU/CPU hashing — Rust-native SHA256 proof-of-work (~200M h/s GPU via wgpu, ~3M h/s CPU via rayon) that transparently replaces the webapp’s JS WebWorker hasher.
• Perception + simulator — recon, a weapon-matrix ruleset, and a pure-math damage simulator so an agent can plan attacks without raw DB access.
• Policy engine — standing orders with delta tracking (auto-refine, power alerts, combat orders, watchdog self-healing).
• Native automation loops — Rust-side auto_harvest, auto_build, auto_defend, and auto_infuse that run the mine → refine → infuse flywheel across the whole roster without an agent in the loop.
• Virtual players — extra players derived from the same mnemonic (different HD indices), joined to your guild, so one operator fields a team.
• Agent-driven UI — the agent can render menus/dialogues/HUD on the human’s screen for co-op play (display/elicitation only; it cannot sign).
• Team Ops dashboard — a multi-page command center (Ops / Fleet / Energy / Work / Tx / Grass / Config / Map) in a native window, optionally served to a browser for a remote human.
• Event feed + notifications — a long-poll stream over a NATS ring buffer, plus native OS alerts filtered to your planet/fleet.

Connecting

Example client config (copyable from the Debug tab):

{
  "mcpServers": {
    "structs-game": {
      "type": "http",
      "url": "http://127.0.0.1:8420/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
    }
  }
}

The bearer token exists because any browser page can reach localhost — without it a malicious site could drive the game. See agent-security.md for the agent threat model.

Tool Catalog (13)

Retired/folded tools: structs_query was merged into structs_intel (query), and structs_ui into structs_board (component). The old names survive as deprecation stubs that return a pointer to the replacement, but they are no longer advertised — tools/list returns exactly the 13 above. An agent enumerating tools will never see them; only a hardcoded call to the old name hits the stub.

structs_players commands

Prompts (7)

Resources

The structs-ai compendium (this documentation) is bundled as MCP resources, synced during the app’s build. URIs are derived from the file tree (no hardcoded paths — see develop/structs-resources.md). Agents read docs on demand under the structs:// scheme, e.g.:

• structs://START.md
• structs://play/index.md
• structs://knowledge/mechanics/combat.md
• structs://reference/index.md

Because the sync is a build step, resources can legitimately be absent. A live server checked on 2026-07-24 advertised the resources capability but returned an empty resources/list and empty resources/templates/list, and every documented URI above answered -32602 Resource not found. So do not assume the compendium is reachable over MCP: call resources/list once and fall back to structs.ai or a local checkout if it comes back empty. Treat a populated resource set as a bonus, not a dependency.

Subsystems

GPU / CPU hashing

GPU (wgpu compute shader, ~200M h/s) is auto-selected when available and falls back to CPU (rayon + hardware SHA256, ~3M h/s). A Worker shim intercepts the webapp’s TaskWorker.js and routes hashing to Rust while keeping the existing TaskManager.js interface, which submits the completion transaction. Override at runtime with structs_hash {command:"config", engine:"cpu"|"gpu"|"auto"} and tune difficulty_start / max_concurrent.

Perception + combat simulator

structs_intel fronts a recon layer, a weapon-matrix ruleset, and a pure-math simulate so an agent can evaluate valid_targets, strike_options, and outcomes before committing charge. This mirrors the combat rules in combat.md.

Policy engine + watchdog

Standing orders run on game-state transitions using delta tracking (previous vs current snapshot) to avoid double-triggers. Only policies the engine actually evaluates are seeded, so structs_policy list is an honest inventory:

Combat orders are agent-honored — the policy engine never auto-signs; the agent reads them via structs_intel {query:"intents"} and acts through structs_action/structs_sequence. (The native loops below are the separate, opt-in path that does sign.) The watchdog self-heals wedged loop guards / stalled hash tasks / dead sync ticks, logging every remedy (structs_system) and notifying only on repeat failure.

Native automation loops

Six Rust-side loops run without an agent tick. All are off by default, all auto-sign for the players they manage, and all are configured through structs_players (or the Team Ops Config page) with {now:true} to force an immediate scan.

The first four run the economic flywheel. The last two are autonomous combat and carry a second safety gate: even once enabled they default to autonomy: advise, meaning they rank and explain but sign nothing until you set autonomy: auto. Both also accept dry_run, which is independent of autonomy — it computes and logs everything and signs nothing, so it stays safe even in auto.

Two auto_build behaviors matter when reading its logs. It is command-struct-first: if a player’s Command Ship is destroyed, rebuilding it is the only initiate that scan (a fleet with no command struct is rejected on every other deploy, and planet builds need the Command Ship online), and the loop waits while the replacement is still building. And it disambiguates the chain’s overloaded cannot handle new load requirements (required: X, available: Y) error — small integers mean the per-player build-count cap for a one-per-player struct type (advance to the next loadout item; no charge was spent), while milliwatt-magnitude values mean a real power shortage (back off).

panic_refine is the one part of auto_response that acts in advise mode, and deliberately so: refining the threatened ore is purely defensive, removes the entire prize, and cannot harm anyone. It also runs in harden mode and even when no shot is possible. The three mode values are harden (refine and alert only), counter, and decapitate (default — go for the raider’s Command Ship).

Two design choices in auto_response follow from constraints documented elsewhere in this repo. Shooter selection is limited to the attacked player’s own on-station fleet plus anyone already parked at that planet, because combat is co-located — the other virtual players’ charge bars are irrelevant no matter how full. And detection runs off effect events rather than struct_attack, because a real multi-shot exchange exceeds the ~8 KB NATS payload ceiling and arrives as a stub with no attacker fields; the attacker identity is pulled from the Guild API planet-activity feed. See structs-streaming.

auto_raid applies a friend-or-foe veto before scoring: your own accounts, allied guilds, and protected players are never targets regardless of what they hold. Those lists are managed with structs_doctrine {command:"lists"}.

Combat lists

structs_doctrine {command:"lists"} reads and edits four persistent lists that both combat loops consult, via {list_action: show|add|remove|mute|unmute, kind, id, weight?, note?}.

weight is a priority multiplier, 0–10, default 1, and note is free text shown on the dashboard’s WAR page. What auto_raid actually scores for a grudge is its heat — weight × (0.35 + 0.4 × incidents + 0.25 × harm) — so repeated attacks and real struct losses raise a target on their own without you touching the weight.

Two lifetime rules matter. Auto-recorded grudges expire after 30 days; manually added ones never expire. And mute/unmute applies only to grudges: a muted grudge is kept for the record but scores zero, which is the right way to spare someone without losing the history.

When your own guild gets its ally veto is a trap worth knowing. Seeding happens at the top of auto_raid’s scan, not at app start — so until that loop has run at least once, lists shows no allied guilds at all, which looks alarming and is easy to misread as “my guild is targetable.” It is not: the seed runs before scoring in the same tick, so there is no window where your own guild can be picked. Verified live on a server that had never run the loop — allies empty, and seed_own_guild is called from exactly one place, auto_raid’s tick. A latch respects later manual removal, so deliberately un-allying your own guild sticks.

Grudges accumulating on their own is worth understanding before you arm auto_raid: auto_response writes them whenever it observes an attack, including while it is merely advising. By the time you turn the offensive loop on, the list may already describe a target set you never explicitly chose. Read it with {list_action:"show"} first.

Team Ops dashboard and web board

The Team Ops window is a multi-page command center (nav labels in the live board):

Those pages are backed by Tauri / web-board commands in board_pages.rs (mcp_roster, mcp_energy, mcp_inventory, mcp_war_bundle, mcp_config_*, mcp_tx_*, …). They are not additional MCP tools — tools/list is still the 13 tools above. Agents keep using structs_board / structs_players / structs_doctrine; humans drive the richer pages in the native window or over the web board.

structs_board {web:"on"} serves those same pages over HTTP at /board on the MCP port so a remote human can drive the dashboard from a browser; {web:"status"} returns the shareable URL and {web:"off"} stops serving. It is opt-in and every route 404s until enabled. Authentication is the MCP bearer token, handed over once as ?token= and swapped for an HttpOnly cookie. The server binds 127.0.0.1 only, so remote access goes through the operator’s own tunnel (ssh -L 8420:127.0.0.1:8420 user@host). Because the web path bypasses the native window guard, the token is full operator authority — including mass actions that sign transactions. Web writes push the same audit entries into the event feed as native ones. Native mutating dashboard commands are gated to the board window label (require_board); the web path reuses the same handlers after bearer auth.

Event feed

Combat reaches structs_events as struct_health (with health/health_old and struct_id) and struct_status, alongside shield_change, struct_block_build_start, fleet_arrive/fleet_depart, raid_status, player_consensus, and lastAction. There is no struct_attack category in the feed — for your own attack outcomes use structs_intel {query:"battle_log"}. Actions you submitted come back as tx_settled receipts carrying the real tx hash, chain code, and succeeded/dropped status.

Every GRASS event is also scanned for player (1-…) and struct (5-…) ids; unknown ones are resolved to names by background LCD reads, cached, and pushed to the board so live rows upgrade in place. block heartbeat events are relayed to the Grass page but deliberately not buffered — they would flush the 1000-entry ring within the hour — so they never appear in structs_events results.

Combat mode

The policy engine auto-detects combat events (raids, attacks, fleet arrivals) and tightens the gameState sync interval from 10s to 3s, dropping back after ~30 quiet blocks (~3 min).

Virtual players

structs_players manages additional players derived from the same mnemonic at different HD indices and joined to your guild. Keys never leave the webapp; the MCP drives signing through the vplayer bridge. Run a chain as a specific virtual player with the as parameter on structs_sequence (and act-as on structs_players). See team-operations for why a team of players beats a single account (the charge bar is per-player).

Transaction signing bridge

MCP actions never hold keys. structs_action validates preconditions, Rust emits mcp_transaction_request to the webview, the JS SigningClientManager signs+broadcasts via CosmJS, and the result returns over mcp_transaction_response. This is why the app is a safe MCP host: the agent requests signatures, it does not possess them. A second, parallel bridge (structs:txq-request) reads and reorders the webapp’s signing queue for the Tx page; it only inspects and mutates in-memory lanes and never signs or broadcasts anything itself.

Charge-gated actions auto-queue — do not hand-time them. The webapp signing queue holds a charge-gated message in a charge lane and broadcasts it once the on-chain charge bar is sufficient, so the MCP no longer blocks on charge. Submit the action and read the returned note, which tells you whether it broadcasts this block or is queued and for how many blocks. This is a meaningful difference from the raw CLI, where you must wait out the charge bar yourself: through Desktop, an agent should submit and move on rather than sleeping between actions.

Agent-driven UI

structs_board component mode renders on the human’s screen (menu, dialogue, panel, info, map_preview, hud_badge, toast, open_menu, raw_html, dismiss). Toasts and dialogues render in the Team Ops window; only open_menu and map_preview touch the main game view. notify shows-and-returns; prompt blocks until the human chooses. Guardrails: every agent-drawn surface carries an “⚡ Agent” marker, the agent_ui policy is a master off-switch, and directives are display/elicitation only — they cannot sign (any chosen action still flows through the approval-gated tx bridge).

Notifications

Native OS alerts fire off NATS WebSocket events, filtered to your planet/fleet: raid alerts, structs under attack, enemy fleet incoming/departed, your fleet moved, mining/refining/build started, struct status changed, Alpha Matter transfer, power alert. macOS uses UNUserNotificationCenter (needs a signed .app); Windows/Linux use notify-rust.

Guild configuration + directory

Configs live in app data as guild_configs.json (multiple entries, one is_active). Fields: guild_id, name, guild_tag, guild_api, reactor_api, client_ws, grass_nats_ws, optional endpoint, source (seed / chain / user), last_refreshed, and denoms (cosmetic guild-token names by exponent for Inventory).

Discovery (guild_directory): crawls GET {reactor}/structs/guild for each guild’s on-chain endpoint document (guild.json), then upserts infrastructure URLs. Endpoint bodies are untrusted UGC — size-capped, schema-validated, fetched with a cookie-less client so the guild session cookie never leaks to arbitrary hosts (see agent-security.md).

Shared vs per-guild: every guild is on the same testnet chain. Discovery pins reactor_api / client_ws to the public node (https://public.testnet.structs.network / matching RPC ws) rather than adopting each guild’s self-declared LCD/RPC (those are inconsistent). Only guild_api and grass_nats_ws are genuinely per-guild. Default/onboarding guild id is 0-5 (SN Corp). User-managed entries are not overwritten by discovery URL refreshes.

Switching active guild reloads the frontend against the new config; a cooldown + LCD backstop guard against reload loops when a player migrates mid-session.

See Also

• TOOLS.md — environment configuration and how to point an agent at this MCP
• awareness/agent-security.md — agent threat model (localhost auth, adversarial UGC)
• knowledge/infrastructure/guild-stack.md — the PostgreSQL + GRASS backend this client talks to
• .cursor/skills/structs-streaming/SKILL.md — GRASS real-time events the notifications/event feed consume
• playbooks/meta/team-operations.md — multi-player (virtual-player) coordination