LDK MCP Server

Instructions

Implementation Reference

• src/tools/getBalance.ts:6-252 (handler)

  The complete tool handler implementation for 'ldk_get_balance'. Defines the tool object with schema, description, and execute function that fetches balance data from LightningService, calculates inbound liquidity from channels, formats the response as JSON including sats conversions and a comprehensive SwiftUI example for iOS balance display.

  export const getBalanceTool: Tool = {
    name: 'ldk_get_balance',
    description: 'Get Lightning wallet balance and channel liquidity',
    inputSchema: {
      type: 'object',
      properties: {}
    },
    execute: async (args: any): Promise<ToolResult> => {
      try {
        const balance = await lightningService.getBalance();
        const channels = await lightningService.getChannelStatus();
        
        // Calculate inbound liquidity
        let inboundMsat = 0;
        for (const channel of channels) {
          if (channel.isUsable) {
            inboundMsat += channel.remoteBalanceMsat;
          }
        }
  
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              success: true,
              balance: {
                totalSats: Math.floor(balance.totalMsat / 1000),
                spendableSats: Math.floor(balance.spendableMsat / 1000),
                inboundSats: Math.floor(inboundMsat / 1000)
              },
              liquidity: {
                canSendMaxSats: Math.floor(balance.spendableMsat / 1000),
                canReceiveMaxSats: Math.floor(inboundMsat / 1000)
              },
              swiftExample: `
  // Swift code to display balance in your iOS app
  import SwiftUI
  import LightningDevKit
  
  struct BalanceView: View {
      @State private var balance: WalletBalance?
      @State private var isLoading = true
      
      var body: some View {
          VStack(spacing: 24) {
              // Total balance card
              VStack(spacing: 16) {
                  HStack {
                      Image(systemName: "bitcoinsign.circle.fill")
                          .font(.largeTitle)
                          .foregroundColor(.orange)
                      
                      Spacer()
                      
                      VStack(alignment: .trailing) {
                          Text(formatSats(balance?.totalSats ?? 0))
                              .font(.system(size: 32, weight: .bold, design: .rounded))
                          Text("sats")
                              .font(.caption)
                              .foregroundColor(.secondary)
                      }
                  }
                  
                  // Balance breakdown
                  VStack(spacing: 8) {
                      BalanceDetailRow(
                          label: "Spendable",
                          amount: balance?.spendableSats ?? 0,
                          icon: "paperplane.fill",
                          color: .green
                      )
                      
                      BalanceDetailRow(
                          label: "Receivable",
                          amount: balance?.inboundSats ?? 0,
                          icon: "arrow.down.circle.fill",
                          color: .blue
                      )
                  }
              }
              .padding()
              .background(
                  LinearGradient(
                      colors: [Color.orange.opacity(0.1), Color.orange.opacity(0.05)],
                      startPoint: .topLeading,
                      endPoint: .bottomTrailing
                  )
              )
              .cornerRadius(16)
              
              // Quick actions
              HStack(spacing: 16) {
                  QuickActionButton(
                      title: "Send",
                      icon: "paperplane.fill",
                      color: .green,
                      isEnabled: (balance?.spendableSats ?? 0) > 0
                  ) {
                      // Navigate to send view
                  }
                  
                  QuickActionButton(
                      title: "Receive",
                      icon: "qrcode",
                      color: .blue,
                      isEnabled: (balance?.inboundSats ?? 0) > 0
                  ) {
                      // Navigate to receive view
                  }
              }
              
              Spacer()
          }
          .padding()
          .navigationTitle("Balance")
          .task {
              await loadBalance()
          }
          .refreshable {
              await loadBalance()
          }
          .overlay {
              if isLoading {
                  ProgressView()
              }
          }
      }
      
      func loadBalance() async {
          isLoading = true
          defer { isLoading = false }
          
          balance = await LDKManager.shared.getBalance()
      }
      
      func formatSats(_ sats: Int64) -> String {
          let formatter = NumberFormatter()
          formatter.numberStyle = .decimal
          formatter.groupingSeparator = ","
          return formatter.string(from: NSNumber(value: sats)) ?? "0"
      }
  }
  
  struct BalanceDetailRow: View {
      let label: String
      let amount: Int64
      let icon: String
      let color: Color
      
      var body: some View {
          HStack {
              Label(label, systemImage: icon)
                  .foregroundColor(color)
                  .font(.callout)
              
              Spacer()
              
              Text(formatAmount(amount))
                  .font(.callout)
                  .fontWeight(.medium)
                  .foregroundColor(.secondary)
          }
      }
      
      func formatAmount(_ sats: Int64) -> String {
          let formatter = NumberFormatter()
          formatter.numberStyle = .decimal
          formatter.groupingSeparator = ","
          return (formatter.string(from: NSNumber(value: sats)) ?? "0") + " sats"
      }
  }
  
  struct QuickActionButton: View {
      let title: String
      let icon: String
      let color: Color
      let isEnabled: Bool
      let action: () -> Void
      
      var body: some View {
          Button(action: action) {
              VStack(spacing: 8) {
                  Image(systemName: icon)
                      .font(.title2)
                  Text(title)
                      .font(.caption)
              }
              .frame(maxWidth: .infinity)
              .padding()
              .background(color.opacity(isEnabled ? 0.15 : 0.05))
              .foregroundColor(isEnabled ? color : .gray)
              .cornerRadius(12)
          }
          .disabled(!isEnabled)
      }
  }
  
  // Extension for LDK balance fetching
  extension LDKManager {
      func getBalance() async -> WalletBalance {
          let channels = channelManager.listChannels()
          
          var totalMsat: UInt64 = 0
          var spendableMsat: UInt64 = 0
          var inboundMsat: UInt64 = 0
          
          for channel in channels {
              if channel.isUsable {
                  let localBalance = channel.balanceMsat
                  let remoteBalance = (channel.channelValueSatoshis * 1000) - localBalance
                  
                  totalMsat += localBalance
                  spendableMsat += max(0, localBalance - (channel.channelValueSatoshis * 10)) // Reserve 1%
                  inboundMsat += remoteBalance
              }
          }
          
          return WalletBalance(
              totalSats: Int64(totalMsat / 1000),
              spendableSats: Int64(spendableMsat / 1000),
              inboundSats: Int64(inboundMsat / 1000)
          )
      }
  }
  
  struct WalletBalance {
      let totalSats: Int64
      let spendableSats: Int64
      let inboundSats: Int64
  }`.trim()
            }, null, 2)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              success: false,
              error: error instanceof Error ? error.message : 'Unknown error'
            }, null, 2)
          }],
          isError: true
        };
      }
    }
  };

• src/index.ts:24-62 (registration)

  Tool registration in the main MCP server index file. Imports getBalanceTool and includes it in the tools array used for listing and executing tools via MCP handlers.

  import { getBalanceTool } from './tools/getBalance.js';
  import { decodeInvoiceTool } from './tools/decodeInvoice.js';
  import { listPaymentsTool } from './tools/listPayments.js';
  import { estimateFeeTool } from './tools/estimateFee.js';
  import { generateMnemonicTool } from './tools/generateMnemonic.js';
  import { deriveAddressTool } from './tools/deriveAddress.js';
  import { getSwiftCodeTool } from './tools/getSwiftCode.js';
  import { getArchitectureTool } from './tools/getArchitecture.js';
  import { testScenarioTool } from './tools/testScenario.js';
  import { networkGraphTool } from './tools/networkGraph.js';
  import { eventHandlingTool } from './tools/eventHandling.js';
  import { chainSyncTool } from './tools/chainSync.js';
  
  // Aggregate all tools
  const tools = [
    generateInvoiceTool,
    payInvoiceTool,
    getChannelStatusTool,
    getNodeInfoTool,
    backupStateTool,
    keychainTestTool,
    backgroundTestTool,
    pushNotificationTool,
    biometricAuthTool,
    createChannelTool,
    closeChannelTool,
    getBalanceTool,
    decodeInvoiceTool,
    listPaymentsTool,
    estimateFeeTool,
    generateMnemonicTool,
    deriveAddressTool,
    getSwiftCodeTool,
    getArchitectureTool,
    testScenarioTool,
    networkGraphTool,
    eventHandlingTool,
    chainSyncTool,
  ];

• src/tools/getBalance.ts:9-12 (schema)

  Input schema definition for the ldk_get_balance tool, specifying an empty object (no required parameters).

  inputSchema: {
    type: 'object',
    properties: {}
  },