@suisei-mcp/mcp 0.1.0

package/README.md

@@ -0,0 +1,199 @@
+# @suisei-mcp/mcp — Suisei MCP
+
+The Sui Stack as one-line tools, exposed over the Model Context Protocol
+— so any MCP-aware client (Claude Desktop, Cursor, Windsurf, your own
+agent) can build on Sui. The server identifies itself as **Suisei** to
+the agent. Tool names keep the `sui_` prefix because they wrap the Sui
+chain — Suisei is the agent toolkit; Sui is the chain it speaks.
+[Suisei the teaching agent](https://suisei.dev) is a showcase built
+entirely on these tools.
+
+> **Status:** Alpha. Thirty-three tools spanning the core build loop —
+> read chain state, build any transaction, simulate it, decode it,
+> submit it — plus native staking (stake, unstake, live APY, validator
+> set, position tracking), DeepBook quotes & swaps, batch payouts,
+> historical events, coin metadata + symbol registry, Tier-1
+> agent-wallet lifecycle, and Walrus storage. Next up: the on-chain
+> policy vault and Seal.
+
+## Why
+
+Most Sui SDKs assume you're writing application code. This package
+assumes you're writing **agent** code — short tool calls, structured
+JSON in, structured JSON out, no React, no UI. The agent decides what
+to do; the tool does it.
+
+## Install
+
+```bash
+npm install -g @suisei-mcp/mcp
+```
+
+## Use with Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or the equivalent on your platform:
+
+```jsonc
+{
+  "mcpServers": {
+    "suisei": {
+      "command": "npx",
+      "args": ["-y", "@suisei-mcp/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You can now ask the agent things like:
+
+> "What's the balance of `alice.sui`?"
+> "Mint a badge to `0x1234…` for completing the zkLogin quest."
+> "Publish this paragraph to Walrus and give me the blob id."
+
+The agent picks the right tool. You see the result.
+
+## Use it remotely (Claude web + mobile)
+
+Stdio only works where the host can spawn a local process (Claude
+Desktop, Cursor). To use the toolkit from the **Claude web and mobile
+apps**, run it as a **remote MCP server** and add the URL as a Custom
+Connector (Settings → Connectors).
+
+Host it anywhere with the bundled HTTP server:
+
+```bash
+PORT=8787 SUISEI_MCP_TOKEN=your-secret npx suisei-mcp-serve
+# serves Streamable HTTP at http://localhost:8787/  (front with HTTPS in prod)
+```
+
+On serverless, import the runtime-agnostic Fetch handler directly — it
+runs on Vercel Edge, Cloudflare Workers, Deno, and Bun:
+
+```ts
+// api/mcp.ts (Vercel Edge)  — needs `@suisei-mcp/mcp` as a dependency
+export const config = { runtime: 'edge' };
+import { handleMcpRequest } from '@suisei-mcp/mcp/http';
+export default (req: Request) => handleMcpRequest(req);
+```
+
+Set `SUISEI_MCP_TOKEN` so the endpoint requires
+`Authorization: Bearer <token>` — a public MCP URL without a token is
+open to the world.
+
+**Signing caveat.** Reads (balances, coins, objects, transactions,
+dynamic fields, gas, Walrus) work over a remote connector immediately.
+The transaction-building tools still return *unsigned* bytes — signing
+happens host-side, and a remote host (mobile) has no local wallet, so it
+needs its own signing path (e.g. an Enoki-sponsored flow or a wallet
+deep-link) to submit.
+
+## Tools
+
+**Read the chain**
+
+| Tool                    | What it does                                                 |
+| ----------------------- | ------------------------------------------------------------ |
+| `sui_resolve_address`   | SuiNS name → 0x address (idempotent on 0x inputs)            |
+| `sui_get_balance`       | SUI balance (in MIST + human-readable SUI)                   |
+| `sui_get_all_balances`  | Every coin balance a wallet holds, not just SUI             |
+| `sui_get_object`        | Any object's type, owner, fields, and Display               |
+| `sui_get_owned_objects` | List objects by owner, filterable by struct type, paginated |
+| `sui_get_owned_badges`  | List a wallet's Suisei completion badges                    |
+| `sui_get_coins`         | List coin objects of a type (the ids you spend), paginated  |
+| `sui_get_transaction`   | Look up a finalized tx by digest: status, gas, changes      |
+| `sui_get_reference_gas_price` | Current network reference gas price (MIST)            |
+| `sui_get_dynamic_fields` | List an object's dynamic fields (Tables, Bags), paginated  |
+| `sui_get_stakes`        | A wallet's active stakes: principal, accrued rewards, ids   |
+| `sui_get_validators_apy` | Live APY per validator (the APR feed for staking)          |
+| `sui_get_validators`    | Active validator set: name, address, commission, total stake |
+| `sui_get_validator`     | One validator, with APY + commission + stake merged         |
+| `sui_query_events`      | Historical events: filter by type / module / sender / tx    |
+| `sui_get_coin_metadata` | Live coin metadata (symbol, decimals, name, icon URL)       |
+| `sui_resolve_coin`      | Symbol → coin type from a built-in registry (USDC, DEEP, …) |
+| `sui_deepbook_quote`    | Read-only DeepBook v3 quote: expected out + DEEP fee        |
+| `agent_wallet_status`   | An agent wallet's SUI balance + whether it's funded         |
+
+**Build a transaction (never signed — bytes returned for the host)**
+
+| Tool                    | What it does                                                 |
+| ----------------------- | ------------------------------------------------------------ |
+| `sui_move_call`         | Build a call to ANY Move entry function — the universal write |
+| `sui_transfer`          | Build a transfer of SUI and/or whole objects                |
+| `sui_pay_many`          | Build a batch payout: N recipients, N amounts, one atomic tx |
+| `sui_stake`             | Build a native staking delegation to a validator            |
+| `sui_unstake`           | Build a withdraw-stake for a StakedSui object               |
+| `sui_mint_badge`        | Build a Suisei completion-badge mint                         |
+| `sui_deepbook_swap`     | Build a DeepBook v3 market swap (CLOB liquidity)            |
+| `agent_wallet_fund`     | Owner-signed: top up an agent wallet's allowance            |
+| `agent_wallet_sweep`    | Agent-signed kill switch: drain the wallet back to the owner |
+
+**Simulate & submit**
+
+| Tool                    | What it does                                                 |
+| ----------------------- | ------------------------------------------------------------ |
+| `sui_dry_run`           | Simulate built tx bytes (status + gas, no spend)            |
+| `sui_decode_tx_bytes`   | Offline decode: turn unsigned bytes into a human-readable plan |
+| `sui_execute_signed_tx` | Submit host-signed tx bytes, return digest + effects        |
+
+**Walrus storage**
+
+| Tool                    | What it does                                                 |
+| ----------------------- | ------------------------------------------------------------ |
+| `walrus_publish`        | Publish a blob to Walrus testnet/mainnet                     |
+| `walrus_fetch`          | Fetch a blob from Walrus by id                               |
+
+The build loop is: a `*_build`-style tool returns base64 tx bytes →
+`sui_dry_run` to verify → the host signs → `sui_execute_signed_tx` to
+submit. The toolkit never holds keys.
+
+All tools return structured JSON in the `text` content block. The
+calling agent is expected to parse it.
+
+## Design rules
+
+- **No private keys.** Tools that produce transactions return tx bytes;
+  the host signs and submits. A tool that holds a key is a tool that
+  can spend money.
+- **One job per tool.** No mega-tools with twelve flags. The agent's
+  reasoning gets sharper when each tool is unambiguous.
+- **Structured output.** Every successful return is JSON. The agent
+  reads structured data more accurately than prose.
+
+## Transport &amp; deprecation
+
+Sui is deprecating public JSON-RPC fullnode endpoints (~mid-2026) in
+favour of gRPC and GraphQL. Transport is chosen in one place —
+`src/sui-client.ts` — so the rest of the toolkit never imports a client
+directly.
+
+Today `clientFor()` returns the JSON-RPC client, because building a
+transaction (`tx.build({ client })`) needs *transaction resolution*,
+which `@mysten/sui` 1.45.x implements only for JSON-RPC. Verified against
+testnet: both the gRPC and GraphQL clients reject `tx.build` ("not
+supported"/"not supported yet"). Reads already work over gRPC via
+`grpcClientFor()`, also in that file.
+
+When the SDK ships transaction-building over gRPC, the cutover is a
+one-line change in `clientFor()` — no tool touches transport directly.
+
+## Development
+
+```bash
+git clone https://github.com/eienel/blockbuilders
+cd blockbuilders/packages/mcp
+npm install
+npm run build
+node dist/index.js
+```
+
+The server speaks JSON-RPC 2.0 over stdio per the MCP spec. To test
+without an agent, you can pipe a handshake in by hand:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
+```
+
+## License
+
+MIT.

package/dist/coins.d.ts

@@ -0,0 +1,21 @@
+import type { Network } from './sui-client.js';
+/**
+ * Coin metadata registry — the "what is USDC's coin type" table. Static
+ * because mainnet/testnet coin types are upgrade-stable; if Sui ever
+ * redeploys one, override the type explicitly in any tool that takes
+ * coin_type, or update this file. Decimals are cached here so an agent
+ * can size amounts without an extra RPC call, but sui_get_coin_metadata
+ * is the authoritative live lookup.
+ */
+export interface CoinInfo {
+    symbol: string;
+    coin_type: string;
+    decimals: number;
+    description?: string;
+}
+/** Common coins by symbol (case-insensitive lookup). */
+export declare const COINS: Record<Network, Record<string, CoinInfo>>;
+/** Look up a coin by symbol on a network. Case-insensitive. */
+export declare function findCoin(network: Network, symbol: string): CoinInfo | undefined;
+/** List known coin symbols for a network. */
+export declare function knownSymbols(network: Network): string[];

package/dist/coins.js

@@ -0,0 +1,59 @@
+const SUI = '0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI';
+/** Common coins by symbol (case-insensitive lookup). */
+export const COINS = {
+    testnet: {
+        SUI: { symbol: 'SUI', coin_type: SUI, decimals: 9, description: 'Native Sui coin.' },
+        DBUSDC: {
+            symbol: 'DBUSDC',
+            coin_type: '0xf7152c05930480cd740d7311b5b8b45c6f488e3a53a11c3f74a6fac36a52e0d7::DBUSDC::DBUSDC',
+            decimals: 6,
+            description: 'DeepBook test USDC (testnet).',
+        },
+        DEEP: {
+            symbol: 'DEEP',
+            coin_type: '0x36dbef866a1d62bf7328989a10fb2f07d769f4ee587c0de4a0a256e57e0a58a8::deep::DEEP',
+            decimals: 6,
+            description: 'DeepBook utility token (testnet).',
+        },
+    },
+    mainnet: {
+        SUI: { symbol: 'SUI', coin_type: SUI, decimals: 9, description: 'Native Sui coin.' },
+        USDC: {
+            symbol: 'USDC',
+            coin_type: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
+            decimals: 6,
+            description: 'Native USDC on Sui (Circle).',
+        },
+        USDT: {
+            symbol: 'USDT',
+            coin_type: '0xc060006111016b8a020ad5b33834984a437aaa7d3c74c18e09a95d48aceab08c::coin::COIN',
+            decimals: 6,
+            description: 'Wormhole USDT (canonical bridged).',
+        },
+        DEEP: {
+            symbol: 'DEEP',
+            coin_type: '0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP',
+            decimals: 6,
+            description: 'DeepBook utility token.',
+        },
+        WAL: {
+            symbol: 'WAL',
+            coin_type: '0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL',
+            decimals: 9,
+            description: 'Walrus native token.',
+        },
+    },
+    devnet: {
+        SUI: { symbol: 'SUI', coin_type: SUI, decimals: 9, description: 'Native Sui coin.' },
+    },
+};
+/** Look up a coin by symbol on a network. Case-insensitive. */
+export function findCoin(network, symbol) {
+    const table = COINS[network] ?? {};
+    return table[symbol.toUpperCase()];
+}
+/** List known coin symbols for a network. */
+export function knownSymbols(network) {
+    return Object.keys(COINS[network] ?? {});
+}
+//# sourceMappingURL=coins.js.map

package/dist/coins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coins.js","sourceRoot":"","sources":["../src/coins.ts"],"names":[],"mappings":"AAkBA,MAAM,GAAG,GAAG,8EAA8E,CAAC;AAE3F,wDAAwD;AACxD,MAAM,CAAC,MAAM,KAAK,GAA8C;IAC9D,OAAO,EAAE;QACP,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE;QACpF,MAAM,EAAE;YACN,MAAM,EAAE,QAAQ;YAChB,SAAS,EACP,oFAAoF;YACtF,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,+BAA+B;SAC7C;QACD,IAAI,EAAE;YACJ,MAAM,EAAE,MAAM;YACd,SAAS,EACP,gFAAgF;YAClF,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,mCAAmC;SACjD;KACF;IACD,OAAO,EAAE;QACP,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE;QACpF,IAAI,EAAE;YACJ,MAAM,EAAE,MAAM;YACd,SAAS,EACP,gFAAgF;YAClF,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,8BAA8B;SAC5C;QACD,IAAI,EAAE;YACJ,MAAM,EAAE,MAAM;YACd,SAAS,EACP,gFAAgF;YAClF,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,oCAAoC;SAClD;QACD,IAAI,EAAE;YACJ,MAAM,EAAE,MAAM;YACd,SAAS,EACP,gFAAgF;YAClF,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,yBAAyB;SACvC;QACD,GAAG,EAAE;YACH,MAAM,EAAE,KAAK;YACb,SAAS,EACP,8EAA8E;YAChF,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,sBAAsB;SACpC;KACF;IACD,MAAM,EAAE;QACN,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE;KACrF;CACF,CAAC;AAEF,+DAA+D;AAC/D,MAAM,UAAU,QAAQ,CAAC,OAAgB,EAAE,MAAc;IACvD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACnC,OAAO,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3C,CAAC"}

package/dist/deepbook.d.ts

@@ -0,0 +1,20 @@
+import type { Network } from './sui-client.js';
+/**
+ * DeepBook v3 on-chain constants, verified against @mysten/deepbook-v3
+ * (the official SDK) source. We hand-build the swap PTB on @mysten/sui v1
+ * rather than depend on that SDK, which now requires @mysten/sui v2.
+ *
+ * These are upgrade-stable but can change when DeepBook redeploys; every
+ * tool input can be overridden explicitly, so the registry is a
+ * convenience, not a hard dependency.
+ */
+export declare const DEEPBOOK_PACKAGE_ID: Record<Network, string>;
+/** DEEP coin type (used to pay trading fees) per network. */
+export declare const DEEP_TYPE: Record<Network, string>;
+export interface PoolInfo {
+    pool_id: string;
+    base_type: string;
+    quote_type: string;
+}
+/** Flagship pools by key. Override pool_id/base_type/quote_type to use others. */
+export declare const POOLS: Partial<Record<Network, Record<string, PoolInfo>>>;

package/dist/deepbook.js

@@ -0,0 +1,63 @@
+/**
+ * DeepBook v3 on-chain constants, verified against @mysten/deepbook-v3
+ * (the official SDK) source. We hand-build the swap PTB on @mysten/sui v1
+ * rather than depend on that SDK, which now requires @mysten/sui v2.
+ *
+ * These are upgrade-stable but can change when DeepBook redeploys; every
+ * tool input can be overridden explicitly, so the registry is a
+ * convenience, not a hard dependency.
+ */
+export const DEEPBOOK_PACKAGE_ID = {
+    testnet: '0x22be4cade64bf2d02412c7e8d0e8beea2f78828b948118d46735315409371a3c',
+    mainnet: '0x0e735f8c93a95722efd73521aca7a7652c0bb71ed1daf41b26dfd7d1ff71f748',
+    devnet: '',
+};
+/** DEEP coin type (used to pay trading fees) per network. */
+export const DEEP_TYPE = {
+    testnet: '0x36dbef866a1d62bf7328989a10fb2f07d769f4ee587c0de4a0a256e57e0a58a8::deep::DEEP',
+    mainnet: '0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP',
+    devnet: '',
+};
+const SUI = '0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI';
+const T_DBUSDC = '0xf7152c05930480cd740d7311b5b8b45c6f488e3a53a11c3f74a6fac36a52e0d7::DBUSDC::DBUSDC';
+const T_DEEP = DEEP_TYPE.testnet;
+const M_USDC = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
+const M_DEEP = DEEP_TYPE.mainnet;
+/** Flagship pools by key. Override pool_id/base_type/quote_type to use others. */
+export const POOLS = {
+    testnet: {
+        SUI_DBUSDC: {
+            pool_id: '0x1c19362ca52b8ffd7a33cee805a67d40f31e6ba303753fd3a4cfdfacea7163a5',
+            base_type: SUI,
+            quote_type: T_DBUSDC,
+        },
+        DEEP_SUI: {
+            pool_id: '0x48c95963e9eac37a316b7ae04a0deb761bcdcc2b67912374d6036e7f0e9bae9f',
+            base_type: T_DEEP,
+            quote_type: SUI,
+        },
+        DEEP_DBUSDC: {
+            pool_id: '0xe86b991f8632217505fd859445f9803967ac84a9d4a1219065bf191fcb74b622',
+            base_type: T_DEEP,
+            quote_type: T_DBUSDC,
+        },
+    },
+    mainnet: {
+        SUI_USDC: {
+            pool_id: '0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407',
+            base_type: SUI,
+            quote_type: M_USDC,
+        },
+        DEEP_SUI: {
+            pool_id: '0xb663828d6217467c8a1838a03793da896cbe745b150ebd57d82f814ca579fc22',
+            base_type: M_DEEP,
+            quote_type: SUI,
+        },
+        DEEP_USDC: {
+            pool_id: '0xf948981b806057580f91622417534f491da5f61aeaf33d0ed8e69fd5691c95ce',
+            base_type: M_DEEP,
+            quote_type: M_USDC,
+        },
+    },
+};
+//# sourceMappingURL=deepbook.js.map

package/dist/deepbook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepbook.js","sourceRoot":"","sources":["../src/deepbook.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAA4B;IAC1D,OAAO,EAAE,oEAAoE;IAC7E,OAAO,EAAE,oEAAoE;IAC7E,MAAM,EAAE,EAAE;CACX,CAAC;AAEF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,SAAS,GAA4B;IAChD,OAAO,EAAE,gFAAgF;IACzF,OAAO,EAAE,gFAAgF;IACzF,MAAM,EAAE,EAAE;CACX,CAAC;AAQF,MAAM,GAAG,GAAG,8EAA8E,CAAC;AAC3F,MAAM,QAAQ,GACZ,oFAAoF,CAAC;AACvF,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;AACjC,MAAM,MAAM,GAAG,gFAAgF,CAAC;AAChG,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;AAEjC,kFAAkF;AAClF,MAAM,CAAC,MAAM,KAAK,GAAuD;IACvE,OAAO,EAAE;QACP,UAAU,EAAE;YACV,OAAO,EAAE,oEAAoE;YAC7E,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,QAAQ;SACrB;QACD,QAAQ,EAAE;YACR,OAAO,EAAE,oEAAoE;YAC7E,SAAS,EAAE,MAAM;YACjB,UAAU,EAAE,GAAG;SAChB;QACD,WAAW,EAAE;YACX,OAAO,EAAE,oEAAoE;YAC7E,SAAS,EAAE,MAAM;YACjB,UAAU,EAAE,QAAQ;SACrB;KACF;IACD,OAAO,EAAE;QACP,QAAQ,EAAE;YACR,OAAO,EAAE,oEAAoE;YAC7E,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,MAAM;SACnB;QACD,QAAQ,EAAE;YACR,OAAO,EAAE,oEAAoE;YAC7E,SAAS,EAAE,MAAM;YACjB,UAAU,EAAE,GAAG;SAChB;QACD,SAAS,EAAE;YACT,OAAO,EAAE,oEAAoE;YAC7E,SAAS,EAAE,MAAM;YACjB,UAAU,EAAE,MAAM;SACnB;KACF;CACF,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Remote (Streamable HTTP) entrypoint — Web Standards flavour.
+ *
+ * `handleMcpRequest(request)` is a runtime-agnostic Fetch handler: it runs
+ * on Vercel Edge, Cloudflare Workers, Deno, Bun, and Node 18+. Wire it to
+ * an HTTPS route and add that URL to Claude as a Custom Connector to use
+ * the Suisei MCP from the Claude web and mobile apps.
+ *
+ * Stateless: a fresh server + transport per request (no session store),
+ * which is what serverless wants. Reads work great over a remote
+ * connector; transaction-building tools return unsigned bytes — signing
+ * still happens host-side, so a remote host needs its own signing path.
+ */
+export interface McpHttpOptions {
+    /**
+     * If set, requests must carry `Authorization: Bearer <token>`. Falls
+     * back to the SUISEI_MCP_TOKEN env var (with SUI_SKILLS_MCP_TOKEN kept
+     * as a compatibility alias). Leave unset only for local testing — a
+     * public endpoint without a token is open to the world.
+     */
+    authToken?: string;
+}
+/** Handle one MCP request over Streamable HTTP. */
+export declare function handleMcpRequest(request: Request, options?: McpHttpOptions): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,42 @@
+/**
+ * Remote (Streamable HTTP) entrypoint — Web Standards flavour.
+ *
+ * `handleMcpRequest(request)` is a runtime-agnostic Fetch handler: it runs
+ * on Vercel Edge, Cloudflare Workers, Deno, Bun, and Node 18+. Wire it to
+ * an HTTPS route and add that URL to Claude as a Custom Connector to use
+ * the Suisei MCP from the Claude web and mobile apps.
+ *
+ * Stateless: a fresh server + transport per request (no session store),
+ * which is what serverless wants. Reads work great over a remote
+ * connector; transaction-building tools return unsigned bytes — signing
+ * still happens host-side, so a remote host needs its own signing path.
+ */
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { createServer } from './server.js';
+function envToken() {
+    const env = globalThis.process?.env;
+    return env?.SUISEI_MCP_TOKEN ?? env?.SUI_SKILLS_MCP_TOKEN;
+}
+function unauthorized() {
+    return new Response(JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32001, message: 'unauthorized' },
+        id: null,
+    }), { status: 401, headers: { 'content-type': 'application/json' } });
+}
+/** Handle one MCP request over Streamable HTTP. */
+export async function handleMcpRequest(request, options = {}) {
+    const token = options.authToken ?? envToken();
+    if (token) {
+        const auth = request.headers.get('authorization') ?? '';
+        if (auth !== `Bearer ${token}`)
+            return unauthorized();
+    }
+    const server = createServer();
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined, // stateless
+    });
+    await server.connect(transport);
+    return transport.handleRequest(request);
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,wCAAwC,EAAE,MAAM,+DAA+D,CAAC;AACzH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C,SAAS,QAAQ;IACf,MAAM,GAAG,GAAI,UAA6D,CAAC,OAAO,EAAE,GAAG,CAAC;IACxF,OAAO,GAAG,EAAE,gBAAgB,IAAI,GAAG,EAAE,oBAAoB,CAAC;AAC5D,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC;QACb,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE;QAChD,EAAE,EAAE,IAAI;KACT,CAAC,EACF,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,CACjE,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgB,EAChB,UAA0B,EAAE;IAE5B,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,EAAE,CAAC;IAC9C,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;QACxD,IAAI,IAAI,KAAK,UAAU,KAAK,EAAE;YAAE,OAAO,YAAY,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC;QAC7D,kBAAkB,EAAE,SAAS,EAAE,YAAY;KAC5C,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * @suisei-mcp/mcp — stdio entrypoint.
+ *
+ * The product: the Suisei MCP server for the Sui stack. Plug into Claude
+ * Desktop, Cursor, or any MCP-aware agent and you get one-line tools to
+ * read chain state, call any Move function, transfer and stake SUI, mint
+ * badges, dry-run and submit transactions, and publish to Walrus.
+ *
+ * This entry uses stdio: the agent process spawns this binary and talks
+ * JSON-RPC over its stdin/stdout. For remote hosts (Claude Custom
+ * Connectors, web + mobile) use the HTTP entry in `http.ts` / `serve.ts`.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * @suisei-mcp/mcp — stdio entrypoint.
+ *
+ * The product: the Suisei MCP server for the Sui stack. Plug into Claude
+ * Desktop, Cursor, or any MCP-aware agent and you get one-line tools to
+ * read chain state, call any Move function, transfer and stake SUI, mint
+ * badges, dry-run and submit transactions, and publish to Walrus.
+ *
+ * This entry uses stdio: the agent process spawns this binary and talks
+ * JSON-RPC over its stdin/stdout. For remote hosts (Claude Custom
+ * Connectors, web + mobile) use the HTTP entry in `http.ts` / `serve.ts`.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;AAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Node HTTP bridge for the Streamable HTTP transport.
+ *
+ * `handleMcpRequest` (http.ts) speaks the Web Fetch API. This adapter lets
+ * it serve Node `http`-style handlers — used by both the standalone server
+ * (serve.ts) and a Vercel Node serverless function. Node runtime is needed
+ * (not Edge) because some tools use the Node `Buffer` global.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type McpHttpOptions } from './http.js';
+/** Serve one MCP request from a Node http req/res pair. */
+export declare function handleNodeRequest(req: IncomingMessage, res: ServerResponse, options?: McpHttpOptions): Promise<void>;

package/dist/node.js

@@ -0,0 +1,54 @@
+/**
+ * Node HTTP bridge for the Streamable HTTP transport.
+ *
+ * `handleMcpRequest` (http.ts) speaks the Web Fetch API. This adapter lets
+ * it serve Node `http`-style handlers — used by both the standalone server
+ * (serve.ts) and a Vercel Node serverless function. Node runtime is needed
+ * (not Edge) because some tools use the Node `Buffer` global.
+ */
+import { handleMcpRequest } from './http.js';
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+async function toFetchRequest(req) {
+    const host = req.headers.host ?? 'localhost';
+    const url = new URL(req.url ?? '/', `http://${host}`);
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (Array.isArray(v))
+            v.forEach((vv) => headers.append(k, vv));
+        else if (v != null)
+            headers.set(k, v);
+    }
+    const method = req.method ?? 'GET';
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    const body = hasBody ? await readBody(req) : undefined;
+    return new Request(url, { method, headers, body: body && body.length ? body : undefined });
+}
+/** Serve one MCP request from a Node http req/res pair. */
+export async function handleNodeRequest(req, res, options = {}) {
+    try {
+        const response = await handleMcpRequest(await toFetchRequest(req), options);
+        const buf = Buffer.from(await response.arrayBuffer());
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        res.writeHead(response.status, headers);
+        res.end(buf);
+    }
+    catch (e) {
+        res.writeHead(500, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32603, message: e instanceof Error ? e.message : String(e) },
+            id: null,
+        }));
+    }
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,WAAW,CAAC;AAElE,SAAS,QAAQ,CAAC,GAAoB;IACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAW,CAAC,CAAC,CAAC;QAChD,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,GAAoB;IAChD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;aAC1D,IAAI,CAAC,IAAI,IAAI;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;IACnC,MAAM,OAAO,GAAG,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,CAAC;IACtD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvD,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;AAC7F,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAoB,EACpB,GAAmB,EACnB,UAA0B,EAAE;IAE5B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAC5E,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QACtD,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACtC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACvB,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACxC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC3D,GAAG,CAAC,GAAG,CACL,IAAI,CAAC,SAAS,CAAC;YACb,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YAC5E,EAAE,EAAE,IAAI;SACT,CAAC,CACH,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/serve.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Standalone HTTP entrypoint — host the Suisei MCP anywhere.
+ *
+ *   PORT=8787 SUISEI_MCP_TOKEN=secret npx suisei-mcp-serve
+ *
+ * Spins up a Node HTTP server and serves the Streamable HTTP transport via
+ * the shared node bridge. Point a Claude Custom Connector at
+ * https://<host>/ to use the toolkit from the Claude web and mobile apps.
+ * For serverless (Vercel Node / Cloudflare) call handleNodeRequest /
+ * handleMcpRequest from a route instead.
+ */
+export {};

package/dist/serve.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Standalone HTTP entrypoint — host the Suisei MCP anywhere.
+ *
+ *   PORT=8787 SUISEI_MCP_TOKEN=secret npx suisei-mcp-serve
+ *
+ * Spins up a Node HTTP server and serves the Streamable HTTP transport via
+ * the shared node bridge. Point a Claude Custom Connector at
+ * https://<host>/ to use the toolkit from the Claude web and mobile apps.
+ * For serverless (Vercel Node / Cloudflare) call handleNodeRequest /
+ * handleMcpRequest from a route instead.
+ */
+import { createServer as createHttpServer } from 'node:http';
+import { handleNodeRequest } from './node.js';
+function envVar(name) {
+    return globalThis.process?.env?.[name];
+}
+const PORT = Number(envVar('PORT') ?? 8787);
+const httpServer = createHttpServer((req, res) => {
+    void handleNodeRequest(req, res);
+});
+httpServer.listen(PORT, () => {
+    process.stderr.write(`suisei-mcp HTTP server on http://localhost:${PORT}\n`);
+});
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAQ,UAA6D,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;AAE5C,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IAC/C,KAAK,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC,CAAC,CAAC;AAEH,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,IAAI,IAAI,CAAC,CAAC;AAC/E,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @suisei-mcp/mcp — server factory.
+ *
+ * Builds the Suisei MCP server with the full Sui-stack tool registry.
+ * Transport is chosen by the entrypoint: `index.ts` (stdio) for local
+ * hosts like Claude Desktop and Cursor; `http.ts` (Streamable HTTP) for
+ * remote hosts like Claude's Custom Connectors (web + mobile). Both call
+ * createServer() so there is exactly one tool registry.
+ *
+ * Write tools never hold keys — they return unsigned tx bytes for the
+ * host to sign, then sui_execute_signed_tx submits the signed result.
+ *
+ * The server identifies itself as "suisei" over the MCP protocol; tool
+ * names keep the sui_ prefix because they wrap the Sui chain, not the
+ * Suisei brand. Suisei is the agent toolkit; Sui is the chain it speaks.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare const PKG_VERSION = "0.1.0";
+/** Build a fresh MCP server with every Sui-stack tool registered. */
+export declare function createServer(): Server;