@nullpay/mcp 1.0.0

package/dist/backend-client.js

@@ -0,0 +1,93 @@
+"use strict";
+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) {
+        this.baseUrl = baseUrl;
+        this.mcpSecret = mcpSecret;
+    }
+    buildUrl(path) {
+        return `${this.baseUrl.replace(/\/+$/, '')}${path}`;
+    }
+    async request(path, init) {
+        const response = await fetch(this.buildUrl(path), init);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(mapBackendError(path, text || `Backend request failed: ${response.status}`));
+        }
+        return await response.json();
+    }
+    async getUserProfile(addressHash) {
+        const response = await fetch(this.buildUrl(`/users/profile/${addressHash}`));
+        if (response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to fetch user profile: ${response.status}`);
+        }
+        return await response.json();
+    }
+    async upsertUserProfile(body) {
+        return await this.request('/users/profile', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async createInvoiceRow(body) {
+        return await this.request('/invoices', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async updateInvoice(hash, body) {
+        return await this.request(`/invoices/${hash}`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async updateCheckoutSession(id, body) {
+        return await this.request(`/checkout/sessions/${id}`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async getInvoice(hash) {
+        return await this.request(`/invoice/${hash}`);
+    }
+    async getMerchantInvoices(merchantHash) {
+        return await this.request(`/invoices/merchant/${merchantHash}`);
+    }
+    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 } : {})
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    async sponsorExecution(body) {
+        return await this.request('/dps/sponsor-sweep', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+}
+exports.NullPayBackendClient = NullPayBackendClient;

package/dist/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/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/esm.d.ts

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

package/dist/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/protocol.d.ts

@@ -0,0 +1,19 @@
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: JsonRpcId;
+    method: string;
+    params?: Record<string, any>;
+}
+export declare class StdioJsonRpcServer {
+    private readonly onRequest;
+    private buffer;
+    constructor(onRequest: (request: JsonRpcRequest) => Promise<unknown>);
+    start(): void;
+    private processBuffer;
+    private tryReadFramedMessage;
+    private tryReadPlainJsonMessage;
+    private handleMessage;
+    send(payload: unknown): void;
+}
+export {};

package/dist/protocol.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StdioJsonRpcServer = void 0;
+class StdioJsonRpcServer {
+    constructor(onRequest) {
+        this.onRequest = onRequest;
+        this.buffer = '';
+    }
+    start() {
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            this.buffer += chunk;
+            this.processBuffer().catch((error) => {
+                console.error('[nullpay-mcp] transport error', error instanceof Error ? error.message : String(error));
+                this.send({
+                    jsonrpc: '2.0',
+                    error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+                    id: null,
+                });
+            });
+        });
+    }
+    async processBuffer() {
+        while (true) {
+            const framed = this.tryReadFramedMessage();
+            if (framed !== null) {
+                const request = JSON.parse(framed);
+                console.error('[nullpay-mcp] parsed framed request', request.method, request.id);
+                await this.handleMessage(request);
+                continue;
+            }
+            const plain = this.tryReadPlainJsonMessage();
+            if (plain !== null) {
+                const request = JSON.parse(plain);
+                console.error('[nullpay-mcp] parsed plain request', request.method, request.id);
+                await this.handleMessage(request);
+                continue;
+            }
+            return;
+        }
+    }
+    tryReadFramedMessage() {
+        let headerEnd = this.buffer.indexOf('\r\n\r\n');
+        let headerLength = 4;
+        if (headerEnd === -1) {
+            headerEnd = this.buffer.indexOf('\n\n');
+            headerLength = 2;
+        }
+        if (headerEnd === -1) {
+            return null;
+        }
+        const header = this.buffer.slice(0, headerEnd);
+        const contentLengthHeader = header
+            .split(/\r?\n/)
+            .find((line) => line.toLowerCase().startsWith('content-length:'));
+        if (!contentLengthHeader) {
+            return null;
+        }
+        const contentLength = Number(contentLengthHeader.split(':')[1].trim());
+        const messageStart = headerEnd + headerLength;
+        const messageEnd = messageStart + contentLength;
+        if (this.buffer.length < messageEnd) {
+            return null;
+        }
+        const message = this.buffer.slice(messageStart, messageEnd);
+        this.buffer = this.buffer.slice(messageEnd);
+        return message;
+    }
+    tryReadPlainJsonMessage() {
+        const trimmed = this.buffer.trim();
+        if (!trimmed.startsWith('{')) {
+            return null;
+        }
+        try {
+            JSON.parse(trimmed);
+            this.buffer = '';
+            return trimmed;
+        }
+        catch {
+            const newlineIndex = this.buffer.indexOf('\n');
+            if (newlineIndex === -1) {
+                return null;
+            }
+            const candidate = this.buffer.slice(0, newlineIndex).trim();
+            if (!candidate.startsWith('{')) {
+                this.buffer = this.buffer.slice(newlineIndex + 1);
+                return null;
+            }
+            JSON.parse(candidate);
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            return candidate;
+        }
+    }
+    async handleMessage(request) {
+        if (request.id === undefined || request.id === null) {
+            await this.onRequest(request);
+            return;
+        }
+        try {
+            const result = await this.onRequest(request);
+            console.error('[nullpay-mcp] sending response', request.method, request.id);
+            this.send({ jsonrpc: '2.0', id: request.id, result });
+        }
+        catch (error) {
+            console.error('[nullpay-mcp] request handler failed', request.method, request.id, error instanceof Error ? error.message : String(error));
+            this.send({
+                jsonrpc: '2.0',
+                id: request.id,
+                error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+            });
+        }
+    }
+    send(payload) {
+        const body = JSON.stringify(payload);
+        const safeWrite = globalThis.__nullpayMcpStdoutWrite
+            || ((chunk) => process.stdout.write(chunk));
+        safeWrite(body + '\n');
+    }
+}
+exports.StdioJsonRpcServer = StdioJsonRpcServer;

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,111 @@
+"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"));
+const backend_client_1 = require("./backend-client");
+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);
+    process.stdout.write = ((chunk, encoding, callback) => {
+        const text = typeof chunk === 'string'
+            ? chunk
+            : Buffer.isBuffer(chunk)
+                ? chunk.toString('utf8')
+                : String(chunk);
+        process.stderr.write(text);
+        if (typeof encoding === 'function') {
+            encoding();
+        }
+        else if (typeof callback === 'function') {
+            callback();
+        }
+        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') {
+        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();

package/dist/service.d.ts

@@ -0,0 +1,179 @@
+import { NullPayBackendClient } from './backend-client';
+import { SessionStore } from './session-store';
+import { ToolResult } from './types';
+export declare class NullPayMcpService {
+    private readonly backend;
+    private readonly sessions;
+    private readonly publicBaseUrl;
+    constructor(backend: NullPayBackendClient, sessions: SessionStore, publicBaseUrl: string);
+    listTools(): ({
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                address: {
+                    type: string;
+                    description: string;
+                };
+                password: {
+                    type: string;
+                    description: string;
+                };
+                main_private_key: {
+                    type: string;
+                    description: string;
+                };
+                create_burner_wallet: {
+                    type: string;
+                    description: string;
+                };
+                wallet_preference: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                amount?: undefined;
+                currency?: undefined;
+                memo?: undefined;
+                invoice_type?: undefined;
+                wallet?: undefined;
+                line_items?: undefined;
+                payment_link?: undefined;
+                invoice_hash?: undefined;
+                session_id?: undefined;
+                limit?: undefined;
+            };
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                amount: {
+                    type: string;
+                    description?: undefined;
+                };
+                currency: {
+                    type: string;
+                    enum: string[];
+                    description?: undefined;
+                };
+                memo: {
+                    type: string;
+                };
+                invoice_type: {
+                    type: string;
+                    enum: string[];
+                };
+                wallet: {
+                    type: string;
+                    enum: string[];
+                };
+                line_items: {
+                    type: string;
+                };
+                address?: undefined;
+                password?: undefined;
+                main_private_key?: undefined;
+                create_burner_wallet?: undefined;
+                wallet_preference?: undefined;
+                payment_link?: undefined;
+                invoice_hash?: undefined;
+                session_id?: undefined;
+                limit?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                payment_link: {
+                    type: string;
+                    description: string;
+                };
+                invoice_hash: {
+                    type: string;
+                    description: string;
+                };
+                wallet: {
+                    type: string;
+                    enum: string[];
+                };
+                amount: {
+                    type: string;
+                    description: string;
+                };
+                currency: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                session_id: {
+                    type: string;
+                    description: string;
+                };
+                address?: undefined;
+                password?: undefined;
+                main_private_key?: undefined;
+                create_burner_wallet?: undefined;
+                wallet_preference?: undefined;
+                memo?: undefined;
+                invoice_type?: undefined;
+                line_items?: undefined;
+                limit?: undefined;
+            };
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                invoice_hash: {
+                    type: string;
+                    description?: undefined;
+                };
+                wallet: {
+                    type: string;
+                    enum: string[];
+                };
+                limit: {
+                    type: string;
+                };
+                address?: undefined;
+                password?: undefined;
+                main_private_key?: undefined;
+                create_burner_wallet?: undefined;
+                wallet_preference?: undefined;
+                amount?: undefined;
+                currency?: undefined;
+                memo?: undefined;
+                invoice_type?: undefined;
+                line_items?: undefined;
+                payment_link?: undefined;
+                session_id?: undefined;
+            };
+            required?: undefined;
+        };
+    })[];
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    private login;
+    private createInvoice;
+    private payInvoice;
+    private getTransactionInfo;
+    private resolveWallet;
+    private resolveWalletAddress;
+    private resolveWalletPrivateKey;
+    private resolveWalletPrivateKeyOptional;
+    private resolveInvoiceLookupPrivateKey;
+    private resolvePayInvoiceContext;
+    private enrichInvoiceIfPossible;
+    private getEnrichedInvoice;
+}