@lightninglabs/lightning-mcp-server 0.2.0

package/skills/aperture/scripts/setup.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Generate aperture configuration from template.
+#
+# Usage:
+#   setup.sh                                    # Defaults (mainnet, lnd)
+#   setup.sh --network testnet --insecure       # Testnet, no TLS
+#   setup.sh --no-auth                          # Disable L402 auth
+#   setup.sh --port 8081                        # Custom listen port
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+APERTURE_DIR="$HOME/.aperture"
+CONFIG_FILE="$APERTURE_DIR/aperture.yaml"
+NETWORK="mainnet"
+PORT="8081"
+INSECURE=false
+NO_AUTH=false
+LND_HOST="localhost:10009"
+LND_TLS="$HOME/.lnd/tls.cert"
+LND_MACDIR=""
+SERVICE_PORT="8080"
+SERVICE_PRICE="100"
+
+# Parse arguments.
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --network)
+            NETWORK="$2"
+            shift 2
+            ;;
+        --port)
+            PORT="$2"
+            shift 2
+            ;;
+        --insecure)
+            INSECURE=true
+            shift
+            ;;
+        --no-auth)
+            NO_AUTH=true
+            shift
+            ;;
+        --lnd-host)
+            LND_HOST="$2"
+            shift 2
+            ;;
+        --lnd-tls)
+            LND_TLS="$2"
+            shift 2
+            ;;
+        --lnd-macdir)
+            LND_MACDIR="$2"
+            shift 2
+            ;;
+        --service-port)
+            SERVICE_PORT="$2"
+            shift 2
+            ;;
+        --service-price)
+            SERVICE_PRICE="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: setup.sh [options]"
+            echo ""
+            echo "Generate aperture configuration."
+            echo ""
+            echo "Options:"
+            echo "  --network NETWORK        Bitcoin network (default: mainnet)"
+            echo "  --port PORT              Listen port (default: 8081)"
+            echo "  --insecure               Disable TLS"
+            echo "  --no-auth                Disable L402 authentication"
+            echo "  --lnd-host HOST          lnd gRPC host (default: localhost:10009)"
+            echo "  --lnd-tls PATH           lnd TLS cert path"
+            echo "  --lnd-macdir PATH        lnd macaroon directory"
+            echo "  --service-port PORT      Backend service port (default: 8080)"
+            echo "  --service-price SATS     Price per request in sats (default: 100)"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Auto-detect lnd macaroon directory if not specified.
+if [ -z "$LND_MACDIR" ]; then
+    LND_MACDIR="$HOME/.lnd/data/chain/bitcoin/$NETWORK"
+fi
+
+echo "=== Aperture Configuration Setup ==="
+echo ""
+echo "Network:      $NETWORK"
+echo "Listen port:  $PORT"
+echo "Insecure:     $INSECURE"
+echo "Auth:         $([ "$NO_AUTH" = true ] && echo "disabled" || echo "enabled")"
+echo "LND host:     $LND_HOST"
+echo "Config:       $CONFIG_FILE"
+echo ""
+
+# Create aperture directory.
+mkdir -p "$APERTURE_DIR"
+
+# Build config.
+cat > "$CONFIG_FILE" << YAML
+# Aperture configuration generated by setup.sh
+# Edit as needed: ~/.aperture/aperture.yaml
+
+listenaddr: "localhost:$PORT"
+debuglevel: "info"
+dbbackend: "sqlite"
+
+sqlite:
+  dbfile: "$APERTURE_DIR/aperture.db"
+
+insecure: $INSECURE
+
+authenticator:
+YAML
+
+if [ "$NO_AUTH" = true ]; then
+    cat >> "$CONFIG_FILE" << YAML
+  disable: true
+YAML
+else
+    cat >> "$CONFIG_FILE" << YAML
+  network: "$NETWORK"
+  lndhost: "$LND_HOST"
+  tlspath: "$LND_TLS"
+  macdir: "$LND_MACDIR"
+YAML
+fi
+
+cat >> "$CONFIG_FILE" << YAML
+
+services:
+  - name: "default-api"
+    hostregexp: ".*"
+    pathregexp: '^/api/.*$'
+    address: "127.0.0.1:$SERVICE_PORT"
+    protocol: http
+    price: $SERVICE_PRICE
+    timeout: 31557600
+    authwhitelistpaths:
+      - '^/health$'
+YAML
+
+echo "Config written to $CONFIG_FILE"
+echo ""
+echo "Next steps:"
+echo "  1. Start a backend on port $SERVICE_PORT"
+echo "  2. Start aperture: skills/aperture/scripts/start.sh"
+echo "  3. Test: lnget -k https://localhost:$PORT/api/test"

package/skills/aperture/scripts/start.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Start aperture reverse proxy.
+#
+# Usage:
+#   start.sh                           # Background, default config
+#   start.sh --foreground              # Foreground mode
+#   start.sh --config /path/to/yaml    # Custom config
+
+set -e
+
+APERTURE_DIR="$HOME/.aperture"
+CONFIG_FILE="$APERTURE_DIR/aperture.yaml"
+FOREGROUND=false
+
+# Parse arguments.
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --config)
+            CONFIG_FILE="$2"
+            shift 2
+            ;;
+        --foreground)
+            FOREGROUND=true
+            shift
+            ;;
+        -h|--help)
+            echo "Usage: start.sh [--foreground] [--config PATH]"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Verify aperture is installed.
+if ! command -v aperture &>/dev/null; then
+    echo "Error: aperture not found. Run install.sh first." >&2
+    exit 1
+fi
+
+# Verify config exists.
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo "Error: Config not found at $CONFIG_FILE" >&2
+    echo "Run setup.sh first to generate config." >&2
+    exit 1
+fi
+
+# Check if aperture is already running.
+if pgrep -x aperture &>/dev/null; then
+    echo "aperture is already running (PID: $(pgrep -x aperture))."
+    echo "Use stop.sh to stop it first."
+    exit 1
+fi
+
+echo "=== Starting Aperture ==="
+echo "Config: $CONFIG_FILE"
+echo ""
+
+LOG_FILE="$APERTURE_DIR/aperture-start.log"
+
+if [ "$FOREGROUND" = true ]; then
+    exec aperture --configfile="$CONFIG_FILE"
+else
+    nohup aperture --configfile="$CONFIG_FILE" \
+        > "$LOG_FILE" 2>&1 &
+    APERTURE_PID=$!
+    echo "aperture started in background (PID: $APERTURE_PID)"
+    echo "Log file: $LOG_FILE"
+
+    # Wait briefly and verify it's running.
+    sleep 2
+    if kill -0 "$APERTURE_PID" 2>/dev/null; then
+        echo "aperture is running."
+    else
+        echo "Error: aperture exited immediately. Check $LOG_FILE" >&2
+        tail -20 "$LOG_FILE" 2>/dev/null
+        exit 1
+    fi
+fi

package/skills/aperture/scripts/stop.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Stop aperture reverse proxy.
+#
+# Usage:
+#   stop.sh            # Graceful stop
+#   stop.sh --force    # SIGKILL
+
+set -e
+
+FORCE=false
+
+# Parse arguments.
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --force)
+            FORCE=true
+            shift
+            ;;
+        -h|--help)
+            echo "Usage: stop.sh [--force]"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+APERTURE_PID=$(pgrep -x aperture 2>/dev/null || true)
+if [ -z "$APERTURE_PID" ]; then
+    echo "aperture is not running."
+    exit 0
+fi
+
+echo "Stopping aperture (PID: $APERTURE_PID)..."
+
+if [ "$FORCE" = true ]; then
+    kill -9 "$APERTURE_PID"
+    echo "Sent SIGKILL."
+else
+    kill "$APERTURE_PID"
+    echo "Sent SIGTERM."
+fi
+
+# Wait for exit.
+for i in {1..10}; do
+    if ! kill -0 "$APERTURE_PID" 2>/dev/null; then
+        echo "aperture stopped."
+        exit 0
+    fi
+    sleep 1
+done
+
+echo "Warning: aperture did not exit within 10 seconds." >&2
+echo "Use --force to send SIGKILL." >&2
+exit 1

package/skills/aperture/templates/aperture-regtest.yaml

@@ -0,0 +1,36 @@
+# Aperture L402 Reverse Proxy — Regtest Configuration
+#
+# Used with docker-compose-aperture.yml for integration testing.
+# Connects to litd on the litd-regtest Docker network for invoice creation.
+
+# Listen on all interfaces so Docker port mapping works.
+listenaddr: "0.0.0.0:8082"
+
+debuglevel: "debug"
+
+# No TLS — regtest only.
+insecure: true
+
+# SQLite database for token storage.
+dbbackend: "sqlite"
+sqlite:
+  dbfile: "/root/.aperture/aperture.db"
+
+# L402 authenticator — connects to litd's embedded lnd.
+authenticator:
+  network: "regtest"
+  lndhost: "litd:10009"
+  tlspath: "/root/.lnd-creds/tls.cert"
+  macdir: "/root/.lnd-creds"
+
+# Backend service protected by L402.
+services:
+  - name: "test-api"
+    hostregexp: ".*"
+    pathregexp: '^/api/.*$'
+    address: "litd-backend:9999"
+    protocol: http
+    price: 1
+    timeout: 31557600
+    authwhitelistpaths:
+      - '^/health$'

package/skills/aperture/templates/aperture.yaml.template

@@ -0,0 +1,64 @@
+# Aperture L402 Reverse Proxy Configuration Template
+#
+# Copy to ~/.aperture/aperture.yaml and modify as needed.
+# Or use: skills/aperture/scripts/setup.sh to generate automatically.
+#
+# Documentation: https://github.com/lightninglabs/aperture
+
+# Listen address for incoming requests.
+listenaddr: "localhost:8081"
+
+# Log level: trace, debug, info, warn, error, critical.
+debuglevel: "info"
+
+# Disable TLS (development only). Set to false for production.
+insecure: true
+
+# Database backend: sqlite, postgres, or etcd.
+dbbackend: "sqlite"
+sqlite:
+  dbfile: "~/.aperture/aperture.db"
+
+# LND authentication configuration.
+authenticator:
+  # Network: regtest, simnet, testnet, mainnet, signet.
+  network: "mainnet"
+
+  # Direct lnd connection.
+  lndhost: "localhost:10009"
+  tlspath: "~/.lnd/tls.cert"
+  macdir: "~/.lnd/data/chain/bitcoin/mainnet"
+
+  # Or disable auth entirely for testing.
+  # disable: true
+
+# Backend services protected by L402.
+services:
+  - name: "default-api"
+    # Match all hosts.
+    hostregexp: ".*"
+
+    # Protect /api/ paths.
+    pathregexp: '^/api/.*$'
+
+    # Backend server address.
+    address: "127.0.0.1:8080"
+    protocol: http
+
+    # Price per request in satoshis.
+    price: 100
+
+    # Token expires after 1 year (seconds).
+    timeout: 31557600
+
+    # Free paths (no payment required).
+    authwhitelistpaths:
+      - '^/health$'
+      - '^/public/.*$'
+
+    # Optional rate limits.
+    # ratelimits:
+    #   - pathregexp: '^/api/.*$'
+    #     requests: 100
+    #     per: 1m
+    #     burst: 150

package/skills/aperture/templates/docker-compose-aperture.yml

@@ -0,0 +1,59 @@
+# Aperture L402 Reverse Proxy — Docker container on regtest.
+#
+# Requires a running litd + bitcoind regtest stack (docker-compose-regtest.yml).
+# Aperture connects to litd's lnd gRPC for invoice creation and L402 auth.
+#
+# Usage:
+#   docker compose -f docker-compose-aperture.yml up -d
+#   docker compose -f docker-compose-aperture.yml down -v
+#
+# The aperture container runs under Rosetta on Apple Silicon since no
+# arm64 image is published.
+#
+# Ports:
+#   8082 — Aperture HTTP proxy (insecure mode for regtest)
+#
+# A simple backend HTTP server is included as a second container (busybox
+# httpd serving static files from /www).
+
+services:
+  aperture:
+    image: ${APERTURE_IMAGE:-lightninglabs/aperture}:${APERTURE_VERSION:-v0.4.2}
+    platform: linux/amd64
+    container_name: litd-aperture
+    restart: unless-stopped
+    depends_on:
+      - backend
+    entrypoint: ["/bin/sh", "-c", "cp /tmp/aperture.yaml /root/.aperture/aperture.yaml && exec aperture --configfile=/root/.aperture/aperture.yaml"]
+    ports:
+      - "${APERTURE_PORT:-8082}:8082"
+    volumes:
+      - aperture-data:/root/.aperture
+      - ${APERTURE_CONF_PATH:-./aperture-regtest.yaml}:/tmp/aperture.yaml:ro
+      # Mount litd's TLS cert and macaroon from the litd container volume.
+      # These are copied in by the test setup after wallet creation.
+      - litd-aperture-creds:/root/.lnd-creds:ro
+    networks:
+      - litd-regtest
+      - aperture-net
+
+  backend:
+    image: busybox:latest
+    container_name: litd-backend
+    restart: unless-stopped
+    # Serve a simple HTTP response on port 9999.
+    command: ["sh", "-c", "mkdir -p /www/api && echo '{\"status\":\"ok\",\"message\":\"Hello from L402 backend\"}' > /www/api/data.json && echo '{\"status\":\"ok\"}' > /www/health && httpd -f -p 9999 -h /www"]
+    networks:
+      - aperture-net
+
+volumes:
+  aperture-data:
+  litd-aperture-creds:
+    external: true
+
+networks:
+  aperture-net:
+    driver: bridge
+  litd-regtest:
+    external: true
+    name: templates_litd-regtest

package/skills/commerce/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: commerce
+description: End-to-end agentic commerce workflow using Lightning Network. Use when an agent needs to set up a full payment stack (lnd + lnget + aperture), buy or sell data via L402, or enable agent-to-agent micropayments.
+user-invocable: false
+---
+
+# Agentic Commerce Toolkit
+
+This plugin provides a complete toolkit for agent-driven Lightning Network
+commerce. Three skills work together to enable agents to send and receive
+micropayments over the Lightning Network using the L402 protocol.
+
+## Components
+
+| Skill | Purpose |
+|-------|---------|
+| **lnd** | Run Lightning Terminal (litd: lnd + loop + pool + tapd) |
+| **lnget** | Fetch L402-protected resources (pay for data) |
+| **aperture** | Host paid API endpoints (sell data) |
+
+## Full Setup Workflow
+
+### Step 1: Install All Components
+
+```bash
+# Install litd (Lightning Terminal — bundles lnd + loop + pool + tapd)
+skills/lnd/scripts/install.sh
+
+# Install lnget (Lightning HTTP client)
+skills/lnget/scripts/install.sh
+
+# Install aperture (L402 reverse proxy)
+skills/aperture/scripts/install.sh
+```
+
+### Step 2: Set Up the Lightning Node
+
+```bash
+# Start litd container (testnet by default)
+skills/lnd/scripts/start-lnd.sh
+
+# Create an encrypted wallet
+skills/lnd/scripts/create-wallet.sh --mode standalone
+
+# Verify node is running
+skills/lnd/scripts/lncli.sh getinfo
+```
+
+### Step 3: Fund the Wallet
+
+```bash
+# Generate a Bitcoin address
+skills/lnd/scripts/lncli.sh newaddress p2tr
+
+# Send BTC to this address from an exchange or another wallet
+
+# Verify balance
+skills/lnd/scripts/lncli.sh walletbalance
+```
+
+### Step 4: Open a Channel
+
+```bash
+# Connect to a well-connected node (e.g., ACINQ, Bitfinex)
+skills/lnd/scripts/lncli.sh connect <pubkey>@<host>:9735
+
+# Open a channel
+skills/lnd/scripts/lncli.sh openchannel --node_key=<pubkey> --local_amt=1000000
+
+# Wait for channel to confirm (6 blocks)
+skills/lnd/scripts/lncli.sh listchannels
+```
+
+### Step 5: Configure lnget
+
+```bash
+# Initialize lnget config (auto-detects local lnd)
+lnget config init
+
+# Verify connection
+lnget ln status
+```
+
+### Step 6: Fetch Paid Resources
+
+```bash
+# Fetch an L402-protected resource
+lnget --max-cost 1000 https://api.example.com/paid-data
+
+# Preview without paying
+lnget --no-pay https://api.example.com/paid-data
+
+# Check cached tokens
+lnget tokens list
+```
+
+### Step 7: Host Paid Endpoints (Optional)
+
+```bash
+# Start your backend service
+python3 -m http.server 8080 &
+
+# Configure aperture to protect it
+skills/aperture/scripts/setup.sh --insecure --port 8081
+
+# Start the L402 paywall
+skills/aperture/scripts/start.sh
+
+# Other agents can now pay to access your endpoints
+# lnget --max-cost 100 https://your-host:8081/api/data
+```
+
+## Agent-to-Agent Commerce
+
+The full loop for autonomous agent commerce:
+
+```
+Agent A (buyer)                    Agent B (seller)
+─────────────                      ─────────────
+lnd node running                   lnd node running
+  ↓                                  ↓
+lnget fetches URL ──────────────→ aperture receives request
+                                     ↓
+                                   Returns 402 + invoice
+  ↓
+lnget pays invoice ─────────────→ lnd receives payment
+  ↓                                  ↓
+lnget retries with token ───────→ aperture validates token
+                                     ↓
+                                   Proxies to backend
+  ↓                                  ↓
+Agent A receives data ←──────────  Backend returns data
+```
+
+### Buyer Agent Setup
+
+```bash
+# One-time setup
+skills/lnd/scripts/install.sh
+skills/lnget/scripts/install.sh
+skills/lnd/scripts/start-lnd.sh
+skills/lnd/scripts/create-wallet.sh --mode standalone
+lnget config init
+
+# Fund wallet and open channels (one-time)
+skills/lnd/scripts/lncli.sh newaddress p2tr
+# ... send BTC ...
+skills/lnd/scripts/lncli.sh openchannel --node_key=<pubkey> --local_amt=500000
+
+# Ongoing: fetch paid resources
+lnget --max-cost 100 -q https://seller-api.example.com/api/data | jq .
+```
+
+### Seller Agent Setup
+
+```bash
+# One-time setup
+skills/lnd/scripts/install.sh
+skills/aperture/scripts/install.sh
+skills/lnd/scripts/start-lnd.sh
+skills/lnd/scripts/create-wallet.sh --mode standalone
+
+# Configure and start paywall
+skills/aperture/scripts/setup.sh --port 8081 --insecure
+
+# Start backend with content to sell
+mkdir -p /tmp/api-data
+echo '{"market_data": "..."}' > /tmp/api-data/data.json
+cd /tmp/api-data && python3 -m http.server 8080 &
+
+# Start aperture
+skills/aperture/scripts/start.sh
+
+# Buyers can now access:
+# https://your-host:8081/api/data.json (100 sats per request)
+```
+
+## Cost Management
+
+Agents should always control spending:
+
+```bash
+# Set a hard limit per request
+lnget --max-cost 500 https://api.example.com/data
+
+# Check cost before paying
+lnget --no-pay --json https://api.example.com/data | jq '.invoice_amount_sat'
+
+# Track spending via token list
+lnget tokens list --json | jq '[.[] | .amount_paid_sat] | add'
+```
+
+## Security Summary
+
+| Component | Security Model |
+|-----------|---------------|
+| **Wallet passphrase** | Stored at `~/.lnget/lnd/wallet-password.txt` (0600) |
+| **Seed mnemonic** | Stored at `~/.lnget/lnd/seed.txt` (0600) |
+| **L402 tokens** | Stored at `~/.lnget/tokens/<domain>/` per domain |
+| **lnd macaroons** | Standard lnd paths at `~/.lnd/data/chain/...` |
+| **Aperture DB** | SQLite at `~/.aperture/aperture.db` |
+
+For production use with significant funds, use watch-only mode with a remote
+signer container. See the `lightning-security-module` skill for details.
+
+## Stopping Everything
+
+```bash
+skills/aperture/scripts/stop.sh
+skills/lnd/scripts/stop-lnd.sh
+```