@x402storage/mcp 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# x402store-mcp
+
+MCP server for storing files permanently on IPFS via [x402.storage](https://x402.storage).
+
+## Installation
+
+```bash
+npm install -g x402store-mcp
+```
+
+Or clone and build locally:
+
+```bash
+git clone https://github.com/anthropics/x402store-mcp
+cd x402store-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+### 1. Set up your wallet
+
+Export your Base wallet private key:
+
+```bash
+export X402_PRIVATE_KEY=0x...
+```
+
+Need a wallet? Create one at [x402.storage](https://x402.storage).
+
+### 2. Configure Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "x402store": {
+      "command": "node",
+      "args": ["/path/to/x402store-mcp/dist/index.js"],
+      "env": {
+        "X402_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "x402store": {
+      "command": "x402store-mcp",
+      "env": {
+        "X402_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+Fully quit and restart Claude Desktop for the configuration to take effect.
+
+## Usage
+
+Once configured, you can ask Claude to store files:
+
+> "Store the file /path/to/document.pdf permanently"
+
+Claude will use the `store_file` tool to upload the file and return the permanent IPFS URL.
+
+## Tool
+
+### store_file
+
+Store a file permanently on IPFS.
+
+**Input:**
+- `file_path` (string): Absolute or relative path to the file
+
+**Output:**
+- Permanent IPFS gateway URL (e.g., `https://x402.storage/bafybeig...`)
+
+**Errors:**
+- File not found
+- Insufficient balance (fund wallet at x402.storage)
+- Network error
+
+## Cost
+
+Each upload costs $0.01 USDC on Base. Files are stored permanently.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Environment validation for x402store MCP server
+ */
+/**
+ * Validates required environment variables.
+ * Returns error message if X402_PRIVATE_KEY is missing, null if valid.
+ */
+export declare function validateEnvironment(): string | null;
+/**
+ * Gets the private key from environment.
+ * Should only be called after validateEnvironment() returns null.
+ */
+export declare function getPrivateKey(): `0x${string}`;

package/dist/config.js

@@ -0,0 +1,20 @@
+/**
+ * Environment validation for x402store MCP server
+ */
+/**
+ * Validates required environment variables.
+ * Returns error message if X402_PRIVATE_KEY is missing, null if valid.
+ */
+export function validateEnvironment() {
+    if (!process.env.X402_PRIVATE_KEY) {
+        return 'X402_PRIVATE_KEY not set. Export your Base wallet private key: export X402_PRIVATE_KEY=0x... Need a wallet? Create one at https://x402.storage';
+    }
+    return null;
+}
+/**
+ * Gets the private key from environment.
+ * Should only be called after validateEnvironment() returns null.
+ */
+export function getPrivateKey() {
+    return process.env.X402_PRIVATE_KEY;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { resolve } from 'node:path';
+import { validateEnvironment, getPrivateKey } from './config.js';
+import { uploadFile, FileNotFoundError, UploadError } from './upload.js';
+// Create MCP server
+const server = new McpServer({
+    name: 'x402store',
+    version: '1.0.0',
+});
+// Register store_file tool
+server.tool('store_file', 'Store a file permanently on IPFS via x402.storage. Returns the permanent gateway URL.', {
+    file_path: z
+        .string()
+        .describe('Absolute or relative path to the file to upload'),
+}, async ({ file_path }) => {
+    // Validate environment first
+    const envError = validateEnvironment();
+    if (envError) {
+        return {
+            content: [{ type: 'text', text: `Error: ${envError}` }],
+        };
+    }
+    try {
+        const resolvedPath = resolve(file_path);
+        const privateKey = getPrivateKey();
+        const result = await uploadFile(resolvedPath, privateKey);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: result.gateway,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof FileNotFoundError) {
+            return {
+                content: [{ type: 'text', text: `Error: File not found: ${file_path}` }],
+            };
+        }
+        if (error instanceof UploadError) {
+            if (error.type === 'insufficient_balance') {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Error: Insufficient balance. Fund your wallet at https://x402.storage or transfer USDC on Base.',
+                        },
+                    ],
+                };
+            }
+            if (error.type === 'network_error') {
+                return {
+                    content: [
+                        { type: 'text', text: 'Error: Network error. Check your connection and try again.' },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: 'text', text: `Error: Upload failed: ${error.message}` }],
+            };
+        }
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+        };
+    }
+});
+// Run server with stdio transport
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Note: MCP servers must not write to stdout (breaks JSON-RPC)
+    // Use console.error for any debugging
+    console.error('x402store MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/upload.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Upload logic with x402 payment integration
+ */
+/**
+ * Error thrown when file doesn't exist
+ */
+export declare class FileNotFoundError extends Error {
+    constructor(filePath: string);
+}
+/**
+ * Types of upload errors
+ */
+export type UploadErrorType = 'network_error' | 'payment_failed' | 'upload_failed' | 'insufficient_balance';
+/**
+ * Error thrown during upload
+ */
+export declare class UploadError extends Error {
+    readonly type: UploadErrorType;
+    constructor(message: string, type: UploadErrorType);
+}
+/**
+ * Response from the upload API
+ */
+interface UploadResponse {
+    cid: string;
+    gateway: string;
+}
+/**
+ * Uploads a file to api.x402.storage with automatic payment handling
+ *
+ * @param filePath - Path to the file to upload
+ * @param privateKey - Private key for x402 payment signing
+ * @returns Object containing CID and gateway URL
+ * @throws FileNotFoundError if file doesn't exist
+ * @throws UploadError on network, payment, or upload failures
+ */
+export declare function uploadFile(filePath: string, privateKey: string): Promise<UploadResponse>;
+export {};

package/dist/upload.js

@@ -0,0 +1,115 @@
+/**
+ * Upload logic with x402 payment integration
+ */
+import { x402Client } from '@x402/core/client';
+import { x402HTTPClient } from '@x402/core/http';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { wrapFetchWithPayment } from '@x402/fetch';
+import { privateKeyToAccount } from 'viem/accounts';
+import { openAsBlob } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+/**
+ * Error thrown when file doesn't exist
+ */
+export class FileNotFoundError extends Error {
+    constructor(filePath) {
+        super(`File not found: ${filePath}`);
+        this.name = 'FileNotFoundError';
+    }
+}
+/**
+ * Error thrown during upload
+ */
+export class UploadError extends Error {
+    type;
+    constructor(message, type) {
+        super(message);
+        this.name = 'UploadError';
+        this.type = type;
+    }
+}
+/**
+ * Creates an x402 payment client with the given private key
+ */
+function createPaymentClient(privateKey) {
+    const signer = privateKeyToAccount(privateKey);
+    const coreClient = new x402Client().register('eip155:*', new ExactEvmScheme(signer));
+    return new x402HTTPClient(coreClient);
+}
+/**
+ * Uploads a file to api.x402.storage with automatic payment handling
+ *
+ * @param filePath - Path to the file to upload
+ * @param privateKey - Private key for x402 payment signing
+ * @returns Object containing CID and gateway URL
+ * @throws FileNotFoundError if file doesn't exist
+ * @throws UploadError on network, payment, or upload failures
+ */
+export async function uploadFile(filePath, privateKey) {
+    // Check file exists
+    try {
+        await stat(filePath);
+    }
+    catch {
+        throw new FileNotFoundError(filePath);
+    }
+    // Create payment client and wrap fetch
+    const client = createPaymentClient(privateKey);
+    const fetchWithPayment = wrapFetchWithPayment(fetch, client);
+    // Read file as blob
+    const blob = await openAsBlob(filePath);
+    const fileName = basename(filePath);
+    // Create FormData with file
+    const formData = new FormData();
+    formData.append('file', blob, fileName);
+    // Upload to api.x402.storage (root endpoint, not /store)
+    let response;
+    try {
+        response = await fetchWithPayment('https://api.x402.storage', {
+            method: 'POST',
+            body: formData,
+            // Do NOT set Content-Type header - let Node.js set boundary
+        });
+    }
+    catch (error) {
+        // Network or payment errors during fetch
+        const message = error instanceof Error ? error.message : 'Unknown network error';
+        // Check for payment-related errors
+        if (message.toLowerCase().includes('insufficient')) {
+            throw new UploadError(message, 'insufficient_balance');
+        }
+        if (message.toLowerCase().includes('payment') ||
+            message.toLowerCase().includes('402')) {
+            throw new UploadError(message, 'payment_failed');
+        }
+        throw new UploadError(message, 'network_error');
+    }
+    // Handle non-OK responses
+    if (!response.ok) {
+        let errorMessage = `Upload failed: ${response.status} ${response.statusText}`;
+        try {
+            const errorBody = (await response.json());
+            if (errorBody.error) {
+                errorMessage = errorBody.error;
+            }
+        }
+        catch {
+            // Ignore JSON parse errors, use status message
+        }
+        // Determine error type from status code
+        if (response.status === 402) {
+            throw new UploadError(errorMessage, 'payment_failed');
+        }
+        if (response.status >= 500) {
+            throw new UploadError(errorMessage, 'network_error');
+        }
+        throw new UploadError(errorMessage, 'upload_failed');
+    }
+    // Parse successful response
+    const result = (await response.json());
+    return {
+        cid: result.cid,
+        gateway: result.gateway,
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@x402storage/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for x402.storage file uploads",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rawgroundbeef/x402.storage"
+  },
+  "bin": {
+    "x402-mcp": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["x402", "ipfs", "storage", "mcp", "claude"],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "@x402/core": "^2.2.0",
+    "@x402/evm": "latest",
+    "@x402/fetch": "latest",
+    "viem": "^2.21.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.7.0"
+  }
+}