@lightninglabs/lightning-mcp-server 0.2.0

package/skills/macaroon-bakery/scripts/bake.sh

@@ -0,0 +1,337 @@
+#!/usr/bin/env bash
+# Bake, inspect, and manage lnd macaroons for least-privilege agent access.
+#
+# Usage:
+#   bake.sh --role pay-only                    # Bake a preset role
+#   bake.sh --role invoice-only                # Invoice-only agent
+#   bake.sh --role read-only                   # Read-only agent
+#   bake.sh --role channel-admin               # Channel management agent
+#   bake.sh --role signer-only                 # Remote signer scoped macaroon
+#   bake.sh --custom uri:/lnrpc.Lightning/...  # Custom permissions
+#   bake.sh --inspect <macaroon-path>          # Inspect a macaroon
+#   bake.sh --list-permissions                 # List all available permissions
+#   bake.sh --container sam --role pay-only     # Bake inside a Docker container
+#   bake.sh --rpcserver remote:10009 \          # Bake on a remote node
+#           --tlscertpath ~/tls.cert \
+#           --macaroonpath ~/admin.macaroon --role pay-only
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LND_DIR="${LND_DIR:-}"
+NETWORK="${NETWORK:-testnet}"
+RPC_PORT=""
+SAVE_TO=""
+ROLE=""
+INSPECT=""
+LIST_PERMS=false
+CUSTOM_PERMS=()
+CONTAINER=""
+RPCSERVER=""
+TLSCERTPATH=""
+MACAROONPATH=""
+
+# Parse arguments.
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --role)
+            ROLE="$2"
+            shift 2
+            ;;
+        --custom)
+            shift
+            # Collect all remaining non-flag args as permissions.
+            while [[ $# -gt 0 ]] && [[ ! "$1" =~ ^-- ]]; do
+                CUSTOM_PERMS+=("$1")
+                shift
+            done
+            ;;
+        --inspect)
+            INSPECT="$2"
+            shift 2
+            ;;
+        --list-permissions)
+            LIST_PERMS=true
+            shift
+            ;;
+        --save-to)
+            SAVE_TO="$2"
+            shift 2
+            ;;
+        --network)
+            NETWORK="$2"
+            shift 2
+            ;;
+        --lnddir)
+            LND_DIR="$2"
+            shift 2
+            ;;
+        --rpc-port)
+            RPC_PORT="$2"
+            shift 2
+            ;;
+        --container)
+            CONTAINER="$2"
+            shift 2
+            ;;
+        --rpcserver)
+            RPCSERVER="$2"
+            shift 2
+            ;;
+        --tlscertpath)
+            TLSCERTPATH="$2"
+            shift 2
+            ;;
+        --macaroonpath)
+            MACAROONPATH="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: bake.sh [options]"
+            echo ""
+            echo "Bake, inspect, and manage lnd macaroons."
+            echo ""
+            echo "Actions:"
+            echo "  --role ROLE            Bake a preset role macaroon"
+            echo "  --custom URI [URI...]  Bake with custom permission URIs"
+            echo "  --inspect PATH         Inspect a macaroon file"
+            echo "  --list-permissions     List all available permission URIs"
+            echo ""
+            echo "Preset roles: pay-only, invoice-only, read-only, channel-admin, signer-only"
+            echo ""
+            echo "Options:"
+            echo "  --save-to PATH         Output path (default: auto-generated)"
+            echo "  --network NETWORK      Bitcoin network (default: testnet)"
+            echo "  --lnddir DIR           lnd data directory (default: ~/.lnd)"
+            echo "  --rpc-port PORT        lnd RPC port (for non-default setups)"
+            echo "  --container NAME       Run lncli inside a Docker container"
+            echo "  --rpcserver HOST:PORT  Connect to a remote lnd node"
+            echo "  --tlscertpath PATH     TLS certificate for remote connection"
+            echo "  --macaroonpath PATH    Macaroon for remote authentication"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Apply default lnddir if not set.
+if [ -z "$LND_DIR" ]; then
+    if [ -n "$CONTAINER" ]; then
+        LND_DIR="/root/.lnd"
+    else
+        LND_DIR="$HOME/.lnd"
+    fi
+fi
+
+# Build lncli base command as an array (preserves paths with spaces).
+LNCLI_CMD=()
+if [ -n "$CONTAINER" ]; then
+    LNCLI_CMD+=(docker exec "$CONTAINER")
+fi
+LNCLI_CMD+=(lncli "--network=$NETWORK" "--lnddir=$LND_DIR")
+if [ -n "$RPCSERVER" ]; then
+    LNCLI_CMD+=("--rpcserver=$RPCSERVER")
+elif [ -n "$RPC_PORT" ]; then
+    LNCLI_CMD+=("--rpcserver=localhost:$RPC_PORT")
+fi
+if [ -n "$TLSCERTPATH" ]; then
+    LNCLI_CMD+=("--tlscertpath=$TLSCERTPATH")
+fi
+if [ -n "$MACAROONPATH" ]; then
+    LNCLI_CMD+=("--macaroonpath=$MACAROONPATH")
+fi
+
+# Verify lncli is available.
+if [ -n "$CONTAINER" ]; then
+    if ! docker exec "$CONTAINER" which lncli &>/dev/null; then
+        echo "Error: lncli not found in container '$CONTAINER'." >&2
+        exit 1
+    fi
+elif ! command -v lncli &>/dev/null; then
+    echo "Error: lncli not found. Run the lnd skill's install.sh first." >&2
+    exit 1
+fi
+
+# --- Inspect mode ---
+if [ -n "$INSPECT" ]; then
+    if [ -n "$CONTAINER" ]; then
+        # The macaroon may be on the host or inside the container. If it
+        # exists on the host, copy it into the container for inspection.
+        if [ -f "$INSPECT" ]; then
+            CONTAINER_TMP="/tmp/inspect-$(date +%s).macaroon"
+            docker cp "$INSPECT" "$CONTAINER:$CONTAINER_TMP"
+            INSPECT_PATH="$CONTAINER_TMP"
+        elif docker exec "$CONTAINER" test -f "$INSPECT" 2>/dev/null; then
+            INSPECT_PATH="$INSPECT"
+        else
+            echo "Error: Macaroon file not found: $INSPECT" >&2
+            exit 1
+        fi
+    elif [ ! -f "$INSPECT" ]; then
+        echo "Error: Macaroon file not found: $INSPECT" >&2
+        exit 1
+    else
+        INSPECT_PATH="$INSPECT"
+    fi
+    echo "=== Macaroon: $(basename "$INSPECT") ==="
+    echo "Path: $INSPECT"
+    if [ -n "$CONTAINER" ]; then
+        echo "Container: $CONTAINER"
+    fi
+    echo ""
+    "${LNCLI_CMD[@]}" printmacaroon --macaroon_file "$INSPECT_PATH"
+    # Clean up temporary copy if we created one.
+    if [ -n "$CONTAINER" ] && [ -f "$INSPECT" ]; then
+        docker exec "$CONTAINER" rm -f "$INSPECT_PATH" 2>/dev/null || true
+    fi
+    exit 0
+fi
+
+# --- List permissions mode ---
+if [ "$LIST_PERMS" = true ]; then
+    echo "=== Available Macaroon Permissions ==="
+    echo ""
+    "${LNCLI_CMD[@]}" listpermissions | jq -r '.method_permissions | to_entries[] | .key' | sort
+    exit 0
+fi
+
+# --- Bake mode ---
+
+# Resolve permissions from role or custom.
+PERMS=()
+
+if [ -n "$ROLE" ]; then
+    case $ROLE in
+        pay-only)
+            PERMS=(
+                "uri:/lnrpc.Lightning/SendPaymentSync"
+                "uri:/routerrpc.Router/SendPaymentV2"
+                "uri:/lnrpc.Lightning/DecodePayReq"
+                "uri:/lnrpc.Lightning/GetInfo"
+            )
+            ;;
+        invoice-only)
+            PERMS=(
+                "uri:/lnrpc.Lightning/AddInvoice"
+                "uri:/invoicesrpc.Invoices/AddHoldInvoice"
+                "uri:/lnrpc.Lightning/LookupInvoice"
+                "uri:/lnrpc.Lightning/ListInvoices"
+                "uri:/lnrpc.Lightning/GetInfo"
+            )
+            ;;
+        read-only)
+            PERMS=(
+                "uri:/lnrpc.Lightning/GetInfo"
+                "uri:/lnrpc.Lightning/WalletBalance"
+                "uri:/lnrpc.Lightning/ChannelBalance"
+                "uri:/lnrpc.Lightning/ListChannels"
+                "uri:/lnrpc.Lightning/ListPeers"
+                "uri:/lnrpc.Lightning/ListPayments"
+                "uri:/lnrpc.Lightning/ListInvoices"
+                "uri:/lnrpc.Lightning/GetNodeInfo"
+                "uri:/lnrpc.Lightning/GetChanInfo"
+            )
+            ;;
+        channel-admin)
+            PERMS=(
+                "uri:/lnrpc.Lightning/GetInfo"
+                "uri:/lnrpc.Lightning/WalletBalance"
+                "uri:/lnrpc.Lightning/ChannelBalance"
+                "uri:/lnrpc.Lightning/ListChannels"
+                "uri:/lnrpc.Lightning/ListPeers"
+                "uri:/lnrpc.Lightning/ConnectPeer"
+                "uri:/lnrpc.Lightning/DisconnectPeer"
+                "uri:/lnrpc.Lightning/OpenChannelSync"
+                "uri:/lnrpc.Lightning/CloseChannel"
+                "uri:/lnrpc.Lightning/ClosedChannels"
+                "uri:/lnrpc.Lightning/GetNodeInfo"
+                "uri:/lnrpc.Lightning/GetChanInfo"
+            )
+            ;;
+        signer-only)
+            PERMS=(
+                "uri:/signrpc.Signer/SignOutputRaw"
+                "uri:/signrpc.Signer/ComputeInputScript"
+                "uri:/signrpc.Signer/MuSig2Sign"
+                "uri:/signrpc.Signer/MuSig2Cleanup"
+                "uri:/signrpc.Signer/MuSig2CreateSession"
+                "uri:/signrpc.Signer/MuSig2RegisterNonces"
+                "uri:/signrpc.Signer/MuSig2CombineSig"
+                "uri:/walletrpc.WalletKit/DeriveKey"
+                "uri:/walletrpc.WalletKit/DeriveNextKey"
+                "uri:/lnrpc.Lightning/GetInfo"
+            )
+            ;;
+        *)
+            echo "Error: Unknown role '$ROLE'." >&2
+            echo "Available roles: pay-only, invoice-only, read-only, channel-admin, signer-only" >&2
+            exit 1
+            ;;
+    esac
+elif [ ${#CUSTOM_PERMS[@]} -gt 0 ]; then
+    PERMS=("${CUSTOM_PERMS[@]}")
+else
+    echo "Error: Specify --role, --custom, --inspect, or --list-permissions." >&2
+    echo "Run bake.sh --help for usage." >&2
+    exit 1
+fi
+
+# Determine output path.
+if [ -z "$SAVE_TO" ]; then
+    if [ -n "$CONTAINER" ] || [ -n "$RPCSERVER" ]; then
+        # Container/remote mode: save locally, not inside the container or on the remote.
+        MACAROON_DIR="$HOME/.lnget/macaroons"
+    else
+        MACAROON_DIR="$LND_DIR/data/chain/bitcoin/$NETWORK"
+    fi
+    if [ -n "$ROLE" ]; then
+        SAVE_TO="$MACAROON_DIR/${ROLE}.macaroon"
+    else
+        SAVE_TO="$MACAROON_DIR/custom-$(date +%s).macaroon"
+    fi
+fi
+
+# Ensure output directory exists.
+mkdir -p "$(dirname "$SAVE_TO")"
+
+echo "=== Baking Macaroon ==="
+if [ -n "$ROLE" ]; then
+    echo "Role:        $ROLE"
+fi
+echo "Permissions: ${#PERMS[@]}"
+echo "Output:      $SAVE_TO"
+echo ""
+
+# Bake the macaroon.
+if [ -n "$CONTAINER" ]; then
+    # Bake inside container, then copy out to local path.
+    CONTAINER_TMP="/tmp/baked-$(date +%s).macaroon"
+    "${LNCLI_CMD[@]}" bakemacaroon "${PERMS[@]}" --save_to="$CONTAINER_TMP"
+    docker cp "$CONTAINER:$CONTAINER_TMP" "$SAVE_TO"
+    docker exec "$CONTAINER" rm -f "$CONTAINER_TMP"
+else
+    "${LNCLI_CMD[@]}" bakemacaroon "${PERMS[@]}" --save_to="$SAVE_TO"
+fi
+
+# Set restrictive permissions.
+chmod 600 "$SAVE_TO"
+
+echo ""
+echo "=== Macaroon Baked ==="
+echo "Saved to: $SAVE_TO (mode 0600)"
+echo ""
+echo "Permissions granted:"
+for p in "${PERMS[@]}"; do
+    echo "  $p"
+done
+echo ""
+echo "To verify:"
+echo "  bake.sh --inspect $SAVE_TO"
+echo ""
+echo "To use with lnget:"
+echo "  ln:"
+echo "    lnd:"
+echo "      macaroon: $SAVE_TO"

package/skills/mcp-lnc/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: mcp-lnc
+description: Build and configure the MCP server for Lightning Node Connect (LNC). Connects AI assistants to lnd nodes via encrypted WebSocket tunnels using pairing phrases — no direct network access or TLS certs needed. Read-only by default (18 tools for querying node state, channels, payments, invoices, peers, on-chain data).
+---
+
+# MCP LNC Server
+
+Build and configure the MCP server that connects AI assistants to Lightning
+nodes via **Lightning Node Connect (LNC)**. LNC uses encrypted WebSocket tunnels
+through a mailbox relay, so the agent never needs direct gRPC access, TLS
+certificates, or macaroons — just a 10-word pairing phrase from Lightning
+Terminal.
+
+The MCP server is **read-only by default** — it exposes 18 tools for querying
+node state but cannot send payments or modify channels.
+
+## Quick Start
+
+```bash
+# 1. Build the MCP server binary
+skills/mcp-lnc/scripts/install.sh
+
+# 2. Configure environment (mailbox server, dev mode, etc.)
+skills/mcp-lnc/scripts/configure.sh
+
+# 3. Add to Claude Code as an MCP server
+skills/mcp-lnc/scripts/setup-claude-config.sh
+```
+
+Then restart Claude Code. The `lnc_connect` tool will be available to connect
+to any lnd node using a pairing phrase.
+
+## How It Works
+
+```
+Claude Code  <--stdio-->  mcp-lnc-server  <--LNC WebSocket-->  Mailbox  <-->  lnd
+```
+
+1. Claude Code launches `mcp-lnc-server` as a subprocess (stdio transport)
+2. Agent calls `lnc_connect` with a pairing phrase and password
+3. Server generates an ephemeral ECDSA keypair and opens an encrypted WebSocket
+   tunnel through the mailbox relay
+4. Once connected, the agent can call any of the 18 read-only tools
+5. `lnc_disconnect` closes the tunnel
+
+No keys, certs, or macaroons are stored on disk — the pairing phrase is the
+only credential, and it's handled in-memory only.
+
+## Installation
+
+```bash
+# Build from source (requires Go 1.24+)
+skills/mcp-lnc/scripts/install.sh
+
+# Verify
+mcp-lnc-server -version
+```
+
+The install script builds from the `mcp-server/` directory in this repo.
+
+## Configuration
+
+```bash
+# Generate .env with defaults
+skills/mcp-lnc/scripts/configure.sh
+
+# Production (mainnet via Lightning Terminal)
+skills/mcp-lnc/scripts/configure.sh --production
+
+# Development (local regtest)
+skills/mcp-lnc/scripts/configure.sh --dev --mailbox aperture:11110
+```
+
+Configuration is stored in `mcp-server/.env`. Key settings:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LNC_MAILBOX_SERVER` | `mailbox.terminal.lightning.today:443` | Mailbox relay server |
+| `LNC_DEV_MODE` | `false` | Enable development mode |
+| `LNC_INSECURE` | `false` | Skip TLS verification (dev only) |
+| `LNC_CONNECT_TIMEOUT` | `30` | Connection timeout in seconds |
+
+## Claude Code Integration
+
+### Option 1: `claude mcp add` (recommended)
+
+Register the MCP server with a single command — no build step required:
+
+```bash
+# Zero-install via npx (downloads pre-built binary)
+claude mcp add --transport stdio lnc -- npx -y @lightninglabs/lightning-mcp-server
+
+# With environment variables for production
+claude mcp add --transport stdio \
+  --env LNC_MAILBOX_SERVER=mailbox.terminal.lightning.today:443 \
+  lnc -- npx -y @lightninglabs/lightning-mcp-server
+
+# For development/regtest
+claude mcp add --transport stdio \
+  --env LNC_MAILBOX_SERVER=localhost:11110 \
+  --env LNC_DEV_MODE=true \
+  --env LNC_INSECURE=true \
+  lnc -- npx -y @lightninglabs/lightning-mcp-server
+```
+
+Scope options: `--scope local` (default, just you), `--scope project` (shared
+via `.mcp.json`), `--scope user` (all your projects).
+
+### Option 2: Setup script (from source)
+
+```bash
+# Add mcp-lnc-server to Claude Code's MCP config
+skills/mcp-lnc/scripts/setup-claude-config.sh
+
+# Project-level config (current project only)
+skills/mcp-lnc/scripts/setup-claude-config.sh --scope project
+
+# Global config (all projects)
+skills/mcp-lnc/scripts/setup-claude-config.sh --scope global
+```
+
+This adds the server to Claude Code's `.mcp.json` (project) or
+`~/.claude.json` (global) configuration. After restarting Claude Code, the
+LNC tools will be available.
+
+### Option 3: Manual configuration
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "lnc": {
+      "command": "npx",
+      "args": ["-y", "@lightninglabs/lightning-mcp-server"],
+      "env": {
+        "LNC_MAILBOX_SERVER": "mailbox.terminal.lightning.today:443"
+      }
+    }
+  }
+}
+```
+
+Or with a locally built binary:
+
+```json
+{
+  "mcpServers": {
+    "lnc": {
+      "command": "mcp-lnc-server",
+      "env": {
+        "LNC_MAILBOX_SERVER": "mailbox.terminal.lightning.today:443"
+      }
+    }
+  }
+}
+```
+
+Or run via Docker:
+
+```json
+{
+  "mcpServers": {
+    "lnc": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i", "--network", "host",
+        "--env", "LNC_MAILBOX_SERVER",
+        "--env", "LNC_DEV_MODE",
+        "--env", "LNC_INSECURE",
+        "mcp-lnc-server"
+      ]
+    }
+  }
+}
+```
+
+## Available Tools (18)
+
+### Connection
+
+| Tool | Description |
+|------|-------------|
+| `lnc_connect` | Connect to lnd via LNC pairing phrase |
+| `lnc_disconnect` | Close active LNC connection |
+
+### Node
+
+| Tool | Description |
+|------|-------------|
+| `lnc_get_info` | Node alias, version, sync status, block height |
+| `lnc_get_balance` | Wallet balance (on-chain) and channel balance |
+
+### Channels
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_channels` | Active/inactive channels with capacity, balances |
+| `lnc_pending_channels` | Channels being opened or closed |
+
+### Invoices
+
+| Tool | Description |
+|------|-------------|
+| `lnc_decode_invoice` | Decode a BOLT11 invoice |
+| `lnc_list_invoices` | List invoices with pagination |
+| `lnc_lookup_invoice` | Look up invoice by payment hash |
+
+### Payments
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_payments` | Payment history with pagination |
+| `lnc_track_payment` | Track specific payment by hash |
+
+### Peers & Network
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_peers` | Connected peers with stats |
+| `lnc_describe_graph` | Lightning Network topology sample |
+| `lnc_get_node_info` | Detailed info about a specific node |
+
+### On-Chain
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_unspent` | UTXOs with confirmations |
+| `lnc_get_transactions` | On-chain transaction history |
+| `lnc_estimate_fee` | Fee estimates for confirmation targets |
+
+## Security Model
+
+- **No stored credentials:** Pairing phrase is handled in-memory only. Ephemeral
+  ECDSA keypairs are generated per session.
+- **Read-only:** No payment, channel, or state-changing operations are exposed.
+  The agent can observe but not modify.
+- **Encrypted tunnels:** All traffic is encrypted end-to-end through the mailbox
+  relay. The mailbox cannot read the traffic.
+- **No direct access:** The agent machine never connects directly to the lnd
+  node's gRPC port — all traffic goes through the mailbox.
+
+### Comparison with Direct gRPC Access
+
+| | MCP LNC Server | Direct lncli/gRPC |
+|---|---|---|
+| **Credential** | Pairing phrase (in-memory) | TLS cert + macaroon (on disk) |
+| **Network** | WebSocket via mailbox relay | Direct TCP to gRPC port |
+| **Firewall** | No inbound ports needed | Port 10009 must be reachable |
+| **Permissions** | Read-only (hardcoded) | Depends on macaroon scope |
+| **Setup** | Pairing phrase from Lightning Terminal | Export cert + macaroon files |
+
+## Prerequisites
+
+- **Go 1.24+** for building from source
+- **Lightning Terminal (litd)** on the target node for generating pairing phrases
+- **Claude Code** for MCP integration
+
+## Troubleshooting
+
+### "pairing phrase must be exactly 10 words"
+The pairing phrase is generated by Lightning Terminal. It must be exactly 10
+space-separated words.
+
+### "connection timeout"
+Check that the mailbox server is reachable. For production, ensure
+`mailbox.terminal.lightning.today:443` is not blocked by a firewall.
+
+### "TLS handshake failure"
+If using a local regtest setup, enable dev mode and insecure mode:
+```bash
+skills/mcp-lnc/scripts/configure.sh --dev --insecure
+```
+
+### Tools not appearing in Claude Code
+Restart Claude Code after running `setup-claude-config.sh`. Check that
+`mcp-lnc-server` is on your `$PATH`:
+```bash
+which mcp-lnc-server
+```