@cloakely/mcp 0.3.0 → 0.5.0

package/README.md

@@ -6,6 +6,12 @@ An agent that trades on chain leaks its strategy with every transaction, and any
 
 **Testnet only for now** (Elysium testnet, chain `99801`). Play money only.
 
+**The easy way:** tell your agent
+
+> Read https://cloak.boblabs.tech/agent.md and set me up to trade privately.
+
+That page is written for agents. The agent sets up its own wallet and the connection, and asks you only for what it can't do itself (free testnet HYPE from the faucet). It never needs your own wallet's key.
+
 There are two ways in:
 
 | | Hosted link | Local server (this package) |
@@ -25,16 +31,18 @@ Its tools: `cloak_info`, `list_launches`, `get_launch`, `quote_bid`, `quote_swap
 
 ## Set up the local server
 
-Create a fresh wallet for the agent, fund it from the [Elysium faucet](https://elysium.kinetiq.xyz/testnet-faucet), and put its private key in a file only you can read:
+Make the agent's own wallet. It's saved in `~/.cloak-agent-key`, readable by you only, and the key is never printed:
 
 ```sh
-umask 077 && echo 0xYOUR_AGENT_KEY > ~/.cloak-agent-key
+npx -y @cloakely/mcp setup
 ```
 
+It prints the wallet's address. Fund it with free testnet HYPE from the [Elysium faucet](https://elysium.kinetiq.xyz/testnet-faucet). Running it again keeps the same wallet.
+
 **Claude Code:**
 
 ```sh
-claude mcp add cloak --env CLOAK_KEY_FILE=$HOME/.cloak-agent-key -- npx -y @cloakely/mcp
+claude mcp add cloak -- npx -y @cloakely/mcp
 ```
 
 **Claude Desktop, Cursor and other clients** (`claude_desktop_config.json`, `.cursor/mcp.json`, and so on):
@@ -42,16 +50,14 @@ claude mcp add cloak --env CLOAK_KEY_FILE=$HOME/.cloak-agent-key -- npx -y @cloa
 ```json
 {
   "mcpServers": {
-    "cloak": {
-      "command": "npx",
-      "args": ["-y", "@cloakely/mcp"],
-      "env": { "CLOAK_KEY_FILE": "/Users/you/.cloak-agent-key" }
-    }
+    "cloak": { "command": "npx", "args": ["-y", "@cloakely/mcp"] }
   }
 }
 ```
 
-Without a key, the server is **read only**: the agent can browse launches and quote bids and swaps, but can't sign anything.
+The server uses `~/.cloak-agent-key` when nothing else is set. To use another wallet, set `CLOAK_KEY_FILE` (or `CLOAK_PRIVATE_KEY`) in the server's `env`.
+
+Without a key (no `~/.cloak-agent-key` and nothing set), the server is **read only**: the agent can browse launches and quote bids and swaps, but can't sign anything.
 
 Then ask, for example:
 - "What Cloak launches are open right now?"
@@ -98,7 +104,7 @@ Amounts are in whole units (`"0.5"` HYPE). `private_send`, `withdraw` and a `pri
 
 | Variable | Default | |
 |---|---|---|
-| `CLOAK_KEY_FILE` | | File holding the agent wallet's private key (preferred) |
+| `CLOAK_KEY_FILE` | `~/.cloak-agent-key` if it exists | File holding the agent wallet's private key |
 | `CLOAK_PRIVATE_KEY` | | The key itself, if a file isn't practical |
 | `CLOAK_NETWORK` | `testnet` | `testnet`, or `custom` with `CLOAK_DEPLOYMENT_FILE` |
 | `CLOAK_MAX_HYPE_PER_TX` | `1` | HYPE value per transaction |

package/dist/config.d.ts

@@ -1,5 +1,7 @@
 import { type Chain, type Hex } from "viem";
 import { type CloakDeployment } from "@cloakely/sdk";
+/** The agent wallet's key file that `setup` creates and the server uses when no key is configured. */
+export declare const defaultKeyFile: () => string;
 /** Where the server points, and what it may do. Everything comes from environment variables (see README). */
 export interface Settings {
     network: string;

package/dist/config.js

@@ -1,8 +1,10 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createPublicClient, defineChain, http, parseEther, parseUnits } from "viem";
 import { deploymentFor, elysiumTestnet, liveDeployment } from "@cloakely/sdk";
+/** The agent wallet's key file that `setup` creates and the server uses when no key is configured. */
+export const defaultKeyFile = () => join(homedir(), ".cloak-agent-key");
 const NETWORKS = {
     testnet: { chain: elysiumTestnet },
 };
@@ -49,6 +51,9 @@ export function loadSettings(env = process.env) {
     let key = env.CLOAK_PRIVATE_KEY?.trim();
     if (!key && env.CLOAK_KEY_FILE)
         key = readFileSync(env.CLOAK_KEY_FILE, "utf8").trim();
+    // the wallet `npx @cloakely/mcp setup` made, when nothing else is configured
+    else if (!key && existsSync(defaultKeyFile()))
+        key = readFileSync(defaultKeyFile(), "utf8").trim();
     if (key && !key.startsWith("0x"))
         key = `0x${key}`;
     if (key && !/^0x[0-9a-fA-F]{64}$/.test(key))

package/dist/index.js

@@ -1,8 +1,17 @@
 #!/usr/bin/env node
-// Cloak's MCP server over stdio: `npx @cloakely/mcp`. Configuration is environment variables only (see README).
+// Cloak's MCP server over stdio: `npx @cloakely/mcp`. Configuration is environment variables (see README).
+// `npx @cloakely/mcp setup` makes the agent's wallet in ~/.cloak-agent-key, which the server then uses by default.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createCloakServer, loadSettings, VERSION } from "./server.js";
 import { withLiveDeployment } from "./config.js";
+import { setup } from "./setup.js";
+if (process.argv[2] === "setup") {
+    // make the agent's wallet and print what's left to do (see https://cloak.boblabs.tech/agent.md)
+    await setup().then(() => process.exit(0), (e) => {
+        console.error(`cloak-mcp setup: ${e.message}`);
+        process.exit(1);
+    });
+}
 try {
     const settings = await withLiveDeployment(loadSettings());
     const server = createCloakServer(settings);

package/dist/server.d.ts

@@ -3,7 +3,7 @@ import { type Prover } from "@cloakely/sdk";
 import type { Settings } from "./config.js";
 export { loadSettings, type Settings, type Limits } from "./config.js";
 export { Spending } from "./limits.js";
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.5.0";
 export declare const HOSTED_URL = "https://cloak.boblabs.tech/mcp";
 /** Turn an SDK or chain error into one plain sentence an agent can act on. */
 export declare function explain(e: unknown): string;

package/dist/server.js

@@ -4,11 +4,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { createPublicClient, createWalletClient, erc20Abi, formatEther, formatUnits, http, isAddress, parseEther, parseUnits, zeroAddress, } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
-import { Cloak, CloakPrivate, cloakAuctionAbi, cloakPairAbi, cloakVaultsAbi, createProver, loadProver, privateRouterAbi, relayerSubmitter, shieldedPoolAbi, } from "@cloakely/sdk";
+import { Cloak, CloakPrivate, cloakAuctionAbi, cloakPairAbi, cloakVaultsAbi, legacyFactories, createProver, loadProver, privateRouterAbi, relayerSubmitter, shieldedPoolAbi, } from "@cloakely/sdk";
 import { Spending } from "./limits.js";
 export { loadSettings } from "./config.js";
 export { Spending } from "./limits.js";
-export const VERSION = "0.3.0";
+export const VERSION = "0.5.0";
 export const HOSTED_URL = "https://cloak.boblabs.tech/mcp";
 const INSTRUCTIONS = `Cloak: sealed-bid token launches and private trading on Kinetiq's Elysium (HYPE is the gas and base currency).
 
@@ -79,10 +79,11 @@ export function createCloakServer(settings, opts = {}) {
     const account = settings.privateKey ? privateKeyToAccount(settings.privateKey) : undefined;
     const wallet = account ? createWalletClient({ chain: settings.chain, transport: http(settings.rpcUrl), account }) : undefined;
     // earlier deployments' launches still list, settle and pay out
-    const cloak = new Cloak(pub, wallet, d.factory, (d.previous ?? []).map((p) => p.factory));
-    /** Where to start scanning a launch's bids: the current factory's deploy block, or the start for an older launch. */
-    const bidsFrom = async (auction) => (await pub.readContract({ address: auction, abi: [{ type: "function", name: "factory", stateMutability: "view", inputs: [], outputs: [{ type: "address" }] }], functionName: "factory" }).catch(() => zeroAddress)).toLowerCase() === d.factory.toLowerCase()
-        ? settings.launchesFromBlock
+    const cloak = new Cloak(pub, wallet, d.factory, legacyFactories(d));
+    /** Where to start scanning a launch's bids: this deployment's first factory block, or the start for an older launch. */
+    const ours = new Set([d.factory, ...(d.earlierFactories ?? [])].map((f) => f.toLowerCase()));
+    const bidsFrom = async (auction) => ours.has((await pub.readContract({ address: auction, abi: [{ type: "function", name: "factory", stateMutability: "view", inputs: [], outputs: [{ type: "address" }] }], functionName: "factory" }).catch(() => zeroAddress)).toLowerCase())
+        ? (d.firstFactoryBlock !== undefined && d.firstFactoryBlock < settings.launchesFromBlock ? d.firstFactoryBlock : settings.launchesFromBlock)
         : 0n;
     const spending = account ? new Spending(settings.limits, settings.stateDir, account.address) : undefined;
     const submit = relayerSubmitter(d.relayerUrl);
@@ -393,14 +394,14 @@ export function createCloakServer(settings, opts = {}) {
         }));
         server.registerTool("connect_full_agent", { title: "Connect a full agent", description: "How to let an agent launch, bid and trade privately: the local Cloak MCP server, which signs on your own machine under spending limits.", inputSchema: {}, annotations: READ }, safe(async () => ({
             why: "This hosted server never holds keys, so it can read and plan but not sign. Launching, bidding and private trading run in the local server, on the machine that holds the agent's wallet. Its proofs are made there too, so nobody else, Cloak included, can see or move the funds.",
+            easiest: "If you can run terminal commands, read https://cloak.boblabs.tech/agent.md and follow it: it sets everything up and says what to ask the person. If you can't (a chat app), tell the person to open that link in Claude Code, Claude Desktop or Cursor and ask the agent there to follow it.",
             steps: [
-                "Make a fresh wallet just for the agent and fund it with testnet HYPE from https://elysium.kinetiq.xyz/testnet-faucet",
-                "Save its private key to a file only you can read, for example ~/.cloak-agent-key",
-                "Claude Code: claude mcp add cloak --env CLOAK_KEY_FILE=$HOME/.cloak-agent-key -- npx -y @cloakely/mcp",
-                'Other clients: { "mcpServers": { "cloak": { "command": "npx", "args": ["-y", "@cloakely/mcp"], "env": { "CLOAK_KEY_FILE": "/path/to/key" } } } }',
+                "npx -y @cloakely/mcp setup (makes the agent's own wallet in ~/.cloak-agent-key and prints its address; the key is never printed)",
+                "Claude Code: claude mcp add cloak -- npx -y @cloakely/mcp. Other clients: { \"mcpServers\": { \"cloak\": { \"command\": \"npx\", \"args\": [\"-y\", \"@cloakely/mcp\"] } } }",
+                "The person gets free testnet HYPE for the agent's address at https://elysium.kinetiq.xyz/testnet-faucet",
             ],
             safety: "Spending limits per transaction and per day (1 HYPE and 10 HYPE by default, set with CLOAK_MAX_HYPE_PER_TX and CLOAK_MAX_HYPE_PER_DAY), dry_run on every action, testnet by default. Never paste a key into a chat or into this hosted server.",
-            docs: "https://github.com/NECOKIZZ/Cloak/tree/main/packages/mcp",
+            docs: "https://cloak.boblabs.tech/agent.md",
         })));
         return server;
     }

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export declare function setup(): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,41 @@
+// `npx -y @cloakely/mcp setup`: make the agent's own wallet (once) and say what's left to do, in words an agent can pass
+// on to a person. Written for agents following https://cloak.boblabs.tech/agent.md. The key is never printed.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createPublicClient, formatEther, http } from "viem";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { elysiumTestnet } from "@cloakely/sdk";
+import { defaultKeyFile } from "./config.js";
+const FAUCET = "https://elysium.kinetiq.xyz/testnet-faucet";
+export async function setup() {
+    const file = process.env.CLOAK_KEY_FILE || defaultKeyFile();
+    let made = false;
+    if (!existsSync(file)) {
+        // owner-only from the start; `wx` refuses to overwrite a file that appeared in between
+        writeFileSync(file, `${generatePrivateKey()}\n`, { mode: 0o600, flag: "wx" });
+        made = true;
+    }
+    let key = readFileSync(file, "utf8").trim();
+    if (!key.startsWith("0x"))
+        key = `0x${key}`;
+    if (!/^0x[0-9a-fA-F]{64}$/.test(key))
+        throw new Error(`${file} doesn't hold a private key. Move it aside and run setup again.`);
+    const address = privateKeyToAccount(key).address;
+    const pub = createPublicClient({ chain: elysiumTestnet, transport: http(undefined, { timeout: 15_000 }) });
+    const balance = await pub.getBalance({ address }).catch(() => undefined);
+    const funded = balance !== undefined && balance > 0n;
+    const out = {
+        status: made ? "Made a new wallet for the agent." : "The agent's wallet already exists. Kept it.",
+        agentWallet: address,
+        keyFile: `${file} (readable by this user only, never printed and never sent anywhere)`,
+        network: "Elysium testnet (play money only)",
+        balance: balance === undefined ? "couldn't read it right now" : `${formatEther(balance)} HYPE`,
+        next: [
+            "Add the Cloak MCP server to this app if it isn't there yet. Claude Code: claude mcp add cloak -- npx -y @cloakely/mcp. Any other app: an MCP server with command npx and args -y @cloakely/mcp. It uses this wallet without any settings.",
+            funded
+                ? "The wallet has HYPE, so it's ready."
+                : `Ask the person to get free testnet HYPE for ${address} at ${FAUCET}. Copy the address for them exactly. Agents can't use the faucet themselves.`,
+            "Tell the person to restart the app or start a new chat so the Cloak tools load, then call cloak_info to check.",
+        ],
+    };
+    console.log(JSON.stringify(out, null, 2));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloakely/mcp",
   "mcpName": "io.github.NECOKIZZ/cloak",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Cloak's MCP server: let an AI agent launch tokens with sealed bids and trade them privately on Elysium, with spending limits, testnet by default and a local signer.",
   "keywords": [
     "mcp",
@@ -47,7 +47,7 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "viem": "2.21.54",
     "zod": "4.6.7",
-    "@cloakely/sdk": "^0.4.0"
+    "@cloakely/sdk": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "22.10.2",