paralith-mcp 0.3.0 → 0.3.2

package/dist/chains.json

@@ -146,5 +146,19 @@
     "solana": "9eVvxEPKgpQ4Y2BZV8BWVAeRHWWfSEJy3vrM2AFNzdQ2",
     "sui": "0x46bd8f40263f6e056262f82f13c61d0849d813a030cde4c5bd6a8dd768144e9f",
     "ao": "z2OMYtbWHqNZY01ehkN0tsepznlrZQW-6dXPQO5lxDM"
-  }
+  },
+  "nodes": [
+    {
+      "ao": "tkqULqMDeHKXCN79Cm_bDIV560JxXl6pBSmdPgxqwSw",
+      "url": "https://hyperbeam.tylerw.ai"
+    },
+    {
+      "ao": "lcP5YsqL7SGNgylyzqlEO2M7VU6ntGUGNSSNO2WeytI",
+      "url": "https://hb.paralithmarkets.com"
+    },
+    {
+      "ao": "yUPIU4jjmkeR1RVACTj5__KavHcMoNoQ_Ly80F7u3GQ",
+      "url": "https://hb.randao.net"
+    }
+  ]
 }

package/dist/http.mjs

@@ -304,15 +304,60 @@ import { z as z9 } from "zod";
 
 // src/tool.mjs
 import { z } from "zod";
+
+// src/update.mjs
+var VERSION = "0.3.2";
+var CHECK_MS = 6 * 36e5;
+var NOTE_MS = 36e5;
+var latest = null;
+var checkedAt = 0;
+var notedAt = 0;
+var newer = (a, b) => {
+  const [x, y] = [a, b].map((v) => v.split(".").map(Number));
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+};
+function check(now) {
+  checkedAt = now;
+  fetch("https://registry.npmjs.org/paralith-mcp/latest", { signal: AbortSignal.timeout(1e4) }).then((r) => r.ok ? r.json() : null).then((j) => {
+    if (j?.version) latest = j.version;
+  }, () => {
+  });
+}
+function updateNote(now = Date.now()) {
+  if (now - checkedAt > CHECK_MS) check(now);
+  if (!latest || !newer(latest, VERSION) || now - notedAt < NOTE_MS) return null;
+  notedAt = now;
+  return `paralith-mcp ${latest} is out (this is ${VERSION}). Tell the user to restart this app to get it.`;
+}
+
+// src/tool.mjs
+var migrationSeen = null;
+async function migrationRefusal(read = readKey, now = Date.now()) {
+  if (!migrationSeen || now - migrationSeen.at > 15e3) {
+    migrationSeen = { at: now, value: await read("game", "migration").catch(() => null) };
+  }
+  const m = migrationSeen.value;
+  if (!m || typeof m !== "object" || m.phase === "live") return null;
+  if (m.phase === "retired") {
+    return `Paralith has moved to new processes (the game is now ${m.successor}). Nothing was sent. Update paralith-mcp to its latest version to use them.`;
+  }
+  return "A migration is in progress: Paralith is paused while every balance moves to new processes. Nothing was sent, and nothing is lost. Reads still work; try writes again later.";
+}
 function tool(server, name, description, inputSchema, run, annotations = {}, view = null) {
   if (READ_ONLY && annotations !== READ) return;
   const schema = view ? { ...inputSchema, full: z.boolean().optional().describe("Return the raw record instead of the compact view.") } : inputSchema;
   server.registerTool(name, { description, inputSchema: schema, annotations }, async (args) => {
     try {
+      if (annotations === WRITE) {
+        const refusal = await migrationRefusal();
+        if (refusal) return { isError: true, content: [{ type: "text", text: refusal }] };
+      }
       const raw = await run(args ?? {});
       const value = view && !args?.full ? await view(raw) : raw;
       const text = typeof value === "string" ? value : JSON.stringify(value, bigints, 2);
-      return { content: [{ type: "text", text: text ?? "null" }] };
+      const note = READ_ONLY ? null : updateNote();
+      return { content: [{ type: "text", text: text ?? "null" }, ...note ? [{ type: "text", text: note }] : []] };
     } catch (error) {
       return { isError: true, content: [{ type: "text", text: explain(error) }] };
     }
@@ -562,7 +607,7 @@ function registerGame(server) {
   tool(
     server,
     "game_daily",
-    "Claim the daily crate and Rune. Once per UTC day.",
+    "Claim the daily crate (and accrued Rune, pass holders only). Once per UTC day.",
     {},
     async () => (await me()).api.claimDaily(),
     WRITE,
@@ -1667,7 +1712,8 @@ import fs4 from "node:fs";
 import path4 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { z as z7 } from "zod";
-import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { spawn } from "node:child_process";
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, getUiCapability } from "@modelcontextprotocol/ext-apps/server";
 var GAME = (process.env.PARALITH_GAME_URL || "https://game.paralithmarkets.com").replace(/\/$/, "");
 var TRADE = (process.env.PARALITH_TRADE_URL || "https://trade.paralithmarkets.com").replace(/\/$/, "");
 var URI = "ui://paralith/view";
@@ -1700,6 +1746,16 @@ async function ownAddress() {
   const { wallets } = await runtime();
   return wallets?.ao.address;
 }
+function openInBrowser(url) {
+  const [cmd, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).on("error", () => {
+    }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
 function registerShow(server) {
   const csp = { frameDomains: [GAME, TRADE] };
   registerAppResource(
@@ -1710,7 +1766,7 @@ function registerShow(server) {
     async () => ({ contents: [{ uri: URI, mimeType: RESOURCE_MIME_TYPE, text: viewHtml(), _meta: { ui: { csp } } }] })
   );
   registerAppTool(server, "show", {
-    description: "Show something with the game's and exchange's own visuals, live: battle (follows a player's arena fights, animated), companion (card), hunt, market (order book and chart), vault, position, bridge (transfers). Returns a link; clients that support MCP Apps also display it inline. Address defaults to yours.",
+    description: "Show something with the game's and exchange's own visuals, live: battle (follows a player's arena fights, animated), companion (card), hunt, market (order book and chart), vault, position, bridge (transfers). Seeing it is a far better experience than reading about it: call show whenever you do something worth watching. It displays inline where the client supports that, and otherwise (local server) opens in the user's browser. Address defaults to yours.",
     inputSchema: {
       what: z7.enum(Object.keys(VIEWS)),
       address: z7.string().optional().describe("AO address; omit for yours."),
@@ -1721,14 +1777,19 @@ function registerShow(server) {
       market: z7.string().optional().describe("market/vault: the market, as exchange_markets lists it."),
       vault: z7.enum(["amm", "active", "grid"]).optional(),
       chain: z7.enum(["base", "solana", "sui"]).optional().describe("bridge: with tx, one transfer."),
-      tx: z7.string().optional()
+      tx: z7.string().optional(),
+      open: z7.boolean().optional().describe("Open in the user's browser. Default: only when this client cannot display it inline.")
     },
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: { ui: { resourceUri: URI } }
   }, async (args) => {
     try {
       const view = VIEWS[args.what]({ ...args, address: args.address ?? await ownAddress() });
-      return { structuredContent: { what: args.what, view }, content: [{ type: "text", text: `${args.what}: ${view}` }] };
+      const inline = !!getUiCapability(server.server.getClientCapabilities());
+      const opened = !READ_ONLY && (args.open ?? !inline) && openInBrowser(view);
+      const where = inline ? "Displayed inline." : opened ? "Opened in the user's browser." : "Give the user this link.";
+      return { structuredContent: { what: args.what, view }, content: [{ type: "text", text: `${args.what}: ${view}
+${where}` }] };
     } catch (error) {
       return { isError: true, content: [{ type: "text", text: error.message }] };
     }
@@ -1847,9 +1908,26 @@ Vaults (pooled liquidity, one amm/active/grid per market): vault_list, vault_pos
 Rune: rune_move withdraw (game -> token) / deposit (token -> game). Bridge: bridge_balances, bridge_faucet, bridge_deposit, bridge_redeem.
 DAO (stake TEST-RUNE; a passed proposal may send one attached message): dao_info, dao_proposals, dao_stake stake/unstake/withdraw, dao_propose, dao_vote.
 
+HOW RESOURCES FLOW. When asked for a resource, find its path here, check what you hold (progress), then say the route before acting.
+- Gold (in-game only, never leaves the game). Earn: companion play/quest/claim (capped at 60 Gold per 20 h), arena bot wins,
+  selling berries/Scrolls/Rune to the shop (game_shop sell) or on the game venue. Spend: arena stakes, shop buys, game-venue buys.
+- Berries and Scrolls. Get: joining, crates (game_daily, game_lootbox), buying with Gold (game_shop, or exchange_order venue "game").
+  Use: feed the companion, hunt escrow (2 of each berry), arena boosts; a Scroll plus 1-3 Rune for a hunt capture.
+- Rune exists twice: in-game Rune and the TEST-RUNE wallet token; rune_move converts 1:1 either way.
+  Get Rune: (1) the shop, only if game_shop quote shows an ask (it often only bids); (2) sell a companion on companion_market;
+  (3) the token route, which always works: element_claim (free daily, 1-10 of one element) -> exchange_order venue "token"
+  sell that element for TEST-RUNE -> rune_move deposit. Public TEST accounts accrue no Rune from game_daily (pass holders only).
+  Spend in-game Rune: game_level_up, hunt capture, companion_market buys. TEST-RUNE: token-venue buys, vaults, dao_stake.
+- Element tokens (TEST-EARTH/AIR/FIRE/WATER): element_claim daily; trade against TEST-RUNE on the token venue; vault liquidity.
+- PUSD: bridge in TEST-USDC from Base, Solana or Sui (needs that chain's gas, which the user funds; bridge_faucet gives TEST-USDC).
+  No PUSD market is listed yet. Redeeming back out needs a release claim this server cannot submit yet: say so rather than start it.
+- Vaults: deposit both sides of a market to earn from its strategy; withdraw with vault_shares.
+
 To report how you (or every agent set up on this machine) are doing, call progress (who: "all" for every agent); it also lists what needs doing next.
 
-To let the user SEE something (an arena fight as it happens, a companion, a hunt, a market's book and chart, a vault, a position, bridge transfers), call show: it returns a live link and displays inline where the client supports it.
+SHOW IT. Watching beats reading: call show for anything worth seeing (a fight as it happens, the companion after a level-up, the book
+you are trading, a vault, a bridge transfer). It displays inline where the client supports it, otherwise it opens in the user's browser.
+Show once per thing, not once per round.
 
 Rules: if a tool says a write WAS accepted but unconfirmed, never resend it; re-read state instead.
 A refusal ({"error": ...}) costs nothing. Use game_catalog for exact costs and move stats; docs at ${DOCS}/llms-full.txt.`;
@@ -1857,7 +1935,7 @@ var READ_ONLY_NOTE = `This endpoint is READ-ONLY: it explains the protocol and r
 To play, trade or bridge, run the local server with a wallet phrase: ${DOCS}/ai/mcp`;
 function buildServer() {
   const server = new McpServer(
-    { name: "paralith", version: "0.3.0" },
+    { name: "paralith", version: VERSION },
     { instructions: READ_ONLY ? `${READ_ONLY_NOTE}
 
 ${INSTRUCTIONS}` : INSTRUCTIONS }

package/dist/server.mjs

@@ -511,17 +511,65 @@ var init_runtime = __esm({
   }
 });
 
+// src/update.mjs
+function check(now) {
+  checkedAt = now;
+  fetch("https://registry.npmjs.org/paralith-mcp/latest", { signal: AbortSignal.timeout(1e4) }).then((r) => r.ok ? r.json() : null).then((j) => {
+    if (j?.version) latest = j.version;
+  }, () => {
+  });
+}
+function updateNote(now = Date.now()) {
+  if (now - checkedAt > CHECK_MS) check(now);
+  if (!latest || !newer(latest, VERSION) || now - notedAt < NOTE_MS) return null;
+  notedAt = now;
+  return `paralith-mcp ${latest} is out (this is ${VERSION}). Tell the user to restart this app to get it.`;
+}
+var VERSION, CHECK_MS, NOTE_MS, latest, checkedAt, notedAt, newer;
+var init_update = __esm({
+  "src/update.mjs"() {
+    "use strict";
+    VERSION = "0.3.2";
+    CHECK_MS = 6 * 36e5;
+    NOTE_MS = 36e5;
+    latest = null;
+    checkedAt = 0;
+    notedAt = 0;
+    newer = (a, b) => {
+      const [x, y] = [a, b].map((v) => v.split(".").map(Number));
+      for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+      return false;
+    };
+  }
+});
+
 // src/tool.mjs
 import { z } from "zod";
+async function migrationRefusal(read = readKey, now = Date.now()) {
+  if (!migrationSeen || now - migrationSeen.at > 15e3) {
+    migrationSeen = { at: now, value: await read("game", "migration").catch(() => null) };
+  }
+  const m = migrationSeen.value;
+  if (!m || typeof m !== "object" || m.phase === "live") return null;
+  if (m.phase === "retired") {
+    return `Paralith has moved to new processes (the game is now ${m.successor}). Nothing was sent. Update paralith-mcp to its latest version to use them.`;
+  }
+  return "A migration is in progress: Paralith is paused while every balance moves to new processes. Nothing was sent, and nothing is lost. Reads still work; try writes again later.";
+}
 function tool(server, name, description, inputSchema, run2, annotations = {}, view = null) {
   if (READ_ONLY && annotations !== READ) return;
   const schema = view ? { ...inputSchema, full: z.boolean().optional().describe("Return the raw record instead of the compact view.") } : inputSchema;
   server.registerTool(name, { description, inputSchema: schema, annotations }, async (args) => {
     try {
+      if (annotations === WRITE) {
+        const refusal = await migrationRefusal();
+        if (refusal) return { isError: true, content: [{ type: "text", text: refusal }] };
+      }
       const raw = await run2(args ?? {});
       const value = view && !args?.full ? await view(raw) : raw;
       const text = typeof value === "string" ? value : JSON.stringify(value, bigints, 2);
-      return { content: [{ type: "text", text: text ?? "null" }] };
+      const note = READ_ONLY ? null : updateNote();
+      return { content: [{ type: "text", text: text ?? "null" }, ...note ? [{ type: "text", text: note }] : []] };
     } catch (error) {
       return { isError: true, content: [{ type: "text", text: explain(error) }] };
     }
@@ -537,11 +585,13 @@ The message WAS accepted (slot ${error?.slot ?? "?"}); its result could not be c
   }
   return message;
 }
-var bigints, READ, OWN, WRITE;
+var migrationSeen, bigints, READ, OWN, WRITE;
 var init_tool = __esm({
   "src/tool.mjs"() {
     "use strict";
     init_runtime();
+    init_update();
+    migrationSeen = null;
     bigints = (_k, v) => typeof v === "bigint" ? v.toString() : v;
     READ = { readOnlyHint: true, openWorldHint: true };
     OWN = { readOnlyHint: true, openWorldHint: true };
@@ -780,7 +830,7 @@ function registerGame(server) {
   tool(
     server,
     "game_daily",
-    "Claim the daily crate and Rune. Once per UTC day.",
+    "Claim the daily crate (and accrued Rune, pass holders only). Once per UTC day.",
     {},
     async () => (await me()).api.claimDaily(),
     WRITE,
@@ -1928,7 +1978,8 @@ import fs5 from "node:fs";
 import path5 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { z as z7 } from "zod";
-import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { spawn } from "node:child_process";
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, getUiCapability } from "@modelcontextprotocol/ext-apps/server";
 function viewHtml() {
   for (const file of [path5.join(HERE2, "view.html"), path5.join(HERE2, "..", "dist", "view.html")]) {
     if (fs5.existsSync(file)) return fs5.readFileSync(file, "utf8");
@@ -1944,6 +1995,16 @@ async function ownAddress() {
   const { wallets } = await runtime();
   return wallets?.ao.address;
 }
+function openInBrowser(url) {
+  const [cmd, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).on("error", () => {
+    }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
 function registerShow(server) {
   const csp = { frameDomains: [GAME, TRADE] };
   registerAppResource(
@@ -1954,7 +2015,7 @@ function registerShow(server) {
     async () => ({ contents: [{ uri: URI, mimeType: RESOURCE_MIME_TYPE, text: viewHtml(), _meta: { ui: { csp } } }] })
   );
   registerAppTool(server, "show", {
-    description: "Show something with the game's and exchange's own visuals, live: battle (follows a player's arena fights, animated), companion (card), hunt, market (order book and chart), vault, position, bridge (transfers). Returns a link; clients that support MCP Apps also display it inline. Address defaults to yours.",
+    description: "Show something with the game's and exchange's own visuals, live: battle (follows a player's arena fights, animated), companion (card), hunt, market (order book and chart), vault, position, bridge (transfers). Seeing it is a far better experience than reading about it: call show whenever you do something worth watching. It displays inline where the client supports that, and otherwise (local server) opens in the user's browser. Address defaults to yours.",
     inputSchema: {
       what: z7.enum(Object.keys(VIEWS)),
       address: z7.string().optional().describe("AO address; omit for yours."),
@@ -1965,14 +2026,19 @@ function registerShow(server) {
       market: z7.string().optional().describe("market/vault: the market, as exchange_markets lists it."),
       vault: z7.enum(["amm", "active", "grid"]).optional(),
       chain: z7.enum(["base", "solana", "sui"]).optional().describe("bridge: with tx, one transfer."),
-      tx: z7.string().optional()
+      tx: z7.string().optional(),
+      open: z7.boolean().optional().describe("Open in the user's browser. Default: only when this client cannot display it inline.")
     },
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: { ui: { resourceUri: URI } }
   }, async (args) => {
     try {
       const view = VIEWS[args.what]({ ...args, address: args.address ?? await ownAddress() });
-      return { structuredContent: { what: args.what, view }, content: [{ type: "text", text: `${args.what}: ${view}` }] };
+      const inline = !!getUiCapability(server.server.getClientCapabilities());
+      const opened = !READ_ONLY && (args.open ?? !inline) && openInBrowser(view);
+      const where = inline ? "Displayed inline." : opened ? "Opened in the user's browser." : "Give the user this link.";
+      return { structuredContent: { what: args.what, view }, content: [{ type: "text", text: `${args.what}: ${view}
+${where}` }] };
     } catch (error) {
       return { isError: true, content: [{ type: "text", text: error.message }] };
     }
@@ -2120,7 +2186,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z as z9 } from "zod";
 function buildServer() {
   const server = new McpServer(
-    { name: "paralith", version: "0.3.0" },
+    { name: "paralith", version: VERSION },
     { instructions: READ_ONLY ? `${READ_ONLY_NOTE}
 
 ${INSTRUCTIONS}` : INSTRUCTIONS }
@@ -2210,6 +2276,7 @@ var init_build = __esm({
     init_vaults();
     init_show();
     init_progress();
+    init_update();
     DOCS = process.env.PARALITH_DOCS_URL || "https://docs.paralithmarkets.com";
     INSTRUCTIONS = `Paralith on AO (HyperBEAM): Rune Realm (a companion game), two order books, and the PUSD bridge.
 Everything is TEST-prefixed while unreleased. Reads are free; every write is a signed message (a few seconds round trip, longer under load).
@@ -2225,9 +2292,26 @@ Vaults (pooled liquidity, one amm/active/grid per market): vault_list, vault_pos
 Rune: rune_move withdraw (game -> token) / deposit (token -> game). Bridge: bridge_balances, bridge_faucet, bridge_deposit, bridge_redeem.
 DAO (stake TEST-RUNE; a passed proposal may send one attached message): dao_info, dao_proposals, dao_stake stake/unstake/withdraw, dao_propose, dao_vote.
 
+HOW RESOURCES FLOW. When asked for a resource, find its path here, check what you hold (progress), then say the route before acting.
+- Gold (in-game only, never leaves the game). Earn: companion play/quest/claim (capped at 60 Gold per 20 h), arena bot wins,
+  selling berries/Scrolls/Rune to the shop (game_shop sell) or on the game venue. Spend: arena stakes, shop buys, game-venue buys.
+- Berries and Scrolls. Get: joining, crates (game_daily, game_lootbox), buying with Gold (game_shop, or exchange_order venue "game").
+  Use: feed the companion, hunt escrow (2 of each berry), arena boosts; a Scroll plus 1-3 Rune for a hunt capture.
+- Rune exists twice: in-game Rune and the TEST-RUNE wallet token; rune_move converts 1:1 either way.
+  Get Rune: (1) the shop, only if game_shop quote shows an ask (it often only bids); (2) sell a companion on companion_market;
+  (3) the token route, which always works: element_claim (free daily, 1-10 of one element) -> exchange_order venue "token"
+  sell that element for TEST-RUNE -> rune_move deposit. Public TEST accounts accrue no Rune from game_daily (pass holders only).
+  Spend in-game Rune: game_level_up, hunt capture, companion_market buys. TEST-RUNE: token-venue buys, vaults, dao_stake.
+- Element tokens (TEST-EARTH/AIR/FIRE/WATER): element_claim daily; trade against TEST-RUNE on the token venue; vault liquidity.
+- PUSD: bridge in TEST-USDC from Base, Solana or Sui (needs that chain's gas, which the user funds; bridge_faucet gives TEST-USDC).
+  No PUSD market is listed yet. Redeeming back out needs a release claim this server cannot submit yet: say so rather than start it.
+- Vaults: deposit both sides of a market to earn from its strategy; withdraw with vault_shares.
+
 To report how you (or every agent set up on this machine) are doing, call progress (who: "all" for every agent); it also lists what needs doing next.
 
-To let the user SEE something (an arena fight as it happens, a companion, a hunt, a market's book and chart, a vault, a position, bridge transfers), call show: it returns a live link and displays inline where the client supports it.
+SHOW IT. Watching beats reading: call show for anything worth seeing (a fight as it happens, the companion after a level-up, the book
+you are trading, a vault, a bridge transfer). It displays inline where the client supports it, otherwise it opens in the user's browser.
+Show once per thing, not once per round.
 
 Rules: if a tool says a write WAS accepted but unconfirmed, never resend it; re-read state instead.
 A refusal ({"error": ...}) costs nothing. Use game_catalog for exact costs and move stats; docs at ${DOCS}/llms-full.txt.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paralith-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server for Paralith on AO: an AI with one 24-word phrase plays Rune Realm, trades and bridges PUSD (TEST deployment).",
   "license": "UNLICENSED",
   "homepage": "https://docs.paralithmarkets.com/ai/mcp",