@nullpay/mcp 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+export type WalletPreference = 'main' | 'burner';
+export type InvoiceType = 'standard' | 'multipay' | 'donation';
+export type Currency = 'CREDITS' | 'USDCX' | 'USAD' | 'ANY';
+export interface UserProfile {
+    address_hash: string;
+    main_address?: string | null;
+    burner_address?: string | null;
+    encrypted_burner_key?: string | null;
+    profile_main_invoice_hash?: string | null;
+    profile_burner_invoice_hash?: string | null;
+    updated_at?: string;
+}
+export interface InvoiceRecord {
+    invoice_hash: string;
+    merchant_address?: string | null;
+    designated_address?: string | null;
+    merchant_address_hash?: string | null;
+    is_burner?: boolean;
+    payer_address?: string | null;
+    amount?: number | null;
+    amount_micro?: number | null;
+    memo?: string | null;
+    status: 'PENDING' | 'SETTLED';
+    block_height?: number | null;
+    block_settled?: number | null;
+    invoice_transaction_id?: string | null;
+    payment_tx_ids?: string[] | null;
+    created_at?: string;
+    updated_at?: string;
+    salt?: string | null;
+    invoice_type?: number | null;
+    token_type?: number | null;
+    invoice_items?: Array<{
+        name: string;
+        quantity: number;
+        unitPrice: number;
+        total: number;
+    }> | null;
+    for_sdk?: boolean;
+}
+export interface SessionState {
+    address: string;
+    addressHash: string;
+    password: string;
+    activeWallet: WalletPreference;
+    encryptedMainAddress: string;
+    encryptedBurnerAddress?: string | null;
+    encryptedBurnerKey?: string | null;
+    mainPrivateKey?: string | null;
+    hasMainPrivateKeyInEnv?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LoginArgs {
+    address?: string;
+    password?: string;
+    main_private_key?: string;
+    create_burner_wallet?: boolean;
+    wallet_preference?: WalletPreference;
+}
+export interface CreateInvoiceArgs {
+    amount: number;
+    currency?: Currency;
+    memo?: string;
+    invoice_type?: InvoiceType;
+    wallet?: WalletPreference;
+    line_items?: Array<{
+        name: string;
+        quantity: number;
+        unitPrice: number;
+        total: number;
+    }>;
+}
+export interface PayInvoiceArgs {
+    payment_link?: string;
+    invoice_hash?: string;
+    wallet?: WalletPreference;
+    amount?: number;
+    currency?: Exclude<Currency, 'ANY'>;
+    session_id?: string;
+}
+export interface GetTransactionInfoArgs {
+    invoice_hash?: string;
+    wallet?: WalletPreference;
+    limit?: number;
+}
+export interface InvoiceStatusData {
+    status: number;
+    tokenType: number;
+    invoiceType: number;
+}
+export interface ParsedOwnedInvoiceRecord {
+    owner: string;
+    invoiceHash: string;
+    amountMicro: number;
+    tokenType: number;
+    invoiceType: number;
+    salt: string;
+    memo: string;
+    walletType: number;
+    plaintext: string;
+}
+export interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/crypto.d.ts

@@ -0,0 +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>;

package/dist/utils/crypto.js

@@ -0,0 +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');
+    }
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,6 @@
+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

@@ -0,0 +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')
+    };
+}

package/dist/utils/esm.d.ts

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

package/dist/utils/esm.js

@@ -0,0 +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);
+}

package/dist/utils/formatters.d.ts

@@ -0,0 +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;

package/dist/utils/formatters.js

@@ -0,0 +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)';
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "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"
+  }
+}