@nullpay/mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,49 +1,60 @@
-# @nullpay/mcp
+# NullPay MCP
 
-NullPay MCP (Model Context Protocol) server for conversational invoice and payment flows.
+NullPay MCP installs a local MCP server for Claude and lets users connect with only their wallet credentials.
 
-This server allows AI agents to interact with the NullPay protocol, enabling them to create invoices, track payments, and manage merchant flows directly through chat.
+## Install
 
-## Features
+```bash
+npx -y @nullpay/mcp
+```
 
-- **Tool-based Interaction**: Exposes tools for creating NullPay invoices.
-- **Privacy First**: Built on top of the Aleo blockchain with Zero-Knowledge Proofs.
-- **Stdio Transport**: Compatible with MCP clients like Claude Desktop.
+The setup wizard asks whether to install into Claude Code or Claude Desktop, then writes the required MCP config automatically on the user's machine.
 
-## Installation
+## User-provided env
 
-```bash
-npm install @nullpay/mcp
-```
+Users only need to provide:
 
-## Usage
-
-### As an MCP Server
-
-Add the following to your MCP client configuration (e.g., `claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "nullpay": {
-      "command": "npx",
-      "args": ["-y", "@nullpay/mcp"],
-      "env": {
-        "NULLPAY_BACKEND_URL": "https://your-api.com/api",
-        "NULLPAY_MCP_SHARED_SECRET": "your-secret"
-      }
-    }
-  }
-}
-```
+- `NULLPAY_MAIN_ADDRESS`
+- `NULLPAY_MAIN_PRIVATE_KEY`
+- `NULLPAY_MAIN_PASSWORD`
+
+## Tools
+
+- `login`
+- `create_invoice`
+- `pay_invoice`
+- `get_transaction_info`
+
+## Environment
+
+Bundled by NullPay inside the package:
+
+- production backend URL
+- public NullPay base URL
+- Provable API key
+- Provable consumer ID
+
+Optional main-wallet credentials for record-backed transaction lookup and automated main-wallet payments:
+
+- `NULLPAY_MAIN_ADDRESS`
+- `NULLPAY_MAIN_PASSWORD`
+- `NULLPAY_MAIN_PRIVATE_KEY`
+
+`NULLPAY_MAIN_PVT_KEY` is also accepted as a legacy alias for the private key.
+
+When Claude launches the MCP server, it also loads env values from these files if present:
 
-## Configuration
+- `packages/nullpay-mcp/.env`
+- repo-root `.env`
+- `backend/.env`
 
-The server requires the following environment variables:
+For relayed invoice creation and sponsored execution, the backend still needs:
 
-- `NULLPAY_BACKEND_URL`: The base URL of your NullPay backend instance.
-- `NULLPAY_MCP_SHARED_SECRET`: A shared secret to authenticate with the backend.
+- `RELAYER_PRIVATE_KEY`
 
-## License
+## Notes
 
-MIT
+- Burner wallet private keys remain encrypted at rest in the existing `users` table.
+- The MCP server decrypts burner keys only in memory during payment execution.
+- If `NULLPAY_MAIN_PRIVATE_KEY` is available, the MCP server can fetch invoice amounts from main-wallet records and pay invoices from the main wallet without exposing that key to the model.
+- If the main private key is not available, the MCP server still allows login and invoice creation, and it prompts the user to add the env var for record-backed amount lookup and automated main-wallet payments.

package/dist/aleo.js

@@ -19,6 +19,7 @@ exports.enrichInvoiceWithRecordAmount = enrichInvoiceWithRecordAmount;
 exports.createSponsoredPaymentAuthorization = createSponsoredPaymentAuthorization;
 const crypto_1 = __importDefault(require("crypto"));
 const esm_1 = require("./esm");
+const env_1 = require("./env");
 exports.PROGRAM_ID = 'zk_pay_proofs_privacy_v22.aleo';
 const FREEZELIST_PROGRAM_ID = 'test_usdcx_freezelist.aleo';
 const EXPLORER_BASE = 'https://api.explorer.provable.com/v1';
@@ -206,12 +207,8 @@ function resolvePaymentMode(invoice, fallbackAmount, fallbackCurrency) {
         amountSuffix: 'u64',
     };
 }
-function getProvableConsumerId() {
-    return process.env.PROVABLE_CONSUMER_ID || process.env.PROVABLE_CONSUMER_KEY;
-}
 async function getScannerSession(privateKey) {
-    const provableApiKey = process.env.PROVABLE_API_KEY;
-    const consumerId = getProvableConsumerId();
+    const { apiKey: provableApiKey, consumerId } = (0, env_1.getProvableConfig)();
     if (!provableApiKey || !consumerId) {
         throw new Error('PROVABLE_API_KEY and PROVABLE_CONSUMER_ID/PROVABLE_CONSUMER_KEY are required for record fetching and payment automation.');
     }

package/dist/backend-client.d.ts

@@ -1,8 +1,7 @@
 import { InvoiceRecord, UserProfile } from './types';
 export declare class NullPayBackendClient {
     private readonly baseUrl;
-    private readonly mcpSecret?;
-    constructor(baseUrl: string, mcpSecret?: string | undefined);
+    constructor(baseUrl: string);
     private buildUrl;
     private request;
     getUserProfile(addressHash: string): Promise<UserProfile | null>;

package/dist/backend-client.js

@@ -2,20 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NullPayBackendClient = void 0;
 function mapBackendError(path, text) {
-    if (path === '/mcp/relay/create-invoice') {
-        if (text.includes('NULLPAY_MCP_SHARED_SECRET is not configured')) {
-            return 'Invoice creation is blocked because NULLPAY_MCP_SHARED_SECRET is missing on the backend. Set the same NULLPAY_MCP_SHARED_SECRET value in both the backend env and the MCP server env, then restart both processes.';
-        }
-        if (text.includes('Invalid MCP shared secret')) {
-            return 'Invoice creation is blocked because the MCP shared secret does not match. Set the same NULLPAY_MCP_SHARED_SECRET value in both the backend env and the MCP server env, then restart both processes.';
-        }
-    }
     return text;
 }
 class NullPayBackendClient {
-    constructor(baseUrl, mcpSecret) {
+    constructor(baseUrl) {
         this.baseUrl = baseUrl;
-        this.mcpSecret = mcpSecret;
     }
     buildUrl(path) {
         return `${this.baseUrl.replace(/\/+$/, '')}${path}`;
@@ -75,10 +66,7 @@ class NullPayBackendClient {
     async relayCreateInvoice(body) {
         return await this.request('/mcp/relay/create-invoice', {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...(this.mcpSecret ? { 'x-nullpay-mcp-secret': this.mcpSecret } : {})
-            },
+            headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
         });
     }

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+const setup_1 = require("./setup");
+function printHelp() {
+    console.log('NullPay MCP');
+    console.log('');
+    console.log('Usage:');
+    console.log('  nullpay-mcp           Start the setup wizard');
+    console.log('  nullpay-mcp setup     Start the setup wizard');
+    console.log('  nullpay-mcp server    Run the stdio MCP server');
+}
+async function main() {
+    const mode = (process.argv[2] || 'setup').toLowerCase();
+    if (mode === 'server') {
+        (0, server_1.startServer)();
+        return;
+    }
+    if (mode === 'setup') {
+        await (0, setup_1.runSetupWizard)();
+        return;
+    }
+    if (mode === '--help' || mode === '-h' || mode === 'help') {
+        printHelp();
+        return;
+    }
+    console.error(`Unknown command: ${mode}`);
+    printHelp();
+    process.exitCode = 1;
+}
+void main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/env.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_BACKEND_URL = "http://localhost:3000/api";
+export declare const DEFAULT_PUBLIC_BASE_URL = "https://nullpay.app";
+export declare function parseDotEnv(content: string): Record<string, string>;
+export declare function loadEnvFiles(): void;
+export declare function getRuntimeConfig(): {
+    backendBaseUrl: string;
+    publicBaseUrl: string;
+};
+export declare function getProvableConfig(): {
+    apiKey: string;
+    consumerId: string;
+};

package/dist/env.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PUBLIC_BASE_URL = exports.DEFAULT_BACKEND_URL = void 0;
+exports.parseDotEnv = parseDotEnv;
+exports.loadEnvFiles = loadEnvFiles;
+exports.getRuntimeConfig = getRuntimeConfig;
+exports.getProvableConfig = getProvableConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.DEFAULT_BACKEND_URL = 'http://localhost:3000/api';
+exports.DEFAULT_PUBLIC_BASE_URL = 'https://nullpay.app';
+const DEFAULT_PROVABLE_API_KEY = 'tWR9YWkM5SVmx1u3m7My8S4p4e2s84Oe';
+const DEFAULT_PROVABLE_CONSUMER_ID = '73ba1b21-d8f7-4d7f-bfd9-0408a4e183f3';
+function parseDotEnv(content) {
+    const parsed = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        const normalized = line.startsWith('export ') ? line.slice(7).trim() : line;
+        const separatorIndex = normalized.indexOf('=');
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = normalized.slice(0, separatorIndex).trim();
+        let value = normalized.slice(separatorIndex + 1).trim();
+        if (!key) {
+            continue;
+        }
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        parsed[key] = value;
+    }
+    return parsed;
+}
+function loadEnvFiles() {
+    const packageRoot = path_1.default.resolve(__dirname, '..');
+    const repoRoot = path_1.default.resolve(packageRoot, '..', '..');
+    const candidates = [
+        path_1.default.resolve(process.cwd(), '.env'),
+        path_1.default.resolve(packageRoot, '.env'),
+        path_1.default.resolve(repoRoot, '.env'),
+        path_1.default.resolve(repoRoot, 'backend', '.env'),
+    ];
+    for (const filePath of candidates) {
+        if (!fs_1.default.existsSync(filePath)) {
+            continue;
+        }
+        const values = parseDotEnv(fs_1.default.readFileSync(filePath, 'utf8'));
+        for (const [key, value] of Object.entries(values)) {
+            if (!process.env[key]) {
+                process.env[key] = value;
+            }
+        }
+    }
+}
+function getRuntimeConfig() {
+    loadEnvFiles();
+    return {
+        backendBaseUrl: process.env.NULLPAY_BACKEND_URL || exports.DEFAULT_BACKEND_URL,
+        publicBaseUrl: process.env.NULLPAY_PUBLIC_BASE_URL || exports.DEFAULT_PUBLIC_BASE_URL,
+    };
+}
+function getProvableConfig() {
+    loadEnvFiles();
+    return {
+        apiKey: process.env.PROVABLE_API_KEY || DEFAULT_PROVABLE_API_KEY,
+        consumerId: process.env.PROVABLE_CONSUMER_ID || process.env.PROVABLE_CONSUMER_KEY || DEFAULT_PROVABLE_CONSUMER_ID,
+    };
+}

package/dist/server.d.ts

@@ -1 +1 @@
-export {};
+export declare function startServer(): void;

package/dist/server.js

@@ -1,59 +1,11 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
+exports.startServer = startServer;
 const backend_client_1 = require("./backend-client");
+const env_1 = require("./env");
 const protocol_1 = require("./protocol");
 const session_store_1 = require("./session-store");
 const service_1 = require("./service");
-function parseDotEnv(content) {
-    const parsed = {};
-    for (const rawLine of content.split(/\r?\n/)) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith('#')) {
-            continue;
-        }
-        const normalized = line.startsWith('export ') ? line.slice(7).trim() : line;
-        const separatorIndex = normalized.indexOf('=');
-        if (separatorIndex <= 0) {
-            continue;
-        }
-        const key = normalized.slice(0, separatorIndex).trim();
-        let value = normalized.slice(separatorIndex + 1).trim();
-        if (!key) {
-            continue;
-        }
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
-        parsed[key] = value;
-    }
-    return parsed;
-}
-function loadEnvFiles() {
-    const packageRoot = path_1.default.resolve(__dirname, '..');
-    const repoRoot = path_1.default.resolve(packageRoot, '..', '..');
-    const candidates = [
-        path_1.default.resolve(process.cwd(), '.env'),
-        path_1.default.resolve(packageRoot, '.env'),
-        path_1.default.resolve(repoRoot, '.env'),
-        path_1.default.resolve(repoRoot, 'backend', '.env'),
-    ];
-    for (const filePath of candidates) {
-        if (!fs_1.default.existsSync(filePath)) {
-            continue;
-        }
-        const values = parseDotEnv(fs_1.default.readFileSync(filePath, 'utf8'));
-        for (const [key, value] of Object.entries(values)) {
-            if (!process.env[key]) {
-                process.env[key] = value;
-            }
-        }
-    }
-}
 function shieldStdoutForMcp() {
     const protocolWrite = process.stdout.write.bind(process.stdout);
     globalThis.__nullpayMcpStdoutWrite = (chunk) => protocolWrite(chunk);
@@ -73,39 +25,38 @@ function shieldStdoutForMcp() {
         return true;
     });
 }
-loadEnvFiles();
-shieldStdoutForMcp();
-const backendBaseUrl = process.env.NULLPAY_BACKEND_URL || 'http://localhost:3000/api';
-const publicBaseUrl = process.env.NULLPAY_PUBLIC_BASE_URL || 'https://nullpay.app';
-const mcpSecret = process.env.NULLPAY_MCP_SHARED_SECRET;
-const backend = new backend_client_1.NullPayBackendClient(backendBaseUrl, mcpSecret);
-const sessions = new session_store_1.SessionStore();
-const service = new service_1.NullPayMcpService(backend, sessions, publicBaseUrl);
-const server = new protocol_1.StdioJsonRpcServer(async (request) => {
-    if (request.method === 'initialize') {
-        return {
-            protocolVersion: String(request.params?.protocolVersion || '2025-11-25'),
-            capabilities: {
-                tools: {}
-            },
-            serverInfo: {
-                name: 'nullpay-mcp',
-                version: '0.1.0'
-            }
-        };
-    }
-    if (request.method === 'notifications/initialized') {
+function startServer() {
+    shieldStdoutForMcp();
+    const { backendBaseUrl, publicBaseUrl } = (0, env_1.getRuntimeConfig)();
+    const backend = new backend_client_1.NullPayBackendClient(backendBaseUrl);
+    const sessions = new session_store_1.SessionStore();
+    const service = new service_1.NullPayMcpService(backend, sessions, publicBaseUrl);
+    const server = new protocol_1.StdioJsonRpcServer(async (request) => {
+        if (request.method === 'initialize') {
+            return {
+                protocolVersion: String(request.params?.protocolVersion || '2025-11-25'),
+                capabilities: {
+                    tools: {}
+                },
+                serverInfo: {
+                    name: 'nullpay-mcp',
+                    version: '0.2.0'
+                }
+            };
+        }
+        if (request.method === 'notifications/initialized') {
+            return {};
+        }
+        if (request.method === 'tools/list') {
+            return { tools: service.listTools() };
+        }
+        if (request.method === 'tools/call') {
+            const name = String(request.params?.name || '');
+            const args = (request.params?.arguments || {});
+            return await service.callTool(name, args);
+        }
         return {};
-    }
-    if (request.method === 'tools/list') {
-        return { tools: service.listTools() };
-    }
-    if (request.method === 'tools/call') {
-        const name = String(request.params?.name || '');
-        const args = (request.params?.arguments || {});
-        return await service.callTool(name, args);
-    }
-    return {};
-});
-console.error('nullpay mcp starting');
-server.start();
+    });
+    console.error(`nullpay mcp starting against ${backendBaseUrl}`);
+    server.start();
+}

package/dist/setup.d.ts

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

package/dist/setup.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetupWizard = runSetupWizard;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("readline/promises"));
+const process_1 = require("process");
+function getClaudeCodeConfigPath() {
+    return path_1.default.join(os_1.default.homedir(), '.claude.json');
+}
+function getClaudeDesktopConfigPath() {
+    if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA || path_1.default.join(os_1.default.homedir(), 'AppData', 'Local');
+        const packagedClaudePath = path_1.default.join(localAppData, 'Packages', 'Claude_pzs8sxrjxfjjc', 'LocalCache', 'Roaming', 'Claude', 'claude_desktop_config.json');
+        if (fs_1.default.existsSync(packagedClaudePath) || fs_1.default.existsSync(path_1.default.dirname(packagedClaudePath))) {
+            return packagedClaudePath;
+        }
+    }
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA || path_1.default.join(os_1.default.homedir(), 'AppData', 'Roaming');
+        return path_1.default.join(appData, 'Claude', 'claude_desktop_config.json');
+    }
+    if (process.platform === 'darwin') {
+        return path_1.default.join(os_1.default.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    return path_1.default.join(os_1.default.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+}
+function buildServerEntry(answers) {
+    const env = {
+        NULLPAY_MAIN_ADDRESS: answers.address,
+        NULLPAY_MAIN_PRIVATE_KEY: answers.privateKey,
+        NULLPAY_MAIN_PASSWORD: answers.password,
+    };
+    if (process.platform === 'win32') {
+        return {
+            command: 'cmd',
+            args: ['/c', 'npx', '-y', '@nullpay/mcp', 'server'],
+            env,
+        };
+    }
+    return {
+        command: 'npx',
+        args: ['-y', '@nullpay/mcp', 'server'],
+        env,
+    };
+}
+function readJsonConfig(configPath) {
+    if (!fs_1.default.existsSync(configPath)) {
+        return {};
+    }
+    const raw = fs_1.default.readFileSync(configPath, 'utf8').trim();
+    if (!raw) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') {
+        throw new Error(`Config at ${configPath} is not a JSON object.`);
+    }
+    return parsed;
+}
+function writeMcpConfig(configPath, serverName, entry) {
+    const current = readJsonConfig(configPath);
+    const currentMcpServers = current.mcpServers && typeof current.mcpServers === 'object' && !Array.isArray(current.mcpServers)
+        ? current.mcpServers
+        : {};
+    const next = {
+        ...current,
+        mcpServers: {
+            ...currentMcpServers,
+            [serverName]: entry,
+        },
+    };
+    fs_1.default.mkdirSync(path_1.default.dirname(configPath), { recursive: true });
+    fs_1.default.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+}
+async function askChoice(rl) {
+    process_1.stdout.write('Where do you want to install NullPay MCP?\n');
+    process_1.stdout.write('1. Claude Code\n');
+    process_1.stdout.write('2. Claude Desktop\n');
+    process_1.stdout.write('3. Cancel\n');
+    while (true) {
+        const answer = (await rl.question('Choose 1, 2, or 3: ')).trim();
+        if (answer === '1')
+            return 'claude-code';
+        if (answer === '2')
+            return 'claude-desktop';
+        if (answer === '3')
+            return null;
+        process_1.stdout.write('Please enter 1, 2, or 3.\n');
+    }
+}
+async function askRequired(rl, label) {
+    while (true) {
+        const answer = (await rl.question(`${label}: `)).trim();
+        if (answer) {
+            return answer;
+        }
+        process_1.stdout.write(`${label} is required.\n`);
+    }
+}
+async function collectAnswers(rl) {
+    process_1.stdout.write('\nNullPay will configure Claude automatically. You only need to provide your wallet credentials here.\n\n');
+    const address = await askRequired(rl, 'Main wallet address');
+    const privateKey = await askRequired(rl, 'Main wallet private key');
+    const password = await askRequired(rl, 'NullPay password');
+    return {
+        address,
+        privateKey,
+        password,
+    };
+}
+async function runSetupWizard() {
+    const rl = promises_1.default.createInterface({ input: process_1.stdin, output: process_1.stdout });
+    try {
+        process_1.stdout.write('NullPay MCP setup\n\n');
+        const choice = await askChoice(rl);
+        if (!choice) {
+            process_1.stdout.write('Setup cancelled.\n');
+            return;
+        }
+        const answers = await collectAnswers(rl);
+        const entry = buildServerEntry(answers);
+        const configPath = choice === 'claude-code' ? getClaudeCodeConfigPath() : getClaudeDesktopConfigPath();
+        writeMcpConfig(configPath, 'nullpay', entry);
+        process_1.stdout.write(`\nNullPay MCP was added to ${configPath}\n`);
+        if (choice === 'claude-code') {
+            process_1.stdout.write('Next step: restart Claude Code or run `claude mcp list` to confirm the server is registered.\n');
+        }
+        else {
+            process_1.stdout.write('Next step: fully restart Claude Desktop so it reloads the new MCP config.\n');
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/utils/crypto.d.ts

@@ -1,3 +1,3 @@
-export declare function hashAddress(address: string): string;
-export declare function encryptWithPassword(text: string, password: string): Promise<string>;
-export declare function decryptWithPassword(payload: string, password: string): Promise<string>;
+export declare function hashAddress(address: string): string;
+export declare function encryptWithPassword(text: string, password: string): Promise<string>;
+export declare function decryptWithPassword(payload: string, password: string): Promise<string>;

package/dist/utils/crypto.js

@@ -1,66 +1,66 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.hashAddress = hashAddress;
-exports.encryptWithPassword = encryptWithPassword;
-exports.decryptWithPassword = decryptWithPassword;
-const crypto_1 = __importDefault(require("crypto"));
-const ITERATIONS = 100000;
-const KEY_LENGTH = 32;
-const DIGEST = 'sha256';
-function toBase64(buffer) {
-    return Buffer.from(buffer).toString('base64');
-}
-function fromBase64(value) {
-    return Buffer.from(value, 'base64');
-}
-function hashAddress(address) {
-    return crypto_1.default.createHash('sha256').update(address).digest('hex');
-}
-async function encryptWithPassword(text, password) {
-    const salt = crypto_1.default.randomBytes(16);
-    const iv = crypto_1.default.randomBytes(12);
-    const key = await new Promise((resolve, reject) => {
-        crypto_1.default.pbkdf2(password, salt, ITERATIONS, KEY_LENGTH, DIGEST, (error, derivedKey) => {
-            if (error)
-                reject(error);
-            else
-                resolve(derivedKey);
-        });
-    });
-    const cipher = crypto_1.default.createCipheriv('aes-256-gcm', key, iv);
-    const ciphertext = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    return `${toBase64(salt)}:${toBase64(iv)}:${toBase64(Buffer.concat([ciphertext, tag]))}`;
-}
-async function decryptWithPassword(payload, password) {
-    const parts = payload.split(':');
-    if (parts.length !== 3) {
-        throw new Error('Invalid encrypted payload format');
-    }
-    const [saltPart, ivPart, cipherPart] = parts;
-    const salt = fromBase64(saltPart);
-    const iv = fromBase64(ivPart);
-    const cipherWithTag = fromBase64(cipherPart);
-    const ciphertext = cipherWithTag.subarray(0, cipherWithTag.length - 16);
-    const tag = cipherWithTag.subarray(cipherWithTag.length - 16);
-    const key = await new Promise((resolve, reject) => {
-        crypto_1.default.pbkdf2(password, salt, ITERATIONS, KEY_LENGTH, DIGEST, (error, derivedKey) => {
-            if (error)
-                reject(error);
-            else
-                resolve(derivedKey);
-        });
-    });
-    try {
-        const decipher = crypto_1.default.createDecipheriv('aes-256-gcm', key, iv);
-        decipher.setAuthTag(tag);
-        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
-        return plaintext.toString('utf8');
-    }
-    catch {
-        throw new Error('Incorrect password or corrupted data');
-    }
-}
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashAddress = hashAddress;
+exports.encryptWithPassword = encryptWithPassword;
+exports.decryptWithPassword = decryptWithPassword;
+const crypto_1 = __importDefault(require("crypto"));
+const ITERATIONS = 100000;
+const KEY_LENGTH = 32;
+const DIGEST = 'sha256';
+function toBase64(buffer) {
+    return Buffer.from(buffer).toString('base64');
+}
+function fromBase64(value) {
+    return Buffer.from(value, 'base64');
+}
+function hashAddress(address) {
+    return crypto_1.default.createHash('sha256').update(address).digest('hex');
+}
+async function encryptWithPassword(text, password) {
+    const salt = crypto_1.default.randomBytes(16);
+    const iv = crypto_1.default.randomBytes(12);
+    const key = await new Promise((resolve, reject) => {
+        crypto_1.default.pbkdf2(password, salt, ITERATIONS, KEY_LENGTH, DIGEST, (error, derivedKey) => {
+            if (error)
+                reject(error);
+            else
+                resolve(derivedKey);
+        });
+    });
+    const cipher = crypto_1.default.createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${toBase64(salt)}:${toBase64(iv)}:${toBase64(Buffer.concat([ciphertext, tag]))}`;
+}
+async function decryptWithPassword(payload, password) {
+    const parts = payload.split(':');
+    if (parts.length !== 3) {
+        throw new Error('Invalid encrypted payload format');
+    }
+    const [saltPart, ivPart, cipherPart] = parts;
+    const salt = fromBase64(saltPart);
+    const iv = fromBase64(ivPart);
+    const cipherWithTag = fromBase64(cipherPart);
+    const ciphertext = cipherWithTag.subarray(0, cipherWithTag.length - 16);
+    const tag = cipherWithTag.subarray(cipherWithTag.length - 16);
+    const key = await new Promise((resolve, reject) => {
+        crypto_1.default.pbkdf2(password, salt, ITERATIONS, KEY_LENGTH, DIGEST, (error, derivedKey) => {
+            if (error)
+                reject(error);
+            else
+                resolve(derivedKey);
+        });
+    });
+    try {
+        const decipher = crypto_1.default.createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plaintext.toString('utf8');
+    }
+    catch {
+        throw new Error('Incorrect password or corrupted data');
+    }
+}

package/dist/utils/env.d.ts

@@ -1,6 +1,6 @@
-export declare function readEnvTrimmed(name: string): string | undefined;
-export declare function getMainWalletEnv(): {
-    address: string | undefined;
-    password: string | undefined;
-    privateKey: string | undefined;
-};
+export declare function readEnvTrimmed(name: string): string | undefined;
+export declare function getMainWalletEnv(): {
+    address: string | undefined;
+    password: string | undefined;
+    privateKey: string | undefined;
+};

package/dist/utils/env.js

@@ -1,15 +1,15 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.readEnvTrimmed = readEnvTrimmed;
-exports.getMainWalletEnv = getMainWalletEnv;
-function readEnvTrimmed(name) {
-    const value = process.env[name]?.trim();
-    return value ? value : undefined;
-}
-function getMainWalletEnv() {
-    return {
-        address: readEnvTrimmed('NULLPAY_MAIN_ADDRESS'),
-        password: readEnvTrimmed('NULLPAY_MAIN_PASSWORD'),
-        privateKey: readEnvTrimmed('NULLPAY_MAIN_PRIVATE_KEY') || readEnvTrimmed('NULLPAY_MAIN_PVT_KEY')
-    };
-}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readEnvTrimmed = readEnvTrimmed;
+exports.getMainWalletEnv = getMainWalletEnv;
+function readEnvTrimmed(name) {
+    const value = process.env[name]?.trim();
+    return value ? value : undefined;
+}
+function getMainWalletEnv() {
+    return {
+        address: readEnvTrimmed('NULLPAY_MAIN_ADDRESS'),
+        password: readEnvTrimmed('NULLPAY_MAIN_PASSWORD'),
+        privateKey: readEnvTrimmed('NULLPAY_MAIN_PRIVATE_KEY') || readEnvTrimmed('NULLPAY_MAIN_PVT_KEY')
+    };
+}

package/dist/utils/esm.d.ts

@@ -1 +1 @@
-export declare function dynamicImport<T = any>(specifier: string): Promise<T>;
+export declare function dynamicImport<T = any>(specifier: string): Promise<T>;

package/dist/utils/esm.js

@@ -1,7 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.dynamicImport = dynamicImport;
-async function dynamicImport(specifier) {
-    const importer = new Function('s', 'return import(s);');
-    return await importer(specifier);
-}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dynamicImport = dynamicImport;
+async function dynamicImport(specifier) {
+    const importer = new Function('s', 'return import(s);');
+    return await importer(specifier);
+}

package/dist/utils/formatters.d.ts

@@ -1,14 +1,14 @@
-import { Currency, InvoiceRecord, InvoiceType } from '../types';
-export declare function normalizeCurrency(value?: string): Currency;
-export declare function normalizePaymentCurrency(value?: string): Exclude<Currency, 'ANY'> | undefined;
-export declare function normalizeInvoiceType(value?: string): InvoiceType;
-export declare function tokenTypeLabel(tokenType?: number | null): string;
-export declare function invoiceTypeLabel(invoiceType?: number | null): string;
-export declare function currencyToTokenType(currency?: Currency | null): number;
-export declare function linkTokenToCurrency(token?: string | null): Currency | undefined;
-export declare function linkTypeToInvoiceType(type?: string | null): InvoiceType;
-export declare function parseAmount(value?: string | number | null): number | undefined;
-export declare function shouldMarkInvoiceSettled(invoiceType?: number | null): boolean;
-export declare function formatInvoiceSummary(invoice: InvoiceRecord): string;
-export declare function getAmountSource(invoice: InvoiceRecord): 'record' | 'database' | 'missing';
-export declare function buildAmountLookupHint(invoice: InvoiceRecord, hasInvoiceLookupKey: boolean): string;
+import { Currency, InvoiceRecord, InvoiceType } from '../types';
+export declare function normalizeCurrency(value?: string): Currency;
+export declare function normalizePaymentCurrency(value?: string): Exclude<Currency, 'ANY'> | undefined;
+export declare function normalizeInvoiceType(value?: string): InvoiceType;
+export declare function tokenTypeLabel(tokenType?: number | null): string;
+export declare function invoiceTypeLabel(invoiceType?: number | null): string;
+export declare function currencyToTokenType(currency?: Currency | null): number;
+export declare function linkTokenToCurrency(token?: string | null): Currency | undefined;
+export declare function linkTypeToInvoiceType(type?: string | null): InvoiceType;
+export declare function parseAmount(value?: string | number | null): number | undefined;
+export declare function shouldMarkInvoiceSettled(invoiceType?: number | null): boolean;
+export declare function formatInvoiceSummary(invoice: InvoiceRecord): string;
+export declare function getAmountSource(invoice: InvoiceRecord): 'record' | 'database' | 'missing';
+export declare function buildAmountLookupHint(invoice: InvoiceRecord, hasInvoiceLookupKey: boolean): string;

package/dist/utils/formatters.js

@@ -1,132 +1,132 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeCurrency = normalizeCurrency;
-exports.normalizePaymentCurrency = normalizePaymentCurrency;
-exports.normalizeInvoiceType = normalizeInvoiceType;
-exports.tokenTypeLabel = tokenTypeLabel;
-exports.invoiceTypeLabel = invoiceTypeLabel;
-exports.currencyToTokenType = currencyToTokenType;
-exports.linkTokenToCurrency = linkTokenToCurrency;
-exports.linkTypeToInvoiceType = linkTypeToInvoiceType;
-exports.parseAmount = parseAmount;
-exports.shouldMarkInvoiceSettled = shouldMarkInvoiceSettled;
-exports.formatInvoiceSummary = formatInvoiceSummary;
-exports.getAmountSource = getAmountSource;
-exports.buildAmountLookupHint = buildAmountLookupHint;
-function normalizeCurrency(value) {
-    const normalized = (value || 'CREDITS').toUpperCase();
-    if (normalized === 'USDCX' || normalized === 'USAD' || normalized === 'ANY') {
-        return normalized;
-    }
-    return 'CREDITS';
-}
-function normalizePaymentCurrency(value) {
-    if (!value) {
-        return undefined;
-    }
-    const normalized = value.toUpperCase();
-    if (normalized === 'USDCX' || normalized === 'USAD') {
-        return normalized;
-    }
-    return 'CREDITS';
-}
-function normalizeInvoiceType(value) {
-    if (value === 'multipay' || value === 'donation')
-        return value;
-    return 'standard';
-}
-function tokenTypeLabel(tokenType) {
-    if (tokenType === 1)
-        return 'USDCX';
-    if (tokenType === 2)
-        return 'USAD';
-    if (tokenType === 3)
-        return 'ANY';
-    return 'CREDITS';
-}
-function invoiceTypeLabel(invoiceType) {
-    if (invoiceType === 1)
-        return 'multipay';
-    if (invoiceType === 2)
-        return 'donation';
-    return 'standard';
-}
-function currencyToTokenType(currency) {
-    if (currency === 'USDCX')
-        return 1;
-    if (currency === 'USAD')
-        return 2;
-    if (currency === 'ANY')
-        return 3;
-    return 0;
-}
-function linkTokenToCurrency(token) {
-    if (!token) {
-        return undefined;
-    }
-    const normalized = token.trim().toLowerCase();
-    if (normalized === 'usdcx')
-        return 'USDCX';
-    if (normalized === 'usad')
-        return 'USAD';
-    if (normalized === 'any')
-        return 'ANY';
-    return 'CREDITS';
-}
-function linkTypeToInvoiceType(type) {
-    if (type === 'multipay' || type === 'donation') {
-        return type;
-    }
-    return 'standard';
-}
-function parseAmount(value) {
-    if (typeof value === 'number') {
-        return Number.isFinite(value) ? value : undefined;
-    }
-    if (!value) {
-        return undefined;
-    }
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-}
-function shouldMarkInvoiceSettled(invoiceType) {
-    return invoiceType !== 1 && invoiceType !== 2;
-}
-function formatInvoiceSummary(invoice) {
-    const paymentIds = Array.isArray(invoice.payment_tx_ids) && invoice.payment_tx_ids.length > 0
-        ? invoice.payment_tx_ids.join(', ')
-        : 'none';
-    const amount = invoice.amount ?? 0;
-    return [
-        `invoice=${invoice.invoice_hash}`,
-        `status=${invoice.status}`,
-        `amount=${amount}`,
-        `token=${tokenTypeLabel(invoice.token_type)}`,
-        `type=${invoiceTypeLabel(invoice.invoice_type)}`,
-        `created=${invoice.created_at || 'unknown'}`,
-        `invoice_tx=${invoice.invoice_transaction_id || 'none'}`,
-        `payment_txs=${paymentIds}`
-    ].join(' | ');
-}
-function getAmountSource(invoice) {
-    if (typeof invoice.amount_micro === 'number') {
-        return 'record';
-    }
-    if (typeof invoice.amount === 'number' && invoice.amount > 0) {
-        return 'database';
-    }
-    return 'missing';
-}
-function buildAmountLookupHint(invoice, hasInvoiceLookupKey) {
-    const amountSource = getAmountSource(invoice);
-    if (amountSource === 'record') {
-        return ' | amount_source=record';
-    }
-    if (amountSource === 'database') {
-        return ' | amount_source=database';
-    }
-    if (hasInvoiceLookupKey) {
-        return ' | amount_source=missing | record_lookup=not_found_or_unreadable_for_selected_wallet';
-    }
-    return ' | amount_source=db_only (private key missing to fetch record-backed amount)';
-}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCurrency = normalizeCurrency;
+exports.normalizePaymentCurrency = normalizePaymentCurrency;
+exports.normalizeInvoiceType = normalizeInvoiceType;
+exports.tokenTypeLabel = tokenTypeLabel;
+exports.invoiceTypeLabel = invoiceTypeLabel;
+exports.currencyToTokenType = currencyToTokenType;
+exports.linkTokenToCurrency = linkTokenToCurrency;
+exports.linkTypeToInvoiceType = linkTypeToInvoiceType;
+exports.parseAmount = parseAmount;
+exports.shouldMarkInvoiceSettled = shouldMarkInvoiceSettled;
+exports.formatInvoiceSummary = formatInvoiceSummary;
+exports.getAmountSource = getAmountSource;
+exports.buildAmountLookupHint = buildAmountLookupHint;
+function normalizeCurrency(value) {
+    const normalized = (value || 'CREDITS').toUpperCase();
+    if (normalized === 'USDCX' || normalized === 'USAD' || normalized === 'ANY') {
+        return normalized;
+    }
+    return 'CREDITS';
+}
+function normalizePaymentCurrency(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.toUpperCase();
+    if (normalized === 'USDCX' || normalized === 'USAD') {
+        return normalized;
+    }
+    return 'CREDITS';
+}
+function normalizeInvoiceType(value) {
+    if (value === 'multipay' || value === 'donation')
+        return value;
+    return 'standard';
+}
+function tokenTypeLabel(tokenType) {
+    if (tokenType === 1)
+        return 'USDCX';
+    if (tokenType === 2)
+        return 'USAD';
+    if (tokenType === 3)
+        return 'ANY';
+    return 'CREDITS';
+}
+function invoiceTypeLabel(invoiceType) {
+    if (invoiceType === 1)
+        return 'multipay';
+    if (invoiceType === 2)
+        return 'donation';
+    return 'standard';
+}
+function currencyToTokenType(currency) {
+    if (currency === 'USDCX')
+        return 1;
+    if (currency === 'USAD')
+        return 2;
+    if (currency === 'ANY')
+        return 3;
+    return 0;
+}
+function linkTokenToCurrency(token) {
+    if (!token) {
+        return undefined;
+    }
+    const normalized = token.trim().toLowerCase();
+    if (normalized === 'usdcx')
+        return 'USDCX';
+    if (normalized === 'usad')
+        return 'USAD';
+    if (normalized === 'any')
+        return 'ANY';
+    return 'CREDITS';
+}
+function linkTypeToInvoiceType(type) {
+    if (type === 'multipay' || type === 'donation') {
+        return type;
+    }
+    return 'standard';
+}
+function parseAmount(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function shouldMarkInvoiceSettled(invoiceType) {
+    return invoiceType !== 1 && invoiceType !== 2;
+}
+function formatInvoiceSummary(invoice) {
+    const paymentIds = Array.isArray(invoice.payment_tx_ids) && invoice.payment_tx_ids.length > 0
+        ? invoice.payment_tx_ids.join(', ')
+        : 'none';
+    const amount = invoice.amount ?? 0;
+    return [
+        `invoice=${invoice.invoice_hash}`,
+        `status=${invoice.status}`,
+        `amount=${amount}`,
+        `token=${tokenTypeLabel(invoice.token_type)}`,
+        `type=${invoiceTypeLabel(invoice.invoice_type)}`,
+        `created=${invoice.created_at || 'unknown'}`,
+        `invoice_tx=${invoice.invoice_transaction_id || 'none'}`,
+        `payment_txs=${paymentIds}`
+    ].join(' | ');
+}
+function getAmountSource(invoice) {
+    if (typeof invoice.amount_micro === 'number') {
+        return 'record';
+    }
+    if (typeof invoice.amount === 'number' && invoice.amount > 0) {
+        return 'database';
+    }
+    return 'missing';
+}
+function buildAmountLookupHint(invoice, hasInvoiceLookupKey) {
+    const amountSource = getAmountSource(invoice);
+    if (amountSource === 'record') {
+        return ' | amount_source=record';
+    }
+    if (amountSource === 'database') {
+        return ' | amount_source=database';
+    }
+    if (hasInvoiceLookupKey) {
+        return ' | amount_source=missing | record_lookup=not_found_or_unreadable_for_selected_wallet';
+    }
+    return ' | amount_source=db_only (private key missing to fetch record-backed amount)';
+}

package/package.json

@@ -1,39 +1,34 @@
 {
-  "name": "@nullpay/mcp",
-  "version": "1.0.0",
-  "description": "NullPay MCP server for conversational invoice and payment flows",
-  "main": "dist/server.js",
-  "types": "dist/server.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "start": "node dist/server.js",
-    "dev": "ts-node src/server.ts"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "dependencies": {
-    "@provablehq/sdk": "^0.9.18",
-    "@provablehq/wasm": "^0.9.18"
-  },
-  "author": "geekofdhruv",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/geekofdhruv/NullPay.git",
-    "directory": "packages/nullpay-mcp"
-  },
-  "bugs": {
-    "url": "https://github.com/geekofdhruv/NullPay/issues"
-  },
-  "homepage": "https://github.com/geekofdhruv/NullPay/tree/main/packages/nullpay-mcp#readme",
-  "devDependencies": {
-    "@types/node": "^25.4.0",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
-  }
+    "name":  "@nullpay/mcp",
+    "version":  "1.0.1",
+    "description":  "NullPay MCP server and Claude setup wizard for conversational payment flows",
+    "type":  "commonjs",
+    "main":  "dist/server.js",
+    "types":  "dist/server.d.ts",
+    "bin":  {
+                "nullpay-mcp":  "./dist/cli.js"
+            },
+    "files":  [
+                  "dist",
+                  "README.md"
+              ],
+    "scripts":  {
+                    "build":  "tsc -p tsconfig.json",
+                    "start":  "node dist/cli.js server",
+                    "dev":  "ts-node src/cli.ts server",
+                    "setup":  "ts-node src/cli.ts setup",
+                    "prepublishOnly":  "npm run build"
+                },
+    "publishConfig":  {
+                          "access":  "public"
+                      },
+    "dependencies":  {
+                         "@provablehq/sdk":  "^0.9.18",
+                         "@provablehq/wasm":  "^0.9.18"
+                     },
+    "devDependencies":  {
+                            "@types/node":  "^25.4.0",
+                            "ts-node":  "^10.9.2",
+                            "typescript":  "^5.9.3"
+                        }
 }