LDK MCP Server

Instructions

Implementation Reference

• src/tools/listPayments.ts:25-290 (handler)

  Main tool handler: fetches payments via LightningService, filters by status/limit, formats output as JSON with SwiftUI example.

    execute: async (args: any): Promise<ToolResult> => {
      try {
        let payments = await lightningService.listPayments();
        
        // Filter by status
        if (args.status && args.status !== 'all') {
          payments = payments.filter(p => p.status === args.status);
        }
        
        // Limit results
        if (args.limit) {
          payments = payments.slice(0, args.limit);
        }
  
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              success: true,
              count: payments.length,
              payments: payments.map(p => ({
                paymentHash: p.paymentHash,
                paymentPreimage: p.paymentPreimage,
                amountSats: Math.floor(p.amountMsat / 1000),
                feeSats: p.feeMsat ? Math.floor(p.feeMsat / 1000) : 0,
                status: p.status,
                timestamp: p.timestamp,
                description: p.description
              })),
              swiftExample: `
  // Swift code to display payment history in your iOS app
  import SwiftUI
  import LightningDevKit
  
  struct PaymentHistoryView: View {
      @State private var payments: [PaymentRecord] = []
      @State private var isLoading = true
      @State private var selectedFilter: PaymentFilter = .all
      
      enum PaymentFilter: String, CaseIterable {
          case all = "All"
          case sent = "Sent"
          case received = "Received"
          case pending = "Pending"
          case failed = "Failed"
      }
      
      var filteredPayments: [PaymentRecord] {
          switch selectedFilter {
          case .all:
              return payments
          case .sent:
              return payments.filter { $0.direction == .outbound && $0.status == .succeeded }
          case .received:
              return payments.filter { $0.direction == .inbound && $0.status == .succeeded }
          case .pending:
              return payments.filter { $0.status == .pending }
          case .failed:
              return payments.filter { $0.status == .failed }
          }
      }
      
      var body: some View {
          VStack(spacing: 0) {
              // Filter picker
              Picker("Filter", selection: $selectedFilter) {
                  ForEach(PaymentFilter.allCases, id: \\.self) { filter in
                      Text(filter.rawValue).tag(filter)
                  }
              }
              .pickerStyle(SegmentedPickerStyle())
              .padding()
              
              // Payment list
              if filteredPayments.isEmpty && !isLoading {
                  ContentUnavailableView(
                      "No Payments",
                      systemImage: "bolt.slash",
                      description: Text("Your payment history will appear here")
                  )
              } else {
                  List(filteredPayments) { payment in
                      PaymentRow(payment: payment)
                          .listRowInsets(EdgeInsets(top: 8, leading: 16, bottom: 8, trailing: 16))
                  }
                  .listStyle(PlainListStyle())
              }
          }
          .navigationTitle("Payment History")
          .task {
              await loadPayments()
          }
          .refreshable {
              await loadPayments()
          }
          .overlay {
              if isLoading {
                  ProgressView()
              }
          }
      }
      
      func loadPayments() async {
          isLoading = true
          defer { isLoading = false }
          
          payments = await LDKManager.shared.getPaymentHistory()
      }
  }
  
  struct PaymentRow: View {
      let payment: PaymentRecord
      
      var body: some View {
          HStack(spacing: 12) {
              // Direction icon
              Image(systemName: payment.direction == .inbound ? "arrow.down.circle.fill" : "arrow.up.circle.fill")
                  .font(.title2)
                  .foregroundColor(payment.direction == .inbound ? .green : .blue)
              
              // Payment details
              VStack(alignment: .leading, spacing: 4) {
                  HStack {
                      Text(payment.description ?? "Lightning Payment")
                          .font(.body)
                          .lineLimit(1)
                      
                      Spacer()
                      
                      // Amount
                      Text("\\(payment.direction == .inbound ? "+" : "-")\\(payment.amountSats)")
                          .font(.callout)
                          .fontWeight(.medium)
                          .foregroundColor(payment.direction == .inbound ? .green : .primary)
                  }
                  
                  HStack {
                      // Status
                      Label(payment.status.displayText, systemImage: payment.status.icon)
                          .font(.caption)
                          .foregroundColor(payment.status.color)
                      
                      Spacer()
                      
                      // Time
                      Text(formatTime(payment.timestamp))
                          .font(.caption)
                          .foregroundColor(.secondary)
                  }
              }
          }
          .padding(.vertical, 4)
      }
      
      func formatTime(_ timestamp: Int64) -> String {
          let date = Date(timeIntervalSince1970: Double(timestamp / 1000))
          let formatter = RelativeDateTimeFormatter()
          formatter.unitsStyle = .abbreviated
          return formatter.localizedString(for: date, relativeTo: Date())
      }
  }
  
  // Payment record model
  struct PaymentRecord: Identifiable {
      let id: String
      let paymentHash: String
      let paymentPreimage: String?
      let amountSats: Int
      let feeSats: Int
      let status: PaymentStatus
      let direction: PaymentDirection
      let timestamp: Int64
      let description: String?
      
      enum PaymentDirection {
          case inbound
          case outbound
      }
      
      enum PaymentStatus {
          case pending
          case succeeded
          case failed
          
          var displayText: String {
              switch self {
              case .pending: return "Pending"
              case .succeeded: return "Completed"
              case .failed: return "Failed"
              }
          }
          
          var icon: String {
              switch self {
              case .pending: return "clock"
              case .succeeded: return "checkmark.circle"
              case .failed: return "xmark.circle"
              }
          }
          
          var color: Color {
              switch self {
              case .pending: return .orange
              case .succeeded: return .green
              case .failed: return .red
              }
          }
      }
  }
  
  // Extension to fetch payment history
  extension LDKManager {
      func getPaymentHistory() async -> [PaymentRecord] {
          // Fetch from event store or database
          var records: [PaymentRecord] = []
          
          // Get recent payments from channel manager events
          let recentPayments = getRecentPaymentEvents()
          
          for event in recentPayments {
              if let sent = event as? PaymentSent {
                  records.append(PaymentRecord(
                      id: sent.paymentHash.toHex(),
                      paymentHash: sent.paymentHash.toHex(),
                      paymentPreimage: sent.paymentPreimage.toHex(),
                      amountSats: Int(sent.amountMsat / 1000),
                      feeSats: Int((sent.feePaidMsat ?? 0) / 1000),
                      status: .succeeded,
                      direction: .outbound,
                      timestamp: Int64(Date().timeIntervalSince1970 * 1000),
                      description: nil
                  ))
              } else if let received = event as? PaymentReceived {
                  records.append(PaymentRecord(
                      id: received.paymentHash.toHex(),
                      paymentHash: received.paymentHash.toHex(),
                      paymentPreimage: nil,
                      amountSats: Int(received.amountMsat / 1000),
                      feeSats: 0,
                      status: .succeeded,
                      direction: .inbound,
                      timestamp: Int64(Date().timeIntervalSince1970 * 1000),
                      description: received.purpose.description
                  ))
              }
          }
          
          return records.sorted { $0.timestamp > $1.timestamp }
      }
  }`.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/tools/listPayments.ts:9-24 (schema)

  Input schema for tool parameters: limit (number, default 10) and status (enum: all/pending/succeeded/failed, default all).

  inputSchema: {
    type: 'object',
    properties: {
      limit: {
        type: 'number',
        description: 'Maximum number of payments to return',
        default: 10
      },
      status: {
        type: 'string',
        enum: ['all', 'pending', 'succeeded', 'failed'],
        description: 'Filter by payment status',
        default: 'all'
      }
    }
  },

• src/index.ts:26-26 (registration)

  Import statement for listPaymentsTool.

  import { listPaymentsTool } from './tools/listPayments.js';

• src/index.ts:52-52 (registration)

  Registration of listPaymentsTool in the tools array used by MCP server.

  listPaymentsTool,

• src/services/lightningService.ts:210-212 (helper)

  Helper method in LightningService that provides the list of payments (mock in-memory implementation).

  async listPayments(): Promise<Payment[]> {
    return Array.from(this.payments.values()).sort((a, b) => b.timestamp - a.timestamp);
  }