@dimcool/mcp 0.1.0 → 0.1.2

package/README.md

@@ -21,7 +21,7 @@ Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
       "command": "npx",
       "args": ["@dimcool/mcp"],
       "env": {
-        "DIM_WALLET_PRIVATE_KEY": "your-base58-solana-private-key",
+        "DIM_WALLET_STORE_PATH": "/absolute/path/to/mcp-wallet.json",
         "DIM_API_URL": "https://api.dim.cool"
       }
     }
@@ -29,20 +29,62 @@ Add to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):
 }
 ```
 
+### Bootstrap a wallet locally (recommended)
+
+Create a local non-custodial wallet file (private key never leaves your machine):
+
+```bash
+npx @dimcool/mcp init-wallet
+```
+
+This prints:
+
+- your public Solana address
+- the local wallet store path
+- the env snippet to add to your MCP config
+
+### Bring your own key (advanced)
+
+If you already have a wallet:
+
+```bash
+DIM_WALLET_PRIVATE_KEY=<base58-key> npx @dimcool/mcp
+```
+
 ### Environment Variables
 
-| Variable                 | Required | Description                                    |
-| ------------------------ | -------- | ---------------------------------------------- |
-| `DIM_WALLET_PRIVATE_KEY` | Yes      | Base58-encoded Solana private key              |
-| `DIM_API_URL`            | No       | API base URL (default: `https://api.dim.cool`) |
-| `DIM_REFERRAL_CODE`      | No       | Referral code to use on first signup           |
+| Variable                 | Required | Description                                                         |
+| ------------------------ | -------- | ------------------------------------------------------------------- |
+| `DIM_WALLET_PRIVATE_KEY` | No\*     | Base58-encoded Solana private key                                   |
+| `DIM_WALLET_STORE_PATH`  | No       | Local path to wallet store file (default: `~/.dim/mcp-wallet.json`) |
+| `DIM_WALLET_AUTO_CREATE` | No       | If `true`, auto-creates/stores a wallet when key/store is missing   |
+| `DIM_API_URL`            | No       | API base URL (default: `https://api.dim.cool`)                      |
+| `DIM_REFERRAL_CODE`      | No       | Referral code to use on first signup                                |
+
+\*Required if you do not use wallet store or auto-create.
 
 ### Wallet Auth Configuration
 
-- `@dimcool/mcp` uses `DIM_WALLET_PRIVATE_KEY` directly for wallet-based login and signing.
+- `@dimcool/mcp` supports three wallet startup modes:
+  1. direct key (`DIM_WALLET_PRIVATE_KEY`)
+  2. local wallet store (`DIM_WALLET_STORE_PATH`)
+  3. auto-create (`DIM_WALLET_AUTO_CREATE=true`)
 - Call `dim_login` before any wallet, games, chat, social, referrals, support, or market tools.
+- Call `dim_get_balance` after login and before paid actions.
 - To generate/export a Base58 key programmatically, use [@dimcool/wallet](https://docs.dim.cool/guides/wallet-package).
 
+### Funding your wallet
+
+- Send **USDC on Solana** to the wallet public address shown during bootstrap/import.
+- Most paid actions (transfers, game bets, market buys) require USDC balance.
+- If balance is low, agents should ask users to fund first, then retry.
+- You can still start referral growth without pre-funding: onboarding referred users who play can earn rewards.
+
+### Skill templates for agent platforms
+
+- OpenClaw starter skill: `skills/openclaw-dim/SKILL.md`
+- Hermes starter skill: `skills/hermes-dim/SKILL.md`
+
 ## Available Tools
 
 ### Authentication

package/dist/index.js

@@ -7,7 +7,19 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/index.ts
+import {
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  stat,
+  writeFile
+} from "fs/promises";
+import os from "os";
+import path from "path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Keypair as Keypair3 } from "@solana/web3.js";
+import bs582 from "bs58";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -6489,14 +6501,14 @@ var require_url_state_machine = __commonJS({
       return url2.replace(/\u0009|\u000A|\u000D/g, "");
     }
     function shortenPath(url2) {
-      const path = url2.path;
-      if (path.length === 0) {
+      const path2 = url2.path;
+      if (path2.length === 0) {
         return;
       }
-      if (url2.scheme === "file" && path.length === 1 && isNormalizedWindowsDriveLetter(path[0])) {
+      if (url2.scheme === "file" && path2.length === 1 && isNormalizedWindowsDriveLetter(path2[0])) {
         return;
       }
-      path.pop();
+      path2.pop();
     }
     function includesCredentials(url2) {
       return url2.username !== "" || url2.password !== "";
@@ -7543,15 +7555,15 @@ var require_node_gyp_build = __commonJS({
   "../../node_modules/node-gyp-build/node-gyp-build.js"(exports, module) {
     "use strict";
     var fs = __require2("fs");
-    var path = __require2("path");
-    var os = __require2("os");
+    var path2 = __require2("path");
+    var os2 = __require2("os");
     var runtimeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : __require2;
     var vars = process.config && process.config.variables || {};
     var prebuildsOnly = !!process.env.PREBUILDS_ONLY;
     var abi = process.versions.modules;
     var runtime = isElectron() ? "electron" : isNwjs() ? "node-webkit" : "node";
-    var arch = process.env.npm_config_arch || os.arch();
-    var platform = process.env.npm_config_platform || os.platform();
+    var arch = process.env.npm_config_arch || os2.arch();
+    var platform = process.env.npm_config_platform || os2.platform();
     var libc = process.env.LIBC || (isAlpine(platform) ? "musl" : "glibc");
     var armv = process.env.ARM_VERSION || (arch === "arm64" ? "8" : vars.arm_version) || "";
     var uv = (process.versions.uv || "").split(".")[0];
@@ -7560,21 +7572,21 @@ var require_node_gyp_build = __commonJS({
       return runtimeRequire(load.resolve(dir));
     }
     load.resolve = load.path = function(dir) {
-      dir = path.resolve(dir || ".");
+      dir = path2.resolve(dir || ".");
       try {
-        var name = runtimeRequire(path.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
+        var name = runtimeRequire(path2.join(dir, "package.json")).name.toUpperCase().replace(/-/g, "_");
         if (process.env[name + "_PREBUILD"]) dir = process.env[name + "_PREBUILD"];
       } catch (err) {
       }
       if (!prebuildsOnly) {
-        var release = getFirst(path.join(dir, "build/Release"), matchBuild);
+        var release = getFirst(path2.join(dir, "build/Release"), matchBuild);
         if (release) return release;
-        var debug = getFirst(path.join(dir, "build/Debug"), matchBuild);
+        var debug = getFirst(path2.join(dir, "build/Debug"), matchBuild);
         if (debug) return debug;
       }
       var prebuild = resolve(dir);
       if (prebuild) return prebuild;
-      var nearby = resolve(path.dirname(process.execPath));
+      var nearby = resolve(path2.dirname(process.execPath));
       if (nearby) return nearby;
       var target = [
         "platform=" + platform,
@@ -7591,14 +7603,14 @@ var require_node_gyp_build = __commonJS({
       ].filter(Boolean).join(" ");
       throw new Error("No native build was found for " + target + "\n    loaded from: " + dir + "\n");
       function resolve(dir2) {
-        var tuples = readdirSync(path.join(dir2, "prebuilds")).map(parseTuple);
+        var tuples = readdirSync(path2.join(dir2, "prebuilds")).map(parseTuple);
         var tuple2 = tuples.filter(matchTuple(platform, arch)).sort(compareTuples)[0];
         if (!tuple2) return;
-        var prebuilds = path.join(dir2, "prebuilds", tuple2.name);
+        var prebuilds = path2.join(dir2, "prebuilds", tuple2.name);
         var parsed = readdirSync(prebuilds).map(parseTags);
         var candidates = parsed.filter(matchTags(runtime, abi));
         var winner = candidates.sort(compareTags(runtime))[0];
-        if (winner) return path.join(prebuilds, winner.file);
+        if (winner) return path2.join(prebuilds, winner.file);
       }
     };
     function readdirSync(dir) {
@@ -7610,7 +7622,7 @@ var require_node_gyp_build = __commonJS({
     }
     function getFirst(dir, filter) {
       var files = readdirSync(dir).filter(filter);
-      return files[0] && path.join(dir, files[0]);
+      return files[0] && path2.join(dir, files[0]);
     }
     function matchBuild(name) {
       return /\.node$/.test(name);
@@ -15332,8 +15344,8 @@ var StructError = class extends TypeError {
   constructor(failure, failures) {
     let cached;
     const { message, explanation, ...rest } = failure;
-    const { path } = failure;
-    const msg = path.length === 0 ? message : `At path: ${path.join(".")} -- ${message}`;
+    const { path: path2 } = failure;
+    const msg = path2.length === 0 ? message : `At path: ${path2.join(".")} -- ${message}`;
     super(explanation ?? msg);
     if (explanation != null)
       this.cause = msg;
@@ -15371,15 +15383,15 @@ function toFailure(result, context, struct2, value) {
   } else if (typeof result === "string") {
     result = { message: result };
   }
-  const { path, branch } = context;
+  const { path: path2, branch } = context;
   const { type: type2 } = struct2;
   const { refinement, message = `Expected a value of type \`${type2}\`${refinement ? ` with refinement \`${refinement}\`` : ""}, but received: \`${print(value)}\`` } = result;
   return {
     value,
     type: type2,
     refinement,
-    key: path[path.length - 1],
-    path,
+    key: path2[path2.length - 1],
+    path: path2,
     branch,
     ...result,
     message
@@ -15397,8 +15409,8 @@ function* toFailures(result, context, struct2, value) {
   }
 }
 function* run(value, struct2, options = {}) {
-  const { path = [], branch = [value], coerce: coerce2 = false, mask: mask2 = false } = options;
-  const ctx = { path, branch, mask: mask2 };
+  const { path: path2 = [], branch = [value], coerce: coerce2 = false, mask: mask2 = false } = options;
+  const ctx = { path: path2, branch, mask: mask2 };
   if (coerce2) {
     value = struct2.coercer(value, ctx);
   }
@@ -15410,7 +15422,7 @@ function* run(value, struct2, options = {}) {
   }
   for (let [k, v, s] of struct2.entries(value, ctx)) {
     const ts = run(v, s, {
-      path: k === void 0 ? path : [...path, k],
+      path: k === void 0 ? path2 : [...path2, k],
       branch: k === void 0 ? branch : [...branch, v],
       coerce: coerce2,
       mask: mask2,
@@ -26838,10 +26850,135 @@ function createDimMcpServer(config) {
 }
 
 // src/index.ts
-var walletPrivateKey = process.env.DIM_WALLET_PRIVATE_KEY;
+var DEFAULT_WALLET_STORE_PATH = path.join(
+  os.homedir(),
+  ".dim",
+  "mcp-wallet.json"
+);
+function parseBooleanFlag(value) {
+  if (!value) return false;
+  return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+function resolveWalletStorePath(cliArgs2) {
+  const storeFlagIndex = cliArgs2.indexOf("--store");
+  if (storeFlagIndex !== -1) {
+    const value = cliArgs2[storeFlagIndex + 1];
+    if (!value || value.startsWith("--")) {
+      throw new Error(
+        "Missing value for --store. Example: npx @dimcool/mcp init-wallet --store ~/.dim/mcp-wallet.json"
+      );
+    }
+    if (value.startsWith("~/")) {
+      return path.join(os.homedir(), value.slice(2));
+    }
+    return path.resolve(value);
+  }
+  const envPath = process.env.DIM_WALLET_STORE_PATH?.trim();
+  if (envPath) {
+    if (envPath.startsWith("~/")) {
+      return path.join(os.homedir(), envPath.slice(2));
+    }
+    return path.resolve(envPath);
+  }
+  return DEFAULT_WALLET_STORE_PATH;
+}
+async function writeWalletStoreFile(storePath, record2) {
+  await mkdir(path.dirname(storePath), { recursive: true });
+  const tmpPath = `${storePath}.tmp`;
+  await writeFile(tmpPath, `${JSON.stringify(record2, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  await chmod(tmpPath, 384);
+  await rename(tmpPath, storePath);
+}
+async function readWalletStoreFile(storePath) {
+  try {
+    const raw = await readFile(storePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.walletPrivateKey && parsed.walletAddress) {
+      return {
+        version: 1,
+        walletAddress: parsed.walletAddress,
+        walletPrivateKey: parsed.walletPrivateKey,
+        createdAt: parsed.createdAt || (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function createWalletRecord() {
+  const keypair = Keypair3.generate();
+  return {
+    version: 1,
+    walletAddress: keypair.publicKey.toBase58(),
+    walletPrivateKey: bs582.encode(keypair.secretKey),
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function walletStoreExists(storePath) {
+  try {
+    await stat(storePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function handleInitWallet(cliArgs2) {
+  const force = cliArgs2.includes("--force");
+  const storePath = resolveWalletStorePath(cliArgs2);
+  const exists = await walletStoreExists(storePath);
+  if (exists && !force) {
+    console.error(
+      `Wallet store already exists at ${storePath}.
+Use --force to overwrite, or remove the file first.`
+    );
+    process.exit(1);
+  }
+  const record2 = await createWalletRecord();
+  await writeWalletStoreFile(storePath, record2);
+  console.log("DIM wallet created and stored locally.");
+  console.log(`Public address: ${record2.walletAddress}`);
+  console.log(`Store path: ${storePath}`);
+  console.log("");
+  console.log("Add this to your MCP env config:");
+  console.log(`  DIM_WALLET_STORE_PATH="${storePath}"`);
+  console.log('  DIM_API_URL="https://api.dim.cool"');
+  console.log("");
+  console.log(
+    "Next step: fund this wallet with USDC on Solana, then call dim_login and dim_get_balance."
+  );
+}
+async function resolveWalletPrivateKey(cliArgs2) {
+  const direct = process.env.DIM_WALLET_PRIVATE_KEY?.trim();
+  if (direct) return direct;
+  const storePath = resolveWalletStorePath(cliArgs2);
+  const record2 = await readWalletStoreFile(storePath);
+  if (record2?.walletPrivateKey) return record2.walletPrivateKey;
+  if (parseBooleanFlag(process.env.DIM_WALLET_AUTO_CREATE)) {
+    const newRecord = await createWalletRecord();
+    await writeWalletStoreFile(storePath, newRecord);
+    console.error(
+      `DIM wallet auto-created. Public address: ${newRecord.walletAddress}
+Stored at: ${storePath}
+Fund this wallet with USDC on Solana before paid actions.`
+    );
+    return newRecord.walletPrivateKey;
+  }
+  return null;
+}
+var cliArgs = process.argv.slice(2);
+if (cliArgs[0] === "init-wallet") {
+  await handleInitWallet(cliArgs.slice(1));
+  process.exit(0);
+}
+var walletPrivateKey = await resolveWalletPrivateKey(cliArgs);
 if (!walletPrivateKey) {
   console.error(
-    "Error: DIM_WALLET_PRIVATE_KEY environment variable is required.\nSet it to your Base58-encoded Solana private key.\n\nExample:\n  DIM_WALLET_PRIVATE_KEY=your-key npx @dimcool/mcp"
+    "Error: DIM wallet key is not configured.\nProvide DIM_WALLET_PRIVATE_KEY, or initialize a local wallet store.\n\nExamples:\n  DIM_WALLET_PRIVATE_KEY=your-base58-key npx @dimcool/mcp\n  npx @dimcool/mcp init-wallet\n  DIM_WALLET_AUTO_CREATE=true npx @dimcool/mcp"
   );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimcool/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for DIM — lets AI agents play games, chat, send USDC, and earn referral income on the DIM platform",
   "type": "module",
   "bin": {