@nullpay/mcp 1.0.0 → 1.0.3

package/README.md

@@ -1,49 +1,216 @@
 # @nullpay/mcp
 
-NullPay MCP (Model Context Protocol) server for conversational invoice and payment flows.
+NullPay MCP is a local Model Context Protocol server for Claude that lets users create invoices, pay invoices, and inspect transactions through chat.
 
-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.
+The package is designed so the user only needs to provide their own wallet credentials:
 
-## Features
+- `NULLPAY_MAIN_ADDRESS`
+- `NULLPAY_MAIN_PRIVATE_KEY`
+- `NULLPAY_MAIN_PASSWORD`
 
-- **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.
+NullPay-owned infrastructure stays inside the package or on the backend:
 
-## Installation
+- default backend API: `https://nullpay-backend-ib5q4.ondigitalocean.app/api`
+- default public app URL: `https://nullpay.app`
+- relayer private key: backend only
+
+## How It Works
+
+1. The user runs the setup wizard.
+2. The wizard asks whether to install into Claude Code or Claude Desktop.
+3. The wizard asks for the user's address, private key, and password.
+4. The wizard writes the MCP config file automatically on the user's machine.
+5. Claude starts the local NullPay MCP server with `@nullpay/mcp server`.
+6. The MCP server talks to the NullPay backend and keeps the user's private-key operations local.
+
+## Install For End Users
+
+Run the setup wizard:
+
+```bash
+npx -y @nullpay/mcp
+```
+
+You can also call the setup command explicitly:
 
 ```bash
-npm install @nullpay/mcp
+npx -y @nullpay/mcp setup
 ```
 
-## Usage
+The wizard writes the required MCP config entry automatically.
 
-### As an MCP Server
+## Manual Claude Configuration
 
-Add the following to your MCP client configuration (e.g., `claude_desktop_config.json`):
+The setup wizard is the recommended path, but you can also add the MCP server manually.
+
+### Claude Desktop
 
 ```json
 {
   "mcpServers": {
     "nullpay": {
       "command": "npx",
-      "args": ["-y", "@nullpay/mcp"],
+      "args": ["-y", "@nullpay/mcp", "server"],
+      "env": {
+        "NULLPAY_MAIN_ADDRESS": "aleo1...",
+        "NULLPAY_MAIN_PRIVATE_KEY": "APrivateKey1...",
+        "NULLPAY_MAIN_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+On Windows, Claude Desktop may need:
+
+```json
+{
+  "mcpServers": {
+    "nullpay": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@nullpay/mcp", "server"],
       "env": {
-        "NULLPAY_BACKEND_URL": "https://your-api.com/api",
-        "NULLPAY_MCP_SHARED_SECRET": "your-secret"
+        "NULLPAY_MAIN_ADDRESS": "aleo1...",
+        "NULLPAY_MAIN_PRIVATE_KEY": "APrivateKey1...",
+        "NULLPAY_MAIN_PASSWORD": "your-password"
       }
     }
   }
 }
 ```
 
-## Configuration
+### Claude Code
+
+The setup wizard can also write the Claude Code config automatically. If needed, the same `server` command is used there too.
+
+After setup, restart Claude and verify the MCP server is available.
+
+## Commands
+
+### Published package
+
+Start the interactive installer:
+
+```bash
+npx -y @nullpay/mcp
+```
+
+Run the MCP server directly:
 
-The server requires the following environment variables:
+```bash
+npx -y @nullpay/mcp server
+```
+
+Show help:
+
+```bash
+npx -y @nullpay/mcp --help
+```
+
+### Local development
+
+From `packages/nullpay-mcp`:
 
-- `NULLPAY_BACKEND_URL`: The base URL of your NullPay backend instance.
-- `NULLPAY_MCP_SHARED_SECRET`: A shared secret to authenticate with the backend.
+```bash
+npm install
+npm run build
+node dist/cli.js
+```
+
+Run the local MCP server directly:
+
+```bash
+node dist/cli.js server
+```
+
+Run in TypeScript during development:
+
+```bash
+npm run dev
+```
+
+## Tooling And Login Model
+
+The MCP server exposes four tools:
+
+- `login`
+- `create_invoice`
+- `pay_invoice`
+- `get_transaction_info`
+
+### `login`
+
+`login` creates or resumes the NullPay session inside the MCP process.
+
+Normal path:
+
+- uses address + password from tool input or env
+- loads the backend profile
+- validates the password by decrypting stored wallet data
+- restores burner wallet metadata when present
+
+Recovery path:
+
+- if password is missing but `NULLPAY_MAIN_PRIVATE_KEY` is available
+- the server can recover the backed-up password from on-chain backup records
+- if a full burner backup exists on-chain, it restores the burner wallet automatically
+
+### `create_invoice`
+
+- uses the active wallet address
+- calls the NullPay backend relayer endpoint
+- waits for the invoice hash to resolve from Aleo mapping
+- stores the invoice row in the backend
+- returns a payment link
+
+### `pay_invoice`
+
+- accepts either a full NullPay payment link or an invoice hash
+- prefers the full payment link so merchant address, amount, salt, token, and session id are available immediately
+- builds the payment authorization locally with the user's wallet key
+- sends the authorization to the backend sponsor endpoint
+
+### `get_transaction_info`
+
+- fetches invoice rows from the backend
+- enriches private record-backed data locally when the main private key is available
+
+## Credential Model
+
+User-provided values:
+
+- `NULLPAY_MAIN_ADDRESS`
+- `NULLPAY_MAIN_PRIVATE_KEY`
+- `NULLPAY_MAIN_PASSWORD`
+
+Bundled or backend-side values:
+
+- `NULLPAY_BACKEND_URL` defaults internally to production
+- `NULLPAY_PUBLIC_BASE_URL` defaults internally to production
+- relayer secrets stay on the backend
+
+## Security Notes
+
+- The user's private key is intended to stay local to the MCP process.
+- The config file used by Claude contains sensitive wallet credentials and should be treated like a secret file.
+- The MCP server never returns decrypted private keys in tool output.
+- Password recovery from on-chain records only works when the main private key is available locally.
+
+## Publishing
+
+From `packages/nullpay-mcp`:
+
+```bash
+npm run build
+npm publish --access public
+```
+
+If npm 2FA is enabled:
+
+```bash
+npm publish --access public --otp=123456
+```
 
 ## License
 
-MIT
+MIT

package/dist/aleo.d.ts

@@ -53,8 +53,24 @@ export declare function createInvoiceDbRecord(args: {
     }[] | null;
     for_sdk: boolean;
 };
+export interface ParsedBurnerBackupRecord {
+    owner: string;
+    burnerAddress: string;
+    passwordPart: string;
+    pkParts: string[];
+    plaintext: string;
+}
+export interface RecoveredOnChainWalletBackup {
+    password: string;
+    burnerAddress?: string;
+    encryptedBurnerKey?: string;
+    source: 'password_only' | 'full_burner';
+}
 export declare function parseOwnedInvoiceRecord(plaintext: string): ParsedOwnedInvoiceRecord | null;
+export declare function parseBurnerBackupRecord(plaintext: string): ParsedBurnerBackupRecord | null;
 export declare function fetchOwnedInvoiceRecords(privateKey: string): Promise<ParsedOwnedInvoiceRecord[]>;
+export declare function fetchOwnedBurnerBackupRecords(privateKey: string): Promise<ParsedBurnerBackupRecord[]>;
+export declare function recoverOnChainWalletBackup(privateKey: string, ownerAddress: string): Promise<RecoveredOnChainWalletBackup | null>;
 export declare function fetchOwnedInvoiceRecordByHash(privateKey: string, invoiceHash: string): Promise<ParsedOwnedInvoiceRecord | null>;
 export declare function enrichInvoiceWithRecordAmount(invoice: InvoiceRecord, privateKey?: string | null): Promise<InvoiceRecord>;
 export declare function createSponsoredPaymentAuthorization(args: {

package/dist/aleo.js

@@ -13,12 +13,16 @@ exports.invoiceTypeToNumber = invoiceTypeToNumber;
 exports.buildPaymentLink = buildPaymentLink;
 exports.createInvoiceDbRecord = createInvoiceDbRecord;
 exports.parseOwnedInvoiceRecord = parseOwnedInvoiceRecord;
+exports.parseBurnerBackupRecord = parseBurnerBackupRecord;
 exports.fetchOwnedInvoiceRecords = fetchOwnedInvoiceRecords;
+exports.fetchOwnedBurnerBackupRecords = fetchOwnedBurnerBackupRecords;
+exports.recoverOnChainWalletBackup = recoverOnChainWalletBackup;
 exports.fetchOwnedInvoiceRecordByHash = fetchOwnedInvoiceRecordByHash;
 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';
@@ -51,6 +55,30 @@ function fieldToString(fieldVal) {
         return '';
     }
 }
+function fieldChunksToString(chunks) {
+    let result = '';
+    for (const chunk of chunks) {
+        if (!chunk || chunk === '0field' || chunk === '0') {
+            continue;
+        }
+        const numeric = chunk.replace('field', '').replace('u128', '').replace('u64', '');
+        let value;
+        try {
+            value = BigInt(numeric);
+        }
+        catch {
+            continue;
+        }
+        let hex = value.toString(16);
+        if (hex.length % 2 !== 0) {
+            hex = '0' + hex;
+        }
+        for (let i = 0; i < hex.length; i += 2) {
+            result += String.fromCharCode(Number.parseInt(hex.slice(i, i + 2), 16));
+        }
+    }
+    return result;
+}
 function parseNumericValue(value) {
     if (!value) {
         return 0;
@@ -206,12 +234,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.');
     }
@@ -308,6 +332,41 @@ function parseOwnedInvoiceRecord(plaintext) {
         return null;
     }
 }
+function parseBurnerBackupRecord(plaintext) {
+    try {
+        const getVal = (key) => {
+            const regex = new RegExp(`(?:${key}|"${key}"):\\s*([\\w\\d\\.]+)`);
+            const match = plaintext.match(regex);
+            if (match && match[1]) {
+                return match[1].replace('.private', '').replace('.public', '');
+            }
+            return null;
+        };
+        const owner = getVal('owner');
+        const burnerAddress = getVal('burner_address');
+        const passwordPart = getVal('password_part');
+        if (!burnerAddress || !passwordPart) {
+            return null;
+        }
+        const pkParts = [];
+        for (let i = 1; i <= 10; i += 1) {
+            const part = getVal(`pk_part_${i}`);
+            if (part && part !== '0field' && part !== '0') {
+                pkParts.push(part);
+            }
+        }
+        return {
+            owner: owner || '',
+            burnerAddress,
+            passwordPart,
+            pkParts,
+            plaintext,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 async function fetchOwnedInvoiceRecords(privateKey) {
     const session = await getScannerSession(privateKey);
     const records = await fetchOwnedProgramRecords(session, exports.PROGRAM_ID);
@@ -328,6 +387,67 @@ async function fetchOwnedInvoiceRecords(privateKey) {
     }
     return parsed;
 }
+async function fetchOwnedBurnerBackupRecords(privateKey) {
+    const session = await getScannerSession(privateKey);
+    const records = await fetchOwnedProgramRecords(session, exports.PROGRAM_ID);
+    const parsed = [];
+    for (const record of records) {
+        let plaintext = record.record_plaintext || record.plaintext || '';
+        if (!plaintext && record.record_ciphertext) {
+            const { RecordCiphertext } = await (0, esm_1.dynamicImport)('@provablehq/sdk');
+            const ciphertext = RecordCiphertext.fromString(record.record_ciphertext);
+            plaintext = ciphertext.decrypt(session.account.viewKey()).toString();
+        }
+        if (!plaintext)
+            continue;
+        const burnerRecord = parseBurnerBackupRecord(plaintext);
+        if (burnerRecord) {
+            parsed.push(burnerRecord);
+        }
+    }
+    return parsed;
+}
+async function recoverOnChainWalletBackup(privateKey, ownerAddress) {
+    const records = await fetchOwnedBurnerBackupRecords(privateKey);
+    let passwordOnlyMatch = null;
+    let fullBurnerMatch = null;
+    for (const record of records) {
+        const ownerMatches = record.owner === ownerAddress;
+        const passwordOnlyMatches = record.burnerAddress === ownerAddress;
+        if (!ownerMatches && !passwordOnlyMatches) {
+            continue;
+        }
+        const encryptedPayload = fieldChunksToString(record.pkParts);
+        const hasRealPayload = Boolean(encryptedPayload && !encryptedPayload.startsWith('0'));
+        if (hasRealPayload) {
+            fullBurnerMatch = record;
+        }
+        else if (!passwordOnlyMatch) {
+            passwordOnlyMatch = record;
+        }
+    }
+    const bestMatch = fullBurnerMatch || passwordOnlyMatch;
+    if (!bestMatch) {
+        return null;
+    }
+    const password = fieldChunksToString([bestMatch.passwordPart]);
+    if (!password) {
+        return null;
+    }
+    if (fullBurnerMatch) {
+        const encryptedBurnerKey = fieldChunksToString(fullBurnerMatch.pkParts);
+        return {
+            password,
+            burnerAddress: fullBurnerMatch.burnerAddress,
+            encryptedBurnerKey: encryptedBurnerKey || undefined,
+            source: 'full_burner',
+        };
+    }
+    return {
+        password,
+        source: 'password_only',
+    };
+}
 async function fetchOwnedInvoiceRecordByHash(privateKey, invoiceHash) {
     const normalized = normalizeInvoiceHash(invoiceHash);
     const records = await fetchOwnedInvoiceRecords(privateKey);

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 = "https://nullpay-backend-ib5q4.ondigitalocean.app/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 = 'https://nullpay-backend-ib5q4.ondigitalocean.app/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;