Lightning Enable MCP

Instructions

Implementation Reference

• python/lightning-enable-mcp/src/lightning_enable_mcp/tools/check_invoice_status.py:21-123 (handler)

  Implementation of the check_invoice_status tool handler which uses wallet instances (LND or Strike) to query invoice state.

  async def check_invoice_status(
      invoice_id: str,
      wallet: "Union[LndWallet, NWCWallet, OpenNodeWallet, StrikeWallet, None]" = None,
  ) -> str:
      """
      Check if a Lightning invoice has been paid.
  
      Use the invoice ID returned from create_invoice to check whether
      the invoice has been paid, is still pending, or has expired.
  
      Args:
          invoice_id: The invoice ID returned from create_invoice
          wallet: Wallet instance
  
      Returns:
          JSON with invoice status including whether it has been paid
      """
      if not invoice_id or not invoice_id.strip():
          return json.dumps({
              "success": False,
              "error": "Invoice ID is required"
          })
  
      if not wallet:
          return json.dumps({
              "success": False,
              "error": "Wallet not configured. Set LND_REST_HOST+LND_MACAROON_HEX, STRIKE_API_KEY, OPENNODE_API_KEY, or NWC_CONNECTION_STRING environment variable."
          })
  
      try:
          from ..lnd_wallet import LndWallet
          from ..strike_wallet import StrikeWallet
  
          if isinstance(wallet, LndWallet):
              # Use LND REST API to check invoice status
              status = await wallet.get_invoice_status(invoice_id.strip())
  
              if status["is_paid"]:
                  message = f"Invoice {invoice_id} has been PAID!"
              elif status["is_pending"]:
                  message = f"Invoice {invoice_id} is still pending payment."
              else:
                  message = f"Invoice {invoice_id} status: {status['state']}"
  
              return json.dumps({
                  "success": True,
                  "provider": "LND",
                  "invoice": {
                      "id": status["id"],
                      "state": status["state"],
                      "isPaid": status["is_paid"],
                      "isPending": status["is_pending"],
                      "amountSats": status["amount_sats"],
                      "settledAt": status.get("settled_at"),
                  },
                  "message": message,
              }, indent=2)
  
          elif isinstance(wallet, StrikeWallet):
              # Use Strike API to check invoice status
              payment = await wallet._request("GET", f"/invoices/{invoice_id}")
              state = payment.get("state", "UNKNOWN")
              amount = payment.get("amount", {})
              amount_value = amount.get("amount") if isinstance(amount, dict) else None
              paid_at = payment.get("paidAt")
  
              is_paid = state.upper() in ("PAID", "COMPLETED")
              is_pending = state.upper() in ("UNPAID", "PENDING")
  
              if is_paid:
                  message = f"Invoice {invoice_id} has been PAID!"
              elif is_pending:
                  message = f"Invoice {invoice_id} is still pending payment."
              else:
                  message = f"Invoice {invoice_id} status: {state}"
  
              return json.dumps({
                  "success": True,
                  "provider": "Strike",
                  "invoice": {
                      "id": invoice_id,
                      "state": state,
                      "isPaid": is_paid,
                      "isPending": is_pending,
                      "amount": amount_value,
                      "paidAt": paid_at,
                  },
                  "message": message,
              }, indent=2)
          else:
              provider_name = type(wallet).__name__.replace("Wallet", "")
              return json.dumps({
                  "success": False,
                  "error": f"Invoice status check is not supported with {provider_name} wallet.",
                  "hint": "Use LND (set LND_REST_HOST+LND_MACAROON_HEX) or Strike (set STRIKE_API_KEY) for invoice status checking."
              })
  
      except Exception as e:
          logger.exception("Error checking invoice status")
          return json.dumps({
              "success": False,
              "error": sanitize_error(str(e))
          })

• python/lightning-enable-mcp/src/lightning_enable_mcp/server.py:262-277 (registration)

  Tool definition and registration in the MCP server for 'check_invoice_status'.

      name="check_invoice_status",
      description=(
          "Check if a Lightning invoice has been paid. "
          "Use the invoice ID from create_invoice."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "invoice_id": {
                  "type": "string",
                  "description": "The invoice ID returned from create_invoice",
              },
          },
          "required": ["invoice_id"],
      },
  ),

• python/lightning-enable-mcp/src/lightning_enable_mcp/server.py:535-539 (handler)

  Tool invocation routing within the MCP server for 'check_invoice_status'.

  elif name == "check_invoice_status":
      result = await check_invoice_status(
          invoice_id=arguments.get("invoice_id", ""),
          wallet=self.wallet,
      )