crossmint-wallets-mcp 0.1.0

package/dist/mcp/tools.js

@@ -0,0 +1,198 @@
+import { z } from "zod";
+import { createWallet } from "../core/create-wallet.js";
+import { getBalance } from "../core/get-balance.js";
+import { transferToken } from "../core/transfer-token.js";
+import { payX402Endpoint } from "../core/pay-x402-endpoint.js";
+import { classifyError, toolErrorResponse } from "./errors.js";
+/**
+ * Register the 4 Crossmint wallet tools against an MCP server instance.
+ *
+ * Tool naming convention: `crossmint_<verb>` — the `crossmint_` prefix
+ * disambiguates from other MCP servers a client may have connected.
+ *
+ * All handlers catch thrown errors and translate them into the
+ * standardized MCP error response shape from `./errors.ts`, so clients
+ * never see raw stack traces in the content block.
+ */
+const chainSchema = z
+    .enum(["solana", "base", "base-sepolia"])
+    .describe("The chain to operate on. Use 'solana' for Solana mainnet (or devnet if " +
+    "the Crossmint API key is a staging key — the SDK resolves the cluster " +
+    "from the API environment). Use 'base' for Base mainnet, 'base-sepolia' " +
+    "for Base testnet.");
+function textResult(obj) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(obj, null, 2) },
+        ],
+    };
+}
+function errorResult(err) {
+    const code = classifyError(err);
+    const message = err instanceof Error ? err.message : String(err);
+    return toolErrorResponse(code, message);
+}
+export function registerTools(server) {
+    // -------------------------------------------------------------------
+    // Tool 1: crossmint_create_wallet
+    // -------------------------------------------------------------------
+    server.registerTool("crossmint_create_wallet", {
+        title: "Create a Crossmint smart wallet",
+        description: "Creates a new Crossmint smart wallet on the given chain, using " +
+            "the server-side recovery signer configured via CROSSMINT_RECOVERY_SECRET. " +
+            "Note: calling this tool without an `alias` generates a NEW wallet " +
+            "on every call (non-deterministic). Pass an `alias` string to make " +
+            "wallet creation idempotent — the same alias always resolves to the " +
+            "same address. `owner` accepts Crossmint user locators like " +
+            "'email:user@example.com', 'userId:abc', 'x:handle', or the literal " +
+            "'COMPANY' for company-owned wallets. Free-form strings are rejected " +
+            "by the Crossmint API.",
+        inputSchema: {
+            chain: chainSchema,
+            owner: z
+                .string()
+                .optional()
+                .describe("Optional user locator (email:x@y.com, userId:abc, x:handle, " +
+                "phoneNumber:+123, twitter:handle) or 'COMPANY'."),
+            alias: z
+                .string()
+                .optional()
+                .describe("Optional alias string. Makes wallet creation deterministic — " +
+                "the same (recovery secret, chain, alias) tuple always resolves " +
+                "to the same wallet address."),
+        },
+    }, async ({ chain, owner, alias }) => {
+        try {
+            const result = await createWallet({ chain, owner, alias });
+            return textResult(result);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -------------------------------------------------------------------
+    // Tool 2: crossmint_get_balance
+    // -------------------------------------------------------------------
+    server.registerTool("crossmint_get_balance", {
+        title: "Get on-chain balances for a Crossmint wallet",
+        description: "Returns the native token balance (SOL/ETH) and USDC balance for a " +
+            "Crossmint wallet, plus any additional token balances requested. " +
+            "Read-only: no signer required.",
+        inputSchema: {
+            address: z
+                .string()
+                .describe("The Crossmint wallet address to query."),
+            chain: chainSchema,
+            tokens: z
+                .array(z.string())
+                .optional()
+                .describe("Optional array of additional token symbols or mint/contract " +
+                "addresses to include in the response. Native token and USDC " +
+                "are always included regardless of this field."),
+        },
+    }, async ({ address, chain, tokens }) => {
+        try {
+            const result = await getBalance({ address, chain, tokens });
+            return textResult(result);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -------------------------------------------------------------------
+    // Tool 3: crossmint_transfer_token
+    // -------------------------------------------------------------------
+    server.registerTool("crossmint_transfer_token", {
+        title: "Transfer tokens from a Crossmint wallet",
+        description: "Transfers tokens from a Crossmint smart wallet to any recipient " +
+            "address or user locator. Uses the server recovery signer and the " +
+            "Crossmint gasless relayer — no native gas token is required in " +
+            "the wallet. `amount` is in decimal human units (e.g. '0.01'), " +
+            "not atomic units.",
+        inputSchema: {
+            payerAddress: z
+                .string()
+                .describe("Address of the Crossmint wallet to transfer from."),
+            chain: chainSchema,
+            to: z
+                .string()
+                .describe("Recipient address or user locator (e.g. a Solana pubkey, an " +
+                "EVM 0x... address, or 'email:x@y.com')."),
+            token: z
+                .string()
+                .describe("Token symbol ('usdc', 'sol', 'eth') or raw mint/contract address."),
+            amount: z
+                .string()
+                .describe("Amount in decimal human units (e.g. '0.01' for 0.01 USDC)."),
+        },
+    }, async ({ payerAddress, chain, to, token, amount }) => {
+        try {
+            const result = await transferToken({
+                payerAddress,
+                chain,
+                to,
+                token,
+                amount,
+            });
+            return textResult(result);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    // -------------------------------------------------------------------
+    // Tool 4: crossmint_pay_x402_endpoint
+    // -------------------------------------------------------------------
+    server.registerTool("crossmint_pay_x402_endpoint", {
+        title: "Pay an x402-protected HTTP endpoint",
+        description: "Fetches an HTTP URL, handles the x402 Payment Required (HTTP 402) " +
+            "challenge by transferring the requested amount of USDC from a " +
+            "Crossmint smart wallet, and returns the paid response body plus " +
+            "the on-chain transaction signature. Supports Solana mainnet in " +
+            "v0.1; EVM support is planned.",
+        inputSchema: {
+            payerAddress: z
+                .string()
+                .describe("Address of the Crossmint wallet that should fund the payment."),
+            chain: chainSchema,
+            url: z.string().url().describe("The x402-protected URL to fetch."),
+            method: z
+                .enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"])
+                .optional()
+                .describe("HTTP method. Defaults to GET."),
+            headers: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("Additional HTTP headers to send with the request."),
+            jsonBody: z
+                .any()
+                .optional()
+                .describe("JSON body to send with POST/PUT/PATCH requests. Ignored for GET."),
+            maxUsdcAtomic: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Safety guardrail: reject the payment if the 402 response asks " +
+                "for more than this many atomic USDC units (1 USDC = 1,000,000 " +
+                "atomic units). Recommended for agents to avoid runaway spend."),
+        },
+    }, async ({ payerAddress, chain, url, method, headers, jsonBody, maxUsdcAtomic }) => {
+        try {
+            const result = await payX402Endpoint({
+                url,
+                payerAddress,
+                chain,
+                method,
+                headers,
+                jsonBody,
+                maxUsdcAtomic: maxUsdcAtomic !== undefined ? BigInt(maxUsdcAtomic) : undefined,
+            });
+            return textResult(result);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "crossmint-wallets-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing Crossmint smart wallet primitives as tools for Claude Desktop, Continue.dev, Cline, Codex CLI, and any MCP-native client.",
+  "type": "module",
+  "bin": {
+    "crossmint-wallets-mcp": "dist/mcp/server.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "crossmint",
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "solana",
+    "smart-wallet",
+    "agents",
+    "claude-desktop",
+    "cursor",
+    "continue",
+    "cline",
+    "lobster-cash",
+    "stablecoin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@crossmint/wallets-sdk": "^1.0.7",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@solana/spl-token": "^0.4.9",
+    "@solana/web3.js": "^1.95.0",
+    "@x402/core": "^2.9.0",
+    "@x402/svm": "^2.9.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.10.0",
+    "@x402/express": "^2.9.0",
+    "dotenv": "^16.4.5",
+    "express": "^5.2.1",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/mcp/server.js",
+    "dev": "tsc --watch",
+    "demo": "tsx demo/smoke-test.ts",
+    "test:smoke": "tsx demo/smoke-test.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}