lightning-wallet-mcp 1.3.2 → 1.4.1

package/README.md

@@ -2,10 +2,24 @@
 
 [![npm version](https://img.shields.io/npm/v/lightning-wallet-mcp.svg)](https://www.npmjs.com/package/lightning-wallet-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![lightning-wallet-mcp MCP server](https://glama.ai/mcp/servers/lightningfaucet/lightning-wallet-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lightningfaucet/lightning-wallet-mcp)
+[![Glama MCP Server](https://img.shields.io/badge/glama.ai-MCP%20server-1ee495?logo=githubsponsors&logoColor=1ee495&labelColor=0a0a0a)](https://glama.ai/mcp/servers/lightningfaucet/lightning-wallet-mcp)
 
 **Give your AI agent a Bitcoin wallet.** MCP server + CLI. Works with Claude Code, OpenClaw, Cursor, and any agent framework.
 
+## What's New in v1.4
+
+- **`update_operator` tool / `lw set-email`** - set your operator email from the MCP client or CLI; a verification link is emailed to you.
+- **`claim_promo` tool / `lw claim-promo`** - claim the free-sats install promo directly from your agent. Requirements: verified email + operator account at least 3 hours old.
+- **`get_info` works before registration** - service info no longer requires an API key.
+
+### Free 100 sats for new operators
+
+1. `lw register --email you@example.com` (or the `register_operator` MCP tool with an email)
+2. Click the verification link we email you
+3. After your account is 3 hours old: `lw claim-promo` (or the `claim_promo` MCP tool)
+
+One bonus per operator, first 100 installs only, no deposit required.
+
 ## What's New in v1.3
 
 **v1.3.0** - L402 protocol v0 support per the latest Lightning Labs spec.
@@ -159,6 +173,9 @@ Then ask Claude: *"Register a new Lightning Wallet operator account"*
 | `withdraw` | Withdraw funds to external Lightning destination |
 | `set_operator_key` | Switch to operator credentials |
 
+- `update_operator` - set operator email (sends verification link) and/or name
+- `claim_promo` - claim the free-sats install promo (verified email + 3h account)
+
 ### Agent Management
 
 | Tool | Description |

package/dist/cli.js

@@ -10,7 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const lightning_faucet_js_1 = require("./lightning-faucet.js");
-const VERSION = '1.1.0';
+const VERSION = '1.4.0';
 // --- Helpers ---
 function getApiKey() {
     const key = process.env.LIGHTNING_WALLET_API_KEY;
@@ -256,9 +256,22 @@ async function cmdTransactions(flags) {
         has_more: result.has_more,
     };
 }
-async function cmdInfo() {
+async function cmdSetEmail(positional) {
+    const email = positional[0];
+    if (!email)
+        error('Usage: lw set-email <email>');
+    const client = getClient();
+    return client.updateOperator({ email });
+}
+async function cmdClaimPromo() {
     const client = getClient();
-    const result = await client.getInfo();
+    return client.claimPromo();
+}
+async function cmdInfo() {
+    // Service info is public - works with or without an API key
+    const result = process.env.LIGHTNING_WALLET_API_KEY
+        ? await getClient().getInfo()
+        : await (0, lightning_faucet_js_1.getPublicInfo)();
     return {
         version: result.version,
         api_version: result.apiVersion,
@@ -316,6 +329,9 @@ COMMANDS
   list-agents | agents             List all agents
 
   transactions                    Recent transactions [--limit 10] [--offset 0]
+  set-email <email>               Set operator email (verification link emailed)
+  claim-promo                     Claim the 100-sat install promo
+                                    (requires verified email + 3h account age)
   help                            Show this help
 
 WEBHOOKS
@@ -404,6 +420,12 @@ async function main() {
             case 'transactions':
                 result = await cmdTransactions(flags);
                 break;
+            case 'set-email':
+                result = await cmdSetEmail(positional);
+                break;
+            case 'claim-promo':
+                result = await cmdClaimPromo();
+                break;
             case 'info':
                 result = await cmdInfo();
                 break;

package/dist/index.js

@@ -104,7 +104,7 @@ const GetTransactionsSchema = zod_1.z.object({
 // Operator management schemas
 const RegisterOperatorSchema = zod_1.z.object({
     name: zod_1.z.string().optional().describe('Name for the operator account'),
-    email: zod_1.z.string().email().optional().describe('Optional email for product updates and announcements'),
+    email: zod_1.z.string().email().optional().describe('Your email — register WITH it to claim the 100 free-sats install promo. A verification link is sent; once verified, claim_promo funds your wallet. Strongly recommended.'),
 });
 const GetDepositInvoiceSchema = zod_1.z.object({
     amount_sats: zod_1.z.number().int().min(100).max(10_000_000).describe('Amount in satoshis to deposit'),
@@ -119,6 +119,13 @@ const FundAgentSchema = zod_1.z.object({
     amount_sats: zod_1.z.number().int().min(1).max(10_000_000).describe('Amount in satoshis to transfer'),
 });
 const ListAgentsSchema = zod_1.z.object({});
+const UpdateOperatorSchema = zod_1.z.object({
+    email: zod_1.z.string().email().optional(),
+    name: zod_1.z.string().min(1).max(100).optional(),
+});
+const ClaimPromoSchema = zod_1.z.object({
+    promo_code: zod_1.z.string().optional(),
+});
 const SetOperatorKeySchema = zod_1.z.object({
     api_key: zod_1.z.string().min(10, 'API key is too short').max(200, 'API key is too long')
         .describe('The operator API key to use for subsequent requests'),
@@ -333,12 +340,35 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // Operator management tools
         {
             name: 'register_operator',
-            description: 'Register a new operator account. Returns API key and recovery code. SAVE THESE - they cannot be retrieved later!',
+            description: 'Register a new operator account. Returns API key and recovery code. SAVE THESE - they cannot be retrieved later! Tip: pass an email to claim the 100 free-sats install promo.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     name: { type: 'string', description: 'Name for the operator account (optional)' },
-                    email: { type: 'string', description: 'Email address — strongly recommended for onboarding tips, setup help, and product updates. Without it we cannot reach you if there are issues.' },
+                    email: { type: 'string', description: 'Email address — pass it here to claim the 100 free-sats install promo (a verification link is sent; once verified, and once the operator account is at least 3 hours old, call claim_promo to get funded). Also used for onboarding tips and important account notices.' },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'update_operator',
+            description: 'Update operator profile: set your email (sends a verification link - required for the free-sats promo) and/or display name. REQUIRES OPERATOR KEY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    email: { type: 'string', description: 'Email address to set. A verification link is emailed; click it to verify.' },
+                    name: { type: 'string', description: 'Display name for the operator account' },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'claim_promo',
+            description: 'Claim the free-sats install promo (100 sats, first 100 installs). Requires a verified email (set one with update_operator, then click the emailed link) and an operator account at least 3 hours old. REQUIRES OPERATOR KEY.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    promo_code: { type: 'string', description: "Promo code (default: 'first_100_installs')" },
                 },
                 required: [],
             },
@@ -943,6 +973,38 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'update_operator': {
+                const parsed = UpdateOperatorSchema.parse(args);
+                if (parsed.email === undefined && parsed.name === undefined) {
+                    throw new Error('Provide email and/or name to update.');
+                }
+                const result = await session.requireClient().updateOperator(parsed);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: result.success !== false,
+                                message: result.message || 'Operator updated',
+                                updated_fields: result.updated_fields,
+                                email_verification: result.email_verification,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'claim_promo': {
+                const parsed = ClaimPromoSchema.parse(args);
+                const result = await session.requireClient().claimPromo(parsed.promo_code);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'get_deposit_invoice': {
                 const parsed = GetDepositInvoiceSchema.parse(args);
                 const result = await session.requireClient().getDepositInvoice(parsed.amount_sats);
@@ -1263,7 +1325,15 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             // ==========================================
             case 'get_info': {
                 GetInfoSchema.parse(args);
-                const result = await session.requireClient().getInfo();
+                // Service info is public - fall back to an unauthenticated request so
+                // first-run users can check the service before registering.
+                let result;
+                try {
+                    result = await session.requireClient().getInfo();
+                }
+                catch {
+                    result = await (0, lightning_faucet_js_1.getPublicInfo)();
+                }
                 return {
                     content: [
                         {

package/dist/lightning-faucet.d.ts

@@ -513,10 +513,40 @@ export declare class LightningFaucetClient {
      * Vote on a post
      */
     boardVote(postId: number, direction: string): Promise<Record<string, unknown>>;
+    /**
+     * Update operator profile (email and/or name). Setting an email sends a
+     * verification link - a verified email is required for the free-sats promo.
+     */
+    updateOperator(opts: {
+        email?: string;
+        name?: string;
+    }): Promise<ApiResponse & {
+        message?: string;
+        updated_fields?: string[];
+        email_verification?: string;
+    }>;
+    /**
+     * Claim a promo bonus (default: the first_100_installs free-sats promo).
+     * Requires a verified email and an operator account at least 3 hours old.
+     */
+    claimPromo(promoCode?: string): Promise<ApiResponse & {
+        promo?: string;
+        bonus_sats?: number;
+        message?: string;
+    }>;
 }
 export declare function registerOperator(name?: string, email?: string): Promise<{
     operatorId: number;
     apiKey: string;
     recoveryCode: string;
 }>;
+export declare function getPublicInfo(): Promise<{
+    version: string;
+    apiVersion: string;
+    status: string;
+    maxPaymentSats: number;
+    minPaymentSats: number;
+    supportedFeatures: string[];
+    rawResponse: ApiResponse;
+}>;
 export {};

package/dist/lightning-faucet.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LightningFaucetClient = void 0;
 exports.registerOperator = registerOperator;
+exports.getPublicInfo = getPublicInfo;
 const API_BASE_URL = process.env.LIGHTNING_WALLET_API_URL || 'https://lightningfaucet.com/ai-agents/api';
 class LightningFaucetClient {
     apiKey;
@@ -774,6 +775,28 @@ class LightningFaucetClient {
             direction,
         });
     }
+    /**
+     * Update operator profile (email and/or name). Setting an email sends a
+     * verification link - a verified email is required for the free-sats promo.
+     */
+    async updateOperator(opts) {
+        const params = {};
+        if (opts.email !== undefined)
+            params.email = opts.email;
+        if (opts.name !== undefined)
+            params.name = opts.name;
+        return this.request('update_operator', params);
+    }
+    /**
+     * Claim a promo bonus (default: the first_100_installs free-sats promo).
+     * Requires a verified email and an operator account at least 3 hours old.
+     */
+    async claimPromo(promoCode) {
+        const params = {};
+        if (promoCode)
+            params.promo_code = promoCode;
+        return this.request('claim_promo', params);
+    }
 }
 exports.LightningFaucetClient = LightningFaucetClient;
 // Static method for registration (no API key needed)
@@ -808,3 +831,24 @@ async function registerOperator(name, email) {
         recoveryCode: result.recovery_code || '',
     };
 }
+// Public service info (no API key needed)
+async function getPublicInfo() {
+    const response = await fetch(API_BASE_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action: 'get_info' }),
+    });
+    if (!response.ok) {
+        throw new Error(`Request failed (HTTP ${response.status})`);
+    }
+    const result = (await response.json());
+    return {
+        version: result.version || '2.0.0',
+        apiVersion: result.api_version || '1.0',
+        status: result.status || 'operational',
+        maxPaymentSats: result.max_payment_sats || 1000000,
+        minPaymentSats: result.min_payment_sats || 1,
+        supportedFeatures: result.supported_features || ['l402', 'webhooks', 'lightning_address'],
+        rawResponse: result,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightning-wallet-mcp",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "mcpName": "io.github.lightningfaucet/lightning-wallet-mcp",
   "description": "Lightning wallet for AI agents. MCP server + CLI. Works with Claude Code, OpenClaw, Cursor, and any agent framework.",
   "main": "dist/index.js",