paralith-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# paralith-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for the Paralith protocol: an AI with one 24-word phrase plays Rune
+Realm, trades on both order books, moves Rune, and bridges PUSD on Base,
+Solana and Sui. Public docs: `products/orderbook/app/src/docs/pages/ai/mcp.md`
+(served at docs.paralithmarkets.com/ai/mcp).
+
+## Use
+
+Read-only, no install: connect your MCP client to `https://mcp.paralithmarkets.com/mcp`.
+
+To play, trade and bridge, run it locally with a phrase made for the agent (Node 20+):
+
+```bash
+claude mcp add paralith --env PARALITH_MNEMONIC_FILE=/path/to/agent-phrase.txt -- npx -y paralith-mcp@latest
+```
+
+Other clients: command `npx`, args `["-y", "paralith-mcp@latest"]`, env `PARALITH_MNEMONIC_FILE`.
+Everything deployed is TEST-prefixed; chain gas is real. Tools: https://docs.paralithmarkets.com/ai/tools
+
+## Develop
+
+Hosted endpoint: `cpdeploy paralith-mono --env mcp` (`.cipherplay/deploy.mcp.env`).
+
+```bash
+npm install
+npm run build                     # bundle clients + servers into dist/ against the recorded deployment, regenerate the tool reference page
+PARALITH_MNEMONIC_FILE=phrase.txt node scripts/call.mjs            # list tools
+PARALITH_MNEMONIC_FILE=phrase.txt node scripts/call.mjs wallet '{}'  # call one over real stdio
+npm test                          # also fails if dist/ or the tool reference is stale
+```
+
+- `src/server.mjs`: stdio entry. No phrase means read-only.
+- `src/http.mjs`: hosted read-only endpoint, `POST /mcp`, `GET /health`.
+- `src/build.mjs`: `buildServer()` and the account tools.
+- `src/keys.mjs`: phrase to AO/Base/Solana/Sui signers.
+- `src/game.mjs`, `exchange.mjs`, `vaults.mjs`, `bridge.mjs`, `dao.mjs`: the tools. Game and venue verbs come
+  from the shipped client bundle (`backend/native/swarm/build-client.mjs`), never
+  reimplemented. Bridge chain calls mirror `products/bridge/testwallets/e2e.mjs`.
+- `src/views.mjs`: compact replies (`full: true` returns raw records).
+- `scripts/tools-doc.mjs`: writes the docs' tool reference (`ai/tools.md`) from the registered tools.
+- `scripts/vault-keeper.mjs`: cranks vaults that need it; report-only unless `--crank` (signs with the phrase). Run `--crank --watch` wherever the venue is operated.
+
+`dist/` is committed: the hosted image runs it as is. Re-run `npm run build` after every deploy, commit, and redeploy `mcp` and `docs`.

package/dist/chains.json

@@ -0,0 +1,113 @@
+{
+  "network": "mainnet",
+  "base": {
+    "chainId": 8453,
+    "rpc": "https://mainnet.base.org",
+    "explorer": "https://basescan.org",
+    "bridge": "0xCE13574d0Ca4A0dE9c5E5039fD2E9F6ec2593409",
+    "deployBlock": 52295541,
+    "tokens": [
+      {
+        "address": "0x405c70597266BefB0504389E333F10785B7919a9",
+        "symbol": "TEST-USDC",
+        "decimals": 6,
+        "faucet": true
+      }
+    ]
+  },
+  "solana": {
+    "cluster": "mainnet-beta",
+    "rpc": "https://api.mainnet-beta.solana.com",
+    "explorer": "https://solscan.io",
+    "programId": "thXGuX413NPvD7zPrSv658UmVEwdki2Tu3zhbU6LoiM",
+    "deployed": true,
+    "tokens": [
+      {
+        "mint": "2oJf5PQxWYjLfPQ5yTBt5XE34F1zoP1fHCeFwoPcrdDn",
+        "symbol": "TEST-USDC",
+        "decimals": 6,
+        "tokenProgram": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
+        "faucet": true
+      }
+    ],
+    "programIndex": 4
+  },
+  "sui": {
+    "network": "mainnet",
+    "rpc": "https://fullnode.mainnet.sui.io:443",
+    "graphql": "https://graphql.mainnet.sui.io/graphql",
+    "explorer": "https://suivision.xyz",
+    "package": "0x43e8e6eea948b92358e799d9f27042ce9d77cf160ad2736ab0f5fd852d1ffa24",
+    "originalPackage": "0x43e8e6eea948b92358e799d9f27042ce9d77cf160ad2736ab0f5fd852d1ffa24",
+    "bridge": "0x63e9050c72530fb577379f6b9d979aba3b84afeb83833cbe47a6972443fcd300",
+    "faucet": "0x24cdc90a23c129fe3afcc2bbb5c8bd0a63f10dad06ca6c04e03c41eb1e955ac3",
+    "tokens": [
+      {
+        "type": "0x43e8e6eea948b92358e799d9f27042ce9d77cf160ad2736ab0f5fd852d1ffa24::test_usdc::TEST_USDC",
+        "symbol": "TEST-USDC",
+        "decimals": 6,
+        "faucet": true
+      }
+    ],
+    "adminCap": "0xbfade5103b48bde0bdb5dcc0b016bb9571a93f79895de542e8853f522166d404",
+    "deployed": true,
+    "upgradeCap": "0xa1fb1dc179dcdc0579dca5b50a8d1162c1a3c40f531fb723f21de206c1ca78cd"
+  },
+  "relayers": {
+    "base": "0xDaaefC6Fe9C820DB57E9be7C0b566800de11ac22",
+    "solana": "9eVvxEPKgpQ4Y2BZV8BWVAeRHWWfSEJy3vrM2AFNzdQ2",
+    "sui": "0x46bd8f40263f6e056262f82f13c61d0849d813a030cde4c5bd6a8dd768144e9f",
+    "ao": "z2OMYtbWHqNZY01ehkN0tsepznlrZQW-6dXPQO5lxDM"
+  },
+  "deploy": {
+    "sui": {
+      "id": "0x43e8e6eea948b92358e799d9f27042ce9d77cf160ad2736ab0f5fd852d1ffa24",
+      "version": "sha256:a1fa3e2c74ded1733922a0055ed98b964223253daa25386a1adcec5e84e1b280",
+      "localHash": "sha256:a1fa3e2c74ded1733922a0055ed98b964223253daa25386a1adcec5e84e1b280",
+      "deployedAt": "2026-10-07T13:59:55.943Z",
+      "tx": "2ENtda5acLVU3RyTfTC4U9n56C9F4wNJfhPK8fZq7FtB",
+      "action": "FRESH"
+    },
+    "pusd": {
+      "id": "sXuny0tvUizug41AHbbvWfDcjkqK0MEjrWSBTQwp3ac",
+      "version": "sha256:4371b32bcc00fd14e85e740ac0f09d41bb6192509bee171d83594c901185eabc",
+      "localHash": "sha256:4371b32bcc00fd14e85e740ac0f09d41bb6192509bee171d83594c901185eabc",
+      "deployedAt": "2026-10-09T21:40:48.119Z",
+      "tx": "sXuny0tvUizug41AHbbvWfDcjkqK0MEjrWSBTQwp3ac",
+      "action": "FRESH"
+    },
+    "base": {
+      "id": "0xCE13574d0Ca4A0dE9c5E5039fD2E9F6ec2593409",
+      "version": "0x85ba7d3498f2cf2c87849ee1d4966867465431d233837f1158964dece0af9028",
+      "localHash": "0x85ba7d3498f2cf2c87849ee1d4966867465431d233837f1158964dece0af9028",
+      "deployedAt": "2026-10-07T13:41:12.236Z",
+      "tx": "0xb07dcc2967c1f803f7177ce99359f235319771fa0037982d983d1fd586bfdfef",
+      "action": "FRESH"
+    },
+    "solana": {
+      "id": "thXGuX413NPvD7zPrSv658UmVEwdki2Tu3zhbU6LoiM",
+      "version": "sha256:3ab07b185fa24f3da2a57352b9e2eed5f37475752cb2258d182d8a61afab7d2b",
+      "localHash": "sha256:3ab07b185fa24f3da2a57352b9e2eed5f37475752cb2258d182d8a61afab7d2b",
+      "deployedAt": "2026-10-07T13:59:36.619Z",
+      "tx": "4gzQJeXcj6WZyhTP1djC95LVAsEiH78gVcNBk57KESYkwzWqRNDkkGgotQwENYEXfzqZpfRFcmysrBoHh44TMxz1",
+      "action": "FRESH"
+    },
+    "lastRun": {
+      "at": "2026-10-09T21:41:00.279Z",
+      "startedAt": "2026-10-09T19:17:15.931Z",
+      "steps": [
+        {
+          "component": "pusd",
+          "action": "FRESH",
+          "status": "done",
+          "tx": "sXuny0tvUizug41AHbbvWfDcjkqK0MEjrWSBTQwp3ac"
+        },
+        {
+          "component": "tokens",
+          "action": "CONFIGURE",
+          "status": "done"
+        }
+      ]
+    }
+  }
+}