Bitcoin MCP Server

Instructions

Implementation Reference

• src/server/tools.ts:199-231 (handler)

  The primary MCP tool handler for 'decode_invoice'. Validates the input args for a required 'invoice' string, delegates decoding to BitcoinService.decodeInvoice, formats the result into MCP TextContent response, and handles errors appropriately.

  export async function handleDecodeInvoice(
    bitcoinService: BitcoinService,
    args: unknown
  ) {
    if (
      !args ||
      typeof args !== "object" ||
      !("invoice" in args) ||
      typeof args.invoice !== "string"
    ) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Invalid parameters: invoice is required"
      );
    }
  
    try {
      const invoice = bitcoinService.decodeInvoice(args.invoice);
      return {
        content: [
          {
            type: "text",
            text: `Decoded Lightning invoice:\nNetwork: ${invoice.network}\nAmount: ${invoice.amount} satoshis\nDescription: ${invoice.description}\nExpiry: ${invoice.expiryDate}\nStatus: ${invoice.status}`,
          },
        ] as TextContent[],
      };
    } catch (error: any) {
      throw new McpError(
        ErrorCode.InternalError,
        error.message || "Failed to decode invoice"
      );
    }
  }

• src/server/base.ts:163-175 (registration)

  Registration of the 'decode_invoice' tool in the ListToolsRequestHandler. Defines the tool name, description, and input schema requiring a 'invoice' string parameter.

    name: "decode_invoice",
    description: "Decode a Lightning invoice",
    inputSchema: {
      type: "object",
      properties: {
        invoice: {
          type: "string",
          description: "BOLT11 Lightning invoice",
        },
      },
      required: ["invoice"],
    },
  } as Tool,

• src/server/base.ts:215-217 (registration)

  Dispatching logic in the CallToolRequestHandler switch statement that routes 'decode_invoice' calls to the handleDecodeInvoice function with BitcoinService instance.

  case "decode_invoice": {
    return handleDecodeInvoice(this.bitcoinService, args);
  }

• src/services/bitcoin.ts:278-295 (helper)

  BitcoinService.decodeInvoice method: Checks if LNBitsClient is configured, then delegates the actual BOLT11 decoding to LNBitsClient.toHumanFriendlyInvoice, with error handling and logging.

  decodeInvoice(bolt11: string): HumanFriendlyInvoice {
    if (!this.lnbitsClient) {
      throw new LightningError(
        "LNBits not configured. Please add lnbitsUrl, lnbitsAdminKey, and lnbitsReadKey to configuration.",
        LightningErrorCode.NOT_CONNECTED
      );
    }
  
    try {
      return this.lnbitsClient.toHumanFriendlyInvoice(bolt11);
    } catch (error) {
      logger.error({ error, bolt11 }, "Failed to decode invoice");
      throw new LightningError(
        "Failed to decode Lightning invoice",
        LightningErrorCode.PAYMENT_ERROR
      );
    }
  }

• src/clients/lnbits_clients.ts:58-78 (helper)

  LNBitsClient helper methods for decoding BOLT11 invoices. 'toHumanFriendlyInvoice' uses the 'bolt11-decoder' library to parse the invoice string, then 'humanFriendlyInvoice' extracts and formats key fields like network, amount, description, expiry, and status into HumanFriendlyInvoice.

  humanFriendlyInvoice(decoded: DecodedInvoice): HumanFriendlyInvoice {
    const network = decoded.prefix.startsWith("lnbc") ? "mainnet" : "testnet";
    const descriptionTag = decoded.tags.find(
      (t) => t.tagName === "description"
    );
    const description = descriptionTag
      ? String(descriptionTag.data)
      : "No description provided";
    return {
      network: network,
      amount: decoded.satoshis,
      description: description,
      expiryDate: new Date(decoded.timestamp * 1000).toLocaleString(),
      status: "VALID",
    };
  }
  
  toHumanFriendlyInvoice(bolt11Invoice: string): HumanFriendlyInvoice {
    const decoded = bolt11.decode(bolt11Invoice) as DecodedInvoice;
    return this.humanFriendlyInvoice(decoded);
  }