Dysnomia EVM MCP

A Dysnomia gameplay MCP server for players. It uses stock contracts on PulseChain and delegates chain reads, gas advice and signed transaction relay to icu-evm-mcp. Signing stays in the separate offline icu-evm-signer executable.

Character creation calls LAUFactory.New directly. CHO registration, username changes, Basilica claims and withdrawals are independent actions. No helper contracts are required or accepted.

Run

Requires Go 1.25 or later and a running icu-evm-mcp with the batched read, simulation and paginated raw-receipt interfaces. Set its URL in default.json.

make build
./dys-evm-mcp --config default.json --db data/dys-evm-mcp.db

The default transport is stdio. To serve HTTP and allow signed game transactions:

./dys-evm-mcp --config default.json --db data/dys-evm-mcp.db \
  --transport http --http-addr 127.0.0.1:8093 --enable-broadcast

HTTP binds to loopback only. Broadcast requires both servers to enable it. Keep the database across upgrades: it contains prepared actions, transaction identities, verified game instances and validation evidence. Startup fails on database errors; it does not reset existing state.

For an MCP client supporting HTTP configuration:

[mcp_servers.dys-evm-mcp]
url = "http://127.0.0.1:8093/"
tool_timeout_sec = 100

Documentation uses https://dys.gui.icu/docs as its canonical source and fetches the same versioned export from https://dysnomia.pages.dev by default. Set DYS_DOCS_BASE_URL to a loopback or private HTTP origin for a local test. --docs-cache-dir selects the persistent documentation cache directory; by default it is docs beside the game database. A fresh cache needs one successful fetch. Later reads use the last hash-verified snapshot when the source is down.

Play Dysnomia

1. Call dys_game_status to discover available deployments.
2. Call dys_prepare_create_character with from, name and symbol.
3. Sign the returned transaction outside the server.
4. Pass the resulting signed bytes and actionId to dys_broadcast_action.
5. Call dys_action_result to verify execution and obtain the actual LAU address.
6. Prepare Username(string) on that LAU and Enter(address) on CHO as separate actions when wanted.
7. Optionally use dys_prepare_basilica_claim for an explicitly selected active LAU. A claim credits the LAU; LAU.Withdraw(address,uint256) is a separate operation to move tokens to its owner.

A factory simulation's returned address is provisional. Other creations can change it before execution. Only the canonical result identifies the new LAU.

Example action arguments:

{
  "target": "CHO",
  "signature": "Enter(address)",
  "arguments": ["0xYOUR_LAU_ADDRESS"],
  "from": "0xYOUR_WALLET_ADDRESS"
}

Use exact signatures from dys_list_actions. It returns only evidence-backed player-callable reads and writes by default and groups repeated inherited bindings. bindingTotal counts exact family bindings, while uniqueFunctionTotal counts distinct signatures. Set expandInherited for every exact binding. Set scope to all, protocol_admin, internal_operation, excluded_helper, interface_only, or unreviewed for diagnostics. Each row reports its call mode, recommended tool, authority and deployment availability separately from live-validation evidence. Integers are decimal strings; addresses and bytes are hex strings; tuples are ordered arrays. Overloaded methods require their full signature, such as Username() versus Username(string).

Verified TT contracts expose fallback(bytes) for data publication and receive() for native deposits through dys_prepare_pki_action. Both require TT permission level 5; the deposit operation requires positive valueWei, while publish may optionally carry native value.

The action list is paginated with offset and limit (default 200, maximum 1,000); nextOffset continues the same family/target query.

The unsigned JSON is compatible with the offline signer:

icu-evm-signer sign --keystore /secure/account/keystore.json \
  --secret-file /secure/account/secret --tx-file unsigned.json

The MCP process never invokes this executable. It has no credential parameters, keystore access tools or signing endpoint. Pass only rawTx to the broadcast tool. Keep credentials outside the repository and outside the server container.

Tools

Tools	Purpose
dys_game_status, dys_discover_deployments, dys_list_actions, dys_find_actions, dys_describe_action, dys_resolve_entity	Deployment graph, bounded deployer discovery, callable-function discovery, exact interfaces and validation evidence
dys_read_game	Caller-preserving stock contract reads and stateful previews
dys_players, dys_player_status, dys_inventory, dys_permissions	Characters, active YUE, game assets and authority
dys_prepare_create_character	Stock character creation only
dys_basilica_claimability, dys_prepare_basilica_claim	Independent stock Basilica claim
dys_venues, dys_chat_history, dys_events	QING venues, global VOID/SHIO/QING chat and decoded event queries
dys_docs_search, dys_docs_read, dys_docs_status, dys_docs_refresh, dys_docs_archive	Verified documentation search, reading, freshness and archived copies
dys_power, dys_yue_quote, dys_territory, dys_war, dys_market_quote	Progression, YUE exchanges, territory, contests and internal markets
dys_explain_action, dys_compare_actions, dys_timers	Live blockers, gas comparisons and observable timing
dys_prepare_chat, dys_prepare_qing_join, dys_prepare_progression, dys_prepare_pki_action	First-class VOID/QING chat, QING admission, QI/MAI/XIA/XIE/ZI/PANG/RING/META progression, and PKMinter/TT workflows
dys_prepare_player_setup, dys_prepare_profile_update, dys_prepare_ownership_change	Onboarding, identity/profile and player-instance ownership workflows
dys_prepare_venue_create, dys_prepare_venue_control	MAP/GWAT creation and QING owner/bouncer workflows
dys_prepare_market_trade, dys_prepare_yue_action, dys_prepare_world_action, dys_prepare_private_message	Markets, YUE/CHAN, territory/WAR and ENCRYPT workflows
dys_prepare_action, dys_plan_actions	Other stock player action workflows
dys_broadcast_action, dys_action_result, dys_rewards	Verified relay, receipts, token flows and gas accounting

Documentation-backed gameplay

When a requested action or strategy has no predefined route, call dys_docs_search without section so it searches the technical, player and Alpha documentation together. Read relevant pages completely with dys_docs_read. Use a section filter only to refine an insufficient broad search: technical pages establish interfaces and source evidence, player pages explain game behavior, and Alpha pages provide strategy and economic context.

The server checks freshness every 15 minutes when documentation is requested; dys_docs_refresh forces a check. dys_docs_status reports the active revision, page counts and any refresh error. dys_docs_archive lists copies retained when pages disappear or move to an archived section; read one with dys_docs_read and archived: true. The dysnomia://docs resource exposes the active index and freshness metadata.

Documentation is not transaction authority or proof that a contract is deployed. Check dys_game_status and the selected player, map exact actions with dys_find_actions and dys_describe_action, then inspect permissions and simulation results before preparing the first transaction.

Strategy area	Current MCP route
Chat mining and admission	dys_venues, dys_timers, dys_prepare_qing_join, dys_prepare_chat
QING tuning and guest rotation	dys_permissions, dys_venues, dys_prepare_venue_control
Internal markets	dys_market_quote, dys_yue_quote, dys_prepare_market_trade
Power and progression	dys_power, dys_prepare_progression for QI through META
Player-instance ownership	dys_permissions, dys_prepare_ownership_change
Timing, formulas and economic comparisons	Read and preview only unless the page resolves to a separately verified action
Territory, overflow and private-message components	Available only when every required stock deployment is resolved

At the current deployment, WORLD, WAR, H2O, VITUS, GWAT and ENCRYPT are unresolved. This is not a permanent network claim; always use dys_game_status before deciding whether a strategy is fully, partially or not currently available. Supported components may still be performed when they are independently useful, but they must not be described as the complete strategy.

Some strategy material describes DYSNOMIASELFSNIPE. That helper is excluded. A similar stock-contract goal can use separate Chat and Purchase transactions, but the sequence is not atomic or economically identical. Confirm each receipt and refresh admission, rates, balances, allowance, simulation and gas before preparing the next step. Scheduling and repeated execution belong to the calling agent or operator; the MCP does not promise profitability or run a persistent strategy loop.

dys_broadcast_action is registered only with --enable-broadcast. dysnomia://catalog exposes the complete ABI catalogue as an MCP resource.

General address history, arbitrary contract calls, external DEX routing, RPC configuration and unrelated transfers belong in icu-evm-mcp. Player-owned LAU and QING management is part of this server's write interface. Protocol-owner administration is not.

Before a restricted player action, call dys_permissions with the target in targets or venue, or provide the exact action object for argument-aware checks. It reports direct ownership, QING bouncer authority, active LAU, YUE Origin and CHAN opt-ins as applicable. The same checks run before simulation and again before relay.

owner() returns the contract's own address in the stock MultiOwnable implementation. Authority checks use owner(address) and never infer a current owner from owner(). A QING owner action requires the signing wallet itself to be an owner. QING bouncer actions also accept authority held by the active LAU, matching the contract's bouncer check.

Validate

make check
make live

check runs formatting verification, tests, vet, module verification and builds. live connects to the running server and real upstream service. It checks the public MCP interface and helper refusal. Stateful validation uses funded dedicated characters and canonical chain receipts; no mocks or local forks.

The live client can call an individual tool and save its complete result:

go run ./scripts/live-check --tool dys_action_result \
  --input request.json --output receipt.json --summary

--suite runs live read/refusal assertions. --workflow runs an explicit funded test manifest with an external signer and a per-wallet gas budget. Its durable artifacts allow resuming the same manifest without replaying completed transactions. Keep manifests, credential references and live artifacts outside the repository. This client is separate from the MCP server.

License

MIT — see LICENSE.