@openclawcash/mcp-server 0.1.0

package/.env.example

@@ -0,0 +1,2 @@
+OPENCLAWCASH_AGENT_KEY=occ_your_api_key_here
+OPENCLAWCASH_BASE_URL=https://openclawcash.com

package/README.md

@@ -0,0 +1,272 @@
+# OpenClawCash MCP Server
+
+This folder contains the public OpenClawCash stdio MCP server package that exposes OpenClawCash agent wallet operations as MCP tools.
+
+It is a thin adapter over the existing OpenClawCash agent API at `https://openclawcash.com/api/agent/*`.
+
+Canonical docs page: `https://openclawcash.com/mcp`
+
+## What It Exposes
+
+- `wallets_list`
+- `wallet_get`
+- `transactions_list`
+- `balances_get`
+- `supported_tokens_list`
+- `transfer_send`
+- `swap_quote`
+- `swap_execute`
+- `approve_token`
+- `wallet_create`
+- `wallet_import`
+
+It also exposes two lightweight MCP resources:
+
+- `openclawcash://approval-modes`
+- `openclawcash://quickstart`
+
+## Run It
+
+Direct from npm:
+
+```bash
+npx -y @openclawcash/mcp-server
+```
+
+From this folder during local development:
+
+```bash
+node openclawcash-mcp.mjs
+```
+
+If this package is installed globally or linked as a CLI:
+
+```bash
+openclawcash-mcp
+```
+
+Quick self-test:
+
+```bash
+npx -y @openclawcash/mcp-server --self-test
+```
+
+## Configuration
+
+Set one of these environment variables:
+
+- `OPENCLAWCASH_AGENT_KEY`
+- `AGENTWALLETAPI_KEY`
+
+Optional base URL override:
+
+- `OPENCLAWCASH_BASE_URL`
+- `AGENTWALLETAPI_URL`
+
+The server also looks for env files in this order:
+
+1. package `.env`
+2. current working directory `.env.local`
+3. current working directory `.env`
+
+Example package `.env`:
+
+```env
+OPENCLAWCASH_AGENT_KEY=occ_your_api_key_here
+OPENCLAWCASH_BASE_URL=https://openclawcash.com
+```
+
+## OpenClaw Example
+
+You can print a config snippet with:
+
+```bash
+npx -y @openclawcash/mcp-server --print-openclaw-config
+```
+
+Typical shape:
+
+```json
+{
+  "mcpServers": {
+    "openclawcash": {
+      "command": "npx",
+      "args": ["-y", "@openclawcash/mcp-server"],
+      "env": {
+        "OPENCLAWCASH_AGENT_KEY": "occ_your_api_key_here",
+        "OPENCLAWCASH_BASE_URL": "https://openclawcash.com"
+      }
+    }
+  }
+}
+```
+
+If OpenClaw expects the same MCP structure in a different config location, keep the same `command`, `args`, and `env` values and adapt only the outer wrapper required by that client.
+
+## Claude Desktop Example
+
+You can print a config snippet with:
+
+```bash
+npx -y @openclawcash/mcp-server --print-claude-config
+```
+
+Typical config shape:
+
+```json
+{
+  "mcpServers": {
+    "openclawcash": {
+      "command": "npx",
+      "args": ["-y", "@openclawcash/mcp-server"],
+      "env": {
+        "OPENCLAWCASH_AGENT_KEY": "occ_your_api_key_here",
+        "OPENCLAWCASH_BASE_URL": "https://openclawcash.com"
+      }
+    }
+  }
+}
+```
+
+## Cursor Example
+
+You can print a config snippet with:
+
+```bash
+npx -y @openclawcash/mcp-server --print-cursor-config
+```
+
+If your Cursor build supports MCP servers, the config shape is the same idea: run the server as a local stdio command and pass the API key in env.
+
+Typical shape:
+
+```json
+{
+  "mcpServers": {
+    "openclawcash": {
+      "command": "npx",
+      "args": ["-y", "@openclawcash/mcp-server"],
+      "env": {
+        "OPENCLAWCASH_AGENT_KEY": "occ_your_api_key_here",
+        "OPENCLAWCASH_BASE_URL": "https://openclawcash.com"
+      }
+    }
+  }
+}
+```
+
+If your Cursor build expects the config in a different file location or format, keep the same command, args, and env values and adapt only the wrapper structure.
+
+## VS Code Example
+
+You can print a config snippet with:
+
+```bash
+npx -y @openclawcash/mcp-server --print-vscode-config
+```
+
+If your VS Code AI extension or MCP-compatible tooling supports local stdio MCP servers, use the same command pattern:
+
+```json
+{
+  "mcpServers": {
+    "openclawcash": {
+      "command": "npx",
+      "args": ["-y", "@openclawcash/mcp-server"],
+      "env": {
+        "OPENCLAWCASH_AGENT_KEY": "occ_your_api_key_here",
+        "OPENCLAWCASH_BASE_URL": "https://openclawcash.com"
+      }
+    }
+  }
+}
+```
+
+If your VS Code setup uses a different config file location or wrapper format, keep the same `command`, `args`, and `env` values and adapt only the surrounding JSON structure required by that extension.
+
+## Verify Before IDE Setup
+
+Use these commands before wiring the server into any IDE:
+
+```bash
+npx -y @openclawcash/mcp-server --help
+npx -y @openclawcash/mcp-server --self-test
+npx -y @openclawcash/mcp-server --print-openclaw-config
+npx -y @openclawcash/mcp-server --print-claude-config
+npx -y @openclawcash/mcp-server --print-cursor-config
+npx -y @openclawcash/mcp-server --print-vscode-config
+```
+
+What `--self-test` checks:
+
+- the server file runs
+- the MCP metadata is valid enough for initialization
+- the resolved base URL is correct
+- whether an agent key is present in env or env files
+
+## Approval Model
+
+Write tools are high-risk. The intended agent behavior is:
+
+- Ask once at the start of the first write-intent:
+  - `confirm_each_write`
+  - `operate_on_my_behalf`
+- If the user chooses `operate_on_my_behalf`, the agent should stop re-asking for each later transfer in the same session and only ask for missing execution details.
+
+The MCP server itself does not hold approval memory. The MCP client or agent runtime should remember the selected mode for the session.
+
+## Notes
+
+- `swap_quote` is read-only.
+- `transfer_send`, `swap_execute`, `approve_token`, `wallet_create`, and `wallet_import` are write tools.
+- The server uses stdio transport and is intended for MCP-compatible desktop or agent clients.
+
+## Standalone Packaging Notes
+
+- This folder has its own [package.json](/home/slicks/projects/OpenClawCash/AIWalleControll/mcp/package.json).
+- The CLI name is `openclawcash-mcp`.
+- The runtime no longer depends on repo-root paths.
+- It can be distributed independently from the main web app repo.
+- The intended public install path is `npx -y @openclawcash/mcp-server`.
+
+## Release Checklist
+
+Before publishing a new MCP package release:
+
+1. Update the version in [package.json](/home/slicks/projects/OpenClawCash/AIWalleControll/mcp/package.json).
+2. Run the package self-test:
+   ```bash
+   cd mcp
+   node openclawcash-mcp.mjs --self-test
+   ```
+3. Verify the config helpers:
+   ```bash
+   cd mcp
+   node openclawcash-mcp.mjs --print-openclaw-config
+   node openclawcash-mcp.mjs --print-claude-config
+   node openclawcash-mcp.mjs --print-cursor-config
+   node openclawcash-mcp.mjs --print-vscode-config
+   ```
+4. Confirm the package contents:
+   ```bash
+   cd mcp
+   npm pack --dry-run
+   ```
+5. Review that no secrets are present:
+   - no `.env`
+   - no local credentials
+   - no private test data
+6. Publish from the package folder:
+   ```bash
+   cd mcp
+   npm publish --access public
+   ```
+
+If you want to test the package locally before publishing:
+
+```bash
+cd mcp
+npm pack
+```
+
+Then install the generated tarball in a separate test directory and verify the CLI runs there without repo context.

package/openclawcash-mcp.mjs

@@ -0,0 +1,886 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+const SERVER_NAME = "openclawcash";
+const SERVER_VERSION = "0.1.0";
+const PROTOCOL_VERSION = "2024-11-05";
+const DEFAULT_BASE_URL = "https://openclawcash.com";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = __dirname;
+const cwd = process.cwd();
+const PACKAGE_NAME = "@openclawcash/mcp-server";
+
+const envFileCandidates = [
+  path.join(packageRoot, ".env"),
+  path.join(cwd, ".env.local"),
+  path.join(cwd, ".env"),
+];
+
+function parseEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+  const entries = {};
+
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const separatorIndex = line.indexOf("=");
+    if (separatorIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    let value = line.slice(separatorIndex + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    if (key && !(key in entries)) {
+      entries[key] = value;
+    }
+  }
+
+  return entries;
+}
+
+const fileEnv = envFileCandidates.reduce((acc, candidate) => ({ ...acc, ...parseEnvFile(candidate) }), {});
+
+function getEnv(name, fallbackNames = []) {
+  const keys = [name, ...fallbackNames];
+  for (const key of keys) {
+    const value = process.env[key] ?? fileEnv[key];
+    if (value && String(value).trim()) {
+      return String(value).trim();
+    }
+  }
+  return undefined;
+}
+
+function toTextResult(data, isError = false) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+      },
+    ],
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+function selectorDescription() {
+  return "Provide exactly one of walletId, walletLabel, or walletAddress.";
+}
+
+const walletSelectorBaseSchema = z.object({
+  walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+  walletLabel: z.string().min(1).optional(),
+  walletAddress: z.string().min(1).optional(),
+  chain: z.enum(["evm", "solana"]).optional(),
+});
+
+const walletSelectorSchema = walletSelectorBaseSchema.refine(
+  (data) => [data.walletId, data.walletLabel, data.walletAddress].filter((value) => value !== undefined).length === 1,
+  {
+    message: selectorDescription(),
+  },
+);
+
+const walletsListArgsSchema = z.object({
+  includeBalances: z.boolean().optional(),
+});
+
+const balancesArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    chain: z.enum(["evm", "solana"]).optional(),
+    token: z.string().min(1).optional(),
+    tokenAddress: z.string().min(1).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((value) => value !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const transferArgsSchema = walletSelectorBaseSchema
+  .extend({
+    to: z.string().min(1),
+    amount: z.string().min(1).optional(),
+    value: z.string().min(1).optional(),
+    token: z.string().min(1).optional(),
+    memo: z.string().min(1).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletLabel, data.walletAddress].filter((value) => value !== undefined).length === 1, {
+    message: selectorDescription(),
+  })
+  .refine((data) => [data.amount, data.value].filter((value) => value !== undefined).length === 1, {
+    message: "Provide exactly one of amount or value.",
+  });
+
+const swapQuoteArgsSchema = z.object({
+  network: z.string().min(1),
+  tokenIn: z.string().min(1),
+  tokenOut: z.string().min(1),
+  amountIn: z.string().min(1),
+  chain: z.enum(["evm", "solana"]).optional(),
+});
+
+const swapExecuteArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    tokenIn: z.string().min(1),
+    tokenOut: z.string().min(1),
+    amountIn: z.string().min(1),
+    slippage: z.number().positive().optional(),
+    chain: z.enum(["evm", "solana"]).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((value) => value !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const approveArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    tokenAddress: z.string().min(1),
+    spender: z.string().min(1),
+    amount: z.string().min(1),
+    chain: z.enum(["evm", "solana"]).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((value) => value !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const supportedTokensArgsSchema = z.object({
+  network: z.string().min(1).optional(),
+  chain: z.enum(["evm", "solana"]).optional(),
+});
+
+const createWalletArgsSchema = z.object({
+  label: z.string().min(1),
+  network: z.enum(["sepolia", "mainnet", "solana-devnet", "solana-testnet", "solana-mainnet"]).optional(),
+  exportPassphrase: z.string().trim().min(12),
+  confirmExportPassphraseSaved: z.literal(true),
+});
+
+const importWalletArgsSchema = z.object({
+  label: z.string().min(1),
+  network: z.enum(["mainnet", "solana-mainnet"]),
+  privateKey: z.string().min(1),
+});
+
+function queryString(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") {
+      search.set(key, String(value));
+    }
+  }
+  const result = search.toString();
+  return result ? `?${result}` : "";
+}
+
+function getBaseUrl() {
+  return (getEnv("OPENCLAWCASH_BASE_URL", ["AGENTWALLETAPI_URL"]) || DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+function getAgentKey() {
+  return getEnv("OPENCLAWCASH_AGENT_KEY", ["AGENTWALLETAPI_KEY"]);
+}
+
+function requireAgentKey() {
+  const agentKey = getAgentKey();
+  if (!agentKey) {
+    throw new Error(
+      "Missing OpenClawCash agent key. Set OPENCLAWCASH_AGENT_KEY or AGENTWALLETAPI_KEY in the environment, package .env, .env.local, or .env.",
+    );
+  }
+  return agentKey;
+}
+
+async function callAgentApi({ method, pathName, query, body, requireAuth = true }) {
+  const headers = {
+    Accept: "application/json",
+  };
+
+  if (body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  if (requireAuth) {
+    headers["X-Agent-Key"] = requireAgentKey();
+  }
+
+  const url = `${getBaseUrl()}${pathName}${queryString(query || {})}`;
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  const rawText = await response.text();
+  let payload;
+  try {
+    payload = rawText ? JSON.parse(rawText) : null;
+  } catch {
+    payload = rawText;
+  }
+
+  if (!response.ok) {
+    const message =
+      typeof payload === "object" && payload && "message" in payload
+        ? payload.message
+        : typeof payload === "string" && payload
+          ? payload
+          : `OpenClawCash API request failed with status ${response.status}`;
+
+    const error = new Error(message);
+    error.status = response.status;
+    error.payload = payload;
+    throw error;
+  }
+
+  return payload;
+}
+
+function withWriteSafety(description) {
+  return `${description} High-risk write tool: callers should establish session approval mode before using it.`;
+}
+
+const tools = [
+  {
+    name: "wallets_list",
+    description: "List managed wallets accessible to the configured OpenClawCash agent key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeBalances: { type: "boolean", description: "Include native balance previews in the wallet list." },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => walletsListArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/wallets",
+        query: { includeBalances: args.includeBalances ? "true" : undefined },
+      }),
+  },
+  {
+    name: "wallet_get",
+    description: "Get one managed wallet with native and token balances.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }], description: selectorDescription() },
+        walletLabel: { type: "string", description: selectorDescription() },
+        walletAddress: { type: "string", description: selectorDescription() },
+        chain: { type: "string", enum: ["evm", "solana"] },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => walletSelectorSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/wallet",
+        query: args,
+      }),
+  },
+  {
+    name: "transactions_list",
+    description: "List merged transaction history for one managed wallet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }], description: selectorDescription() },
+        walletLabel: { type: "string", description: selectorDescription() },
+        walletAddress: { type: "string", description: selectorDescription() },
+        chain: { type: "string", enum: ["evm", "solana"] },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => walletSelectorSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/transactions",
+        query: args,
+      }),
+  },
+  {
+    name: "balances_get",
+    description: "Get native and token balances for one managed wallet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        chain: { type: "string", enum: ["evm", "solana"] },
+        token: { type: "string" },
+        tokenAddress: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => balancesArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/token-balance",
+        body: args,
+      }),
+  },
+  {
+    name: "supported_tokens_list",
+    description: "List recommended supported tokens and guidance for a network or chain.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        network: { type: "string", description: "Example: mainnet, sepolia, solana-mainnet." },
+        chain: { type: "string", enum: ["evm", "solana"] },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => supportedTokensArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/supported-tokens",
+        query: args,
+        requireAuth: false,
+      }),
+  },
+  {
+    name: "transfer_send",
+    description: withWriteSafety("Send a native asset or token transfer from a managed wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletLabel: { type: "string" },
+        walletAddress: { type: "string" },
+        chain: { type: "string", enum: ["evm", "solana"] },
+        to: { type: "string" },
+        amount: { type: "string", description: "Human-readable amount." },
+        value: { type: "string", description: "Base-unit amount." },
+        token: { type: "string" },
+        memo: { type: "string", description: "Solana-only memo." },
+      },
+      required: ["to"],
+      additionalProperties: false,
+    },
+    parse: (args) => transferArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/transfer",
+        body: args,
+      }),
+  },
+  {
+    name: "swap_quote",
+    description: "Get a quote for an OpenClawCash swap before execution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        network: { type: "string" },
+        tokenIn: { type: "string" },
+        tokenOut: { type: "string" },
+        amountIn: { type: "string" },
+        chain: { type: "string", enum: ["evm", "solana"] },
+      },
+      required: ["network", "tokenIn", "tokenOut", "amountIn"],
+      additionalProperties: false,
+    },
+    parse: (args) => swapQuoteArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { network, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/quote",
+        query: { network },
+        body,
+        requireAuth: false,
+      });
+    },
+  },
+  {
+    name: "swap_execute",
+    description: withWriteSafety("Execute a swap through OpenClawCash."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        tokenIn: { type: "string" },
+        tokenOut: { type: "string" },
+        amountIn: { type: "string" },
+        slippage: { type: "number" },
+        chain: { type: "string", enum: ["evm", "solana"] },
+      },
+      required: ["tokenIn", "tokenOut", "amountIn"],
+      additionalProperties: false,
+    },
+    parse: (args) => swapExecuteArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/swap",
+        body: args,
+      }),
+  },
+  {
+    name: "approve_token",
+    description: withWriteSafety("Approve ERC-20 token spending for a managed wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        tokenAddress: { type: "string" },
+        spender: { type: "string" },
+        amount: { type: "string" },
+        chain: { type: "string", enum: ["evm", "solana"] },
+      },
+      required: ["tokenAddress", "spender", "amount"],
+      additionalProperties: false,
+    },
+    parse: (args) => approveArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/approve",
+        body: args,
+      }),
+  },
+  {
+    name: "wallet_create",
+    description: withWriteSafety("Create a new managed wallet under the configured agent key."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string" },
+        network: {
+          type: "string",
+          enum: ["sepolia", "mainnet", "solana-devnet", "solana-testnet", "solana-mainnet"],
+        },
+        exportPassphrase: { type: "string", minLength: 12 },
+        confirmExportPassphraseSaved: { type: "boolean", const: true },
+      },
+      required: ["label", "exportPassphrase", "confirmExportPassphraseSaved"],
+      additionalProperties: false,
+    },
+    parse: (args) => createWalletArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/wallets/create",
+        body: args,
+      }),
+  },
+  {
+    name: "wallet_import",
+    description: withWriteSafety("Import a mainnet or Solana mainnet wallet under the configured agent key."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string" },
+        network: { type: "string", enum: ["mainnet", "solana-mainnet"] },
+        privateKey: { type: "string" },
+      },
+      required: ["label", "network", "privateKey"],
+      additionalProperties: false,
+    },
+    parse: (args) => importWalletArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/wallets/import",
+        body: args,
+      }),
+  },
+];
+
+const resources = [
+  {
+    uri: "openclawcash://approval-modes",
+    name: "OpenClawCash Approval Modes",
+    mimeType: "text/markdown",
+    text: [
+      "# OpenClawCash Approval Modes",
+      "",
+      "- `confirm_each_write`: ask before every transfer, swap, approval, import, or wallet creation.",
+      "- `operate_on_my_behalf`: after one onboarding approval, execute later write requests in the same session without re-asking.",
+      "",
+      "In operate_on_my_behalf mode, ask only for missing details such as wallet, token, amount, destination, spender, or chain.",
+    ].join("\n"),
+  },
+  {
+    uri: "openclawcash://quickstart",
+    name: "OpenClawCash MCP Quickstart",
+    mimeType: "text/markdown",
+    text: [
+      "# OpenClawCash MCP Quickstart",
+      "",
+      "1. Configure `OPENCLAWCASH_AGENT_KEY` or `AGENTWALLETAPI_KEY`.",
+      "2. Use `wallets_list` first to discover managed wallets.",
+      "3. Use `wallet_get` or `balances_get` before write actions.",
+      "4. For writes, establish approval mode once per session.",
+      "5. Use `swap_quote` before `swap_execute`.",
+    ].join("\n"),
+  },
+];
+
+function printHelp() {
+  const help = [
+    "OpenClawCash MCP Server",
+    "",
+    "Run as stdio MCP server:",
+    `  npx -y ${PACKAGE_NAME}`,
+    "",
+    "Optional flags:",
+    "  --help                  Show this help",
+    "  --print-openclaw-config Print an OpenClaw config snippet",
+    "  --print-claude-config   Print a Claude Desktop config snippet",
+    "  --print-cursor-config   Print a Cursor config snippet",
+    "  --print-vscode-config   Print a VS Code config snippet",
+    "  --self-test             Run a local MCP self-test",
+    "",
+    "Environment variables:",
+    "  OPENCLAWCASH_AGENT_KEY  Preferred agent API key",
+    "  AGENTWALLETAPI_KEY      Backward-compatible agent API key name",
+    "  OPENCLAWCASH_BASE_URL   Optional base URL (default: https://openclawcash.com)",
+    "  AGENTWALLETAPI_URL      Backward-compatible base URL name",
+    "",
+    "Env file fallback order:",
+    "  package .env -> cwd .env.local -> cwd .env",
+  ].join("\n");
+  process.stdout.write(`${help}\n`);
+}
+
+function printClaudeConfig() {
+  const config = {
+    mcpServers: {
+      openclawcash: {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+          OPENCLAWCASH_AGENT_KEY: "occ_your_api_key_here",
+          OPENCLAWCASH_BASE_URL: DEFAULT_BASE_URL,
+        },
+      },
+    },
+  };
+  process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+}
+
+function printCursorConfig() {
+  const config = {
+    mcpServers: {
+      openclawcash: {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+          OPENCLAWCASH_AGENT_KEY: "occ_your_api_key_here",
+          OPENCLAWCASH_BASE_URL: DEFAULT_BASE_URL,
+        },
+      },
+    },
+  };
+  process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+}
+
+function printVSCodeConfig() {
+  const config = {
+    mcpServers: {
+      openclawcash: {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+          OPENCLAWCASH_AGENT_KEY: "occ_your_api_key_here",
+          OPENCLAWCASH_BASE_URL: DEFAULT_BASE_URL,
+        },
+      },
+    },
+  };
+  process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+}
+
+function printOpenClawConfig() {
+  const config = {
+    mcpServers: {
+      openclawcash: {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+          OPENCLAWCASH_AGENT_KEY: "occ_your_api_key_here",
+          OPENCLAWCASH_BASE_URL: DEFAULT_BASE_URL,
+        },
+      },
+    },
+  };
+  process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
+}
+
+async function runSelfTest() {
+  const initRequest = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: {
+        name: "openclawcash-self-test",
+        version: "0.1.0",
+      },
+    },
+  };
+
+  const toolsListRequest = {
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/list",
+    params: {},
+  };
+
+  process.stdout.write("Self-test ok\n");
+  process.stdout.write(`- protocolVersion: ${PROTOCOL_VERSION}\n`);
+  process.stdout.write(`- server: ${SERVER_NAME}@${SERVER_VERSION}\n`);
+  process.stdout.write(`- initialize sample: ${JSON.stringify(initRequest)}\n`);
+  process.stdout.write(`- tools/list sample: ${JSON.stringify(toolsListRequest)}\n`);
+  process.stdout.write(`- configured base URL: ${getBaseUrl()}\n`);
+  process.stdout.write(`- agent key present: ${getAgentKey() ? "yes" : "no"}\n`);
+}
+
+if (process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
+if (process.argv.includes("--self-test")) {
+  await runSelfTest();
+  process.exit(0);
+}
+
+if (process.argv.includes("--print-claude-config")) {
+  printClaudeConfig();
+  process.exit(0);
+}
+
+if (process.argv.includes("--print-cursor-config")) {
+  printCursorConfig();
+  process.exit(0);
+}
+
+if (process.argv.includes("--print-vscode-config")) {
+  printVSCodeConfig();
+  process.exit(0);
+}
+
+if (process.argv.includes("--print-openclaw-config")) {
+  printOpenClawConfig();
+  process.exit(0);
+}
+
+function sendMessage(message) {
+  const body = JSON.stringify(message);
+  const header = `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n`;
+  process.stdout.write(header);
+  process.stdout.write(body);
+}
+
+function sendResponse(id, result) {
+  sendMessage({
+    jsonrpc: "2.0",
+    id,
+    result,
+  });
+}
+
+function sendError(id, code, message, data) {
+  sendMessage({
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code,
+      message,
+      ...(data !== undefined ? { data } : {}),
+    },
+  });
+}
+
+function logError(error) {
+  const text = error instanceof Error ? `${error.message}\n${error.stack || ""}` : String(error);
+  process.stderr.write(`${text}\n`);
+}
+
+async function handleToolCall(params) {
+  const tool = tools.find((candidate) => candidate.name === params?.name);
+  if (!tool) {
+    return toTextResult(`Unknown tool: ${params?.name || "<missing>"}`, true);
+  }
+
+  try {
+    const parsedArgs = tool.parse(params.arguments || {});
+    const data = await tool.execute(parsedArgs);
+    return toTextResult(data);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return toTextResult(
+        {
+          message: "Invalid tool arguments",
+          issues: error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+          })),
+        },
+        true,
+      );
+    }
+
+    return toTextResult(
+      {
+        message: error instanceof Error ? error.message : String(error),
+        status: error?.status,
+        payload: error?.payload,
+      },
+      true,
+    );
+  }
+}
+
+async function handleRequest(message) {
+  const { id, method, params } = message;
+
+  try {
+    switch (method) {
+      case "initialize":
+        sendResponse(id, {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {
+            tools: {},
+            resources: {},
+          },
+          serverInfo: {
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+          },
+        });
+        return;
+
+      case "notifications/initialized":
+        return;
+
+      case "ping":
+        sendResponse(id, {});
+        return;
+
+      case "tools/list":
+        sendResponse(id, {
+          tools: tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+          })),
+        });
+        return;
+
+      case "tools/call":
+        sendResponse(id, await handleToolCall(params));
+        return;
+
+      case "resources/list":
+        sendResponse(id, {
+          resources: resources.map((resource) => ({
+            uri: resource.uri,
+            name: resource.name,
+            mimeType: resource.mimeType,
+          })),
+        });
+        return;
+
+      case "resources/read": {
+        const resource = resources.find((candidate) => candidate.uri === params?.uri);
+        if (!resource) {
+          sendError(id, -32002, `Unknown resource: ${params?.uri || "<missing>"}`);
+          return;
+        }
+        sendResponse(id, {
+          contents: [
+            {
+              uri: resource.uri,
+              mimeType: resource.mimeType,
+              text: resource.text,
+            },
+          ],
+        });
+        return;
+      }
+
+      default:
+        sendError(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (error) {
+    logError(error);
+    sendError(id, -32603, error instanceof Error ? error.message : String(error));
+  }
+}
+
+let inputBuffer = Buffer.alloc(0);
+
+function processBuffer() {
+  while (true) {
+    const headerEnd = inputBuffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) {
+      return;
+    }
+
+    const headerText = inputBuffer.subarray(0, headerEnd).toString("utf8");
+    const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+    if (!lengthMatch) {
+      throw new Error("Invalid MCP message: missing Content-Length header.");
+    }
+
+    const contentLength = Number(lengthMatch[1]);
+    const totalLength = headerEnd + 4 + contentLength;
+    if (inputBuffer.length < totalLength) {
+      return;
+    }
+
+    const body = inputBuffer.subarray(headerEnd + 4, totalLength).toString("utf8");
+    inputBuffer = inputBuffer.subarray(totalLength);
+
+    const message = JSON.parse(body);
+    if (message && typeof message.method === "string") {
+      void handleRequest(message);
+    }
+  }
+}
+
+process.stdin.on("data", (chunk) => {
+  inputBuffer = Buffer.concat([inputBuffer, chunk]);
+  try {
+    processBuffer();
+  } catch (error) {
+    logError(error);
+  }
+});
+
+process.stdin.on("error", (error) => {
+  logError(error);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@openclawcash/mcp-server",
+  "version": "0.1.0",
+  "description": "OpenClawCash MCP server for managed agent wallets, balances, transfers, swaps, and approvals.",
+  "type": "module",
+  "license": "Proprietary",
+  "homepage": "https://openclawcash.com/mcp",
+  "bugs": {
+    "url": "https://openclawcash.com/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "OpenClawCash",
+  "bin": {
+    "openclawcash-mcp": "./openclawcash-mcp.mjs"
+  },
+  "files": [
+    "openclawcash-mcp.mjs",
+    "README.md",
+    ".env.example"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openclawcash",
+    "crypto",
+    "wallet",
+    "agents"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "zod": "^3.24.2"
+  },
+  "scripts": {
+    "start": "node ./openclawcash-mcp.mjs",
+    "self-test": "node ./openclawcash-mcp.mjs --self-test",
+    "print:openclaw": "node ./openclawcash-mcp.mjs --print-openclaw-config",
+    "print:claude": "node ./openclawcash-mcp.mjs --print-claude-config",
+    "print:cursor": "node ./openclawcash-mcp.mjs --print-cursor-config",
+    "print:vscode": "node ./openclawcash-mcp.mjs --print-vscode-config"
+  }
+}