@lightninglabs/lightning-mcp-server 0.2.0

package/skills/lnget/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: lnget
+description: Install and use lnget, a Lightning-native HTTP client with automatic L402 payment support. Use when downloading files behind Lightning paywalls, managing L402 tokens, checking Lightning backend status, or making HTTP requests that may require micropayments.
+---
+
+# lnget - Lightning-Native HTTP Client
+
+lnget is a wget/curl-like CLI that natively handles L402 (Lightning HTTP 402)
+authentication. When a server responds with HTTP 402 and an L402 challenge,
+lnget automatically pays the Lightning invoice and retries with the paid token.
+
+**Source:** `github.com/lightninglabs/lnget`
+
+## Quick Start
+
+```bash
+# 1. Install lnget
+skills/lnget/scripts/install.sh
+
+# 2. Initialize config (auto-detects local lnd)
+lnget config init
+
+# 3. Fetch an L402-protected resource
+lnget --max-cost 1000 https://api.example.com/paid-data
+```
+
+## Installation
+
+```bash
+skills/lnget/scripts/install.sh
+```
+
+This will:
+- Verify Go is installed
+- Run `go install github.com/lightninglabs/lnget/cmd/lnget@latest`
+- Verify `lnget` is on `$PATH`
+
+To install manually:
+
+```bash
+go install github.com/lightninglabs/lnget/cmd/lnget@latest
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/lightninglabs/lnget.git
+cd lnget
+make install
+```
+
+## Basic Usage
+
+### Downloads
+
+```bash
+# Fetch URL (output to stdout)
+lnget https://api.example.com/data.json
+
+# Save to file
+lnget -o data.json https://api.example.com/data.json
+
+# Quiet mode for piping
+lnget -q https://api.example.com/data.json | jq .
+
+# Resume partial download
+lnget -c -o largefile.zip https://api.example.com/largefile.zip
+
+# Custom HTTP method with data
+lnget -X POST -d '{"query":"test"}' https://api.example.com/search
+
+# Custom headers
+lnget -H "Accept: text/plain" https://api.example.com/data
+```
+
+### Payment Control
+
+```bash
+# Set maximum auto-pay amount (satoshis)
+lnget --max-cost 5000 https://api.example.com/expensive.json
+
+# Set maximum routing fee
+lnget --max-fee 50 https://api.example.com/data.json
+
+# Preview without paying (shows 402 challenge details)
+lnget --no-pay https://api.example.com/data.json
+
+# Custom payment timeout
+lnget --payment-timeout 120s https://api.example.com/data.json
+```
+
+### Output Modes
+
+```bash
+# JSON output (default, best for programmatic use)
+lnget --json https://api.example.com/data.json
+
+# Human-readable output
+lnget --human https://api.example.com/data.json
+
+# Verbose mode (shows L402 flow details)
+lnget -v https://api.example.com/data.json
+
+# Disable progress bar
+lnget --no-progress -o file.zip https://api.example.com/file.zip
+```
+
+## Subcommands
+
+### Token Management (`lnget tokens`)
+
+Tokens are cached per-domain at `~/.lnget/tokens/<domain>/token.json` and
+reused automatically on subsequent requests.
+
+```bash
+# List all cached tokens
+lnget tokens list
+
+# Show token for a specific domain
+lnget tokens show api.example.com
+
+# Remove token for a domain (forces re-authentication)
+lnget tokens remove api.example.com
+
+# Clear all tokens
+lnget tokens clear --force
+```
+
+### Configuration (`lnget config`)
+
+```bash
+# Initialize config file at ~/.lnget/config.yaml
+lnget config init
+
+# Show current configuration
+lnget config show
+
+# Show config file path
+lnget config path
+```
+
+### Lightning Backend (`lnget ln`)
+
+```bash
+# Check backend connection status
+lnget ln status
+
+# Show detailed node info
+lnget ln info
+```
+
+#### LNC (Lightning Node Connect)
+
+```bash
+# Pair with a node via LNC pairing phrase
+lnget ln lnc pair "your-pairing-phrase"
+
+# Ephemeral pairing (no session persistence)
+lnget ln lnc pair "phrase" --ephemeral
+
+# List saved LNC sessions
+lnget ln lnc sessions
+
+# Revoke a session
+lnget ln lnc revoke <session-id>
+```
+
+#### Neutrino (Embedded Wallet)
+
+```bash
+# Initialize embedded neutrino wallet
+lnget ln neutrino init
+
+# Get address to fund wallet
+lnget ln neutrino fund
+
+# Check wallet balance
+lnget ln neutrino balance
+
+# Show sync status
+lnget ln neutrino status
+```
+
+## Configuration File
+
+Config lives at `~/.lnget/config.yaml`. Run `lnget config init` to create it.
+
+```yaml
+l402:
+  max_cost_sats: 1000       # Max invoice to auto-pay
+  max_fee_sats: 10           # Max routing fee
+  payment_timeout: 60s       # Payment timeout
+  auto_pay: true             # Enable auto-payment
+
+http:
+  timeout: 30s
+  max_redirects: 10
+  user_agent: "lnget/0.1.0"
+  allow_insecure: false
+
+ln:
+  mode: lnd                  # Options: lnd, lnc, neutrino
+  lnd:
+    host: localhost:10009
+    tls_cert: ~/.lnd/tls.cert
+    macaroon: ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
+    network: mainnet
+
+output:
+  format: json
+  progress: true
+  verbose: false
+
+tokens:
+  dir: ~/.lnget/tokens
+```
+
+Environment variables override config with `LNGET_` prefix:
+
+```bash
+export LNGET_L402_MAX_COST_SATS=5000
+export LNGET_LN_MODE=lnc
+export LNGET_LN_LND_HOST=localhost:10009
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Payment exceeds max cost |
+| 3 | Payment failed |
+| 4 | Network/connection error |
+
+## L402 Flow
+
+When lnget encounters a 402 response:
+
+1. Parses `WWW-Authenticate: L402 macaroon="...", invoice="..."` header
+2. Decodes the macaroon and BOLT11 invoice
+3. Checks invoice amount against `--max-cost`
+4. Stores a pending token (crash recovery)
+5. Pays the invoice via the configured Lightning backend
+6. Stores the paid token with preimage at `~/.lnget/tokens/<domain>/`
+7. Retries the request with `Authorization: L402 <macaroon>:<preimage>`
+
+Subsequent requests to the same domain reuse the cached token without payment.
+
+## Agent Integration Patterns
+
+### Budget-Aware Fetching
+
+```bash
+# Check cost before committing
+result=$(lnget --no-pay --json https://api.example.com/data.json)
+cost=$(echo "$result" | jq -r '.invoice_amount_sat // 0')
+
+if [ "$cost" -le "$BUDGET" ]; then
+    lnget --max-cost "$BUDGET" -q https://api.example.com/data.json
+fi
+```
+
+### Parsing JSON Output
+
+```bash
+# Extract just the response body
+lnget --json -q https://api.example.com/data.json | jq '.body'
+
+# Check if payment was required
+lnget --json https://api.example.com/data.json | jq '.l402_paid'
+```
+
+### Testing with Insecure Connections
+
+```bash
+# For local development with aperture (no TLS)
+lnget -k https://localhost:8081/api/data
+```
+
+## File Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.lnget/config.yaml` | Configuration file |
+| `~/.lnget/tokens/<domain>/` | Per-domain token storage |
+| `~/.lnget/lnc/sessions/` | LNC session persistence |
+| `~/.lnget/neutrino/` | Embedded wallet data |

package/skills/lnget/scripts/install.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Install lnget from source.
+#
+# Usage:
+#   install.sh                       # Install latest
+#   install.sh --version v0.1.0      # Specific version
+
+set -e
+
+VERSION=""
+
+# Parse arguments.
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --version)
+            VERSION="@$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: install.sh [--version VERSION]"
+            echo ""
+            echo "Install lnget Lightning-native HTTP client."
+            echo ""
+            echo "Options:"
+            echo "  --version VERSION  Go module version"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+echo "=== Installing lnget ==="
+echo ""
+
+# Verify Go is installed.
+if ! command -v go &>/dev/null; then
+    echo "Error: Go is not installed." >&2
+    echo "Install Go from https://go.dev/dl/" >&2
+    exit 1
+fi
+
+echo "Go version: $(go version | grep -oE 'go[0-9]+\.[0-9]+')"
+echo ""
+
+# Install lnget.
+echo "Installing lnget..."
+go install "github.com/lightninglabs/lnget/cmd/lnget${VERSION}"
+echo "Done."
+echo ""
+
+# Verify installation.
+if command -v lnget &>/dev/null; then
+    echo "lnget installed: $(which lnget)"
+else
+    echo "Warning: lnget not found on PATH." >&2
+    echo "Ensure \$GOPATH/bin is in your PATH." >&2
+    echo "  export PATH=\$PATH:\$(go env GOPATH)/bin" >&2
+fi
+
+echo ""
+echo "Installation complete."
+echo ""
+echo "Next steps:"
+echo "  1. Initialize config: lnget config init"
+echo "  2. Check LN status:   lnget ln status"
+echo "  3. Fetch a URL:        lnget https://example.com"

package/skills/macaroon-bakery/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: macaroon-bakery
+description: Bake, inspect, and manage lnd macaroons for least-privilege agent access. Use when an agent needs scoped credentials — pay-only, invoice-only, read-only, or custom permissions. Also covers signer macaroon scoping and macaroon rotation.
+---
+
+# Macaroon Bakery
+
+Bake custom lnd macaroons so every agent gets only the permissions it needs.
+Never hand out `admin.macaroon` in production — bake a scoped one instead.
+
+## Quick Start
+
+```bash
+# Bake a pay-only macaroon
+skills/macaroon-bakery/scripts/bake.sh --role pay-only
+
+# Bake an invoice-only macaroon
+skills/macaroon-bakery/scripts/bake.sh --role invoice-only
+
+# Bake a read-only macaroon
+skills/macaroon-bakery/scripts/bake.sh --role read-only
+
+# Inspect any macaroon
+skills/macaroon-bakery/scripts/bake.sh --inspect ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
+
+# List all available lnd permissions
+skills/macaroon-bakery/scripts/bake.sh --list-permissions
+```
+
+### Docker
+
+The litd container is auto-detected. You can also specify `--container`:
+
+```bash
+# Auto-detect litd container (default)
+skills/macaroon-bakery/scripts/bake.sh --role pay-only
+
+# Explicit container
+skills/macaroon-bakery/scripts/bake.sh --role pay-only --container litd
+
+# Inspect a macaroon inside a container
+skills/macaroon-bakery/scripts/bake.sh --inspect /root/.lnd/data/chain/bitcoin/testnet/admin.macaroon --container litd
+```
+
+### Remote Nodes
+
+To bake macaroons on a remote lnd node, provide the connection credentials:
+
+```bash
+# Bake a pay-only macaroon on a remote node
+skills/macaroon-bakery/scripts/bake.sh --role pay-only \
+    --rpcserver remote-host:10009 \
+    --tlscertpath ~/remote-tls.cert \
+    --macaroonpath ~/remote-admin.macaroon \
+    --save-to ~/remote-pay-only.macaroon
+```
+
+You need lncli installed locally and copies of the node's TLS cert and a macaroon
+with `macaroon:generate` permission (typically admin.macaroon).
+
+## Preset Roles
+
+| Role | What the agent can do | Cannot do |
+|------|----------------------|-----------|
+| `pay-only` | Pay invoices, decode invoices, get node info | Create invoices, open channels, see balances |
+| `invoice-only` | Create invoices, lookup invoices, get node info | Pay, open channels, see wallet balance |
+| `read-only` | Get info, balances, list channels/peers/payments | Pay, create invoices, open/close channels |
+| `channel-admin` | All of read-only + open/close channels, connect peers | Pay invoices, create invoices |
+| `signer-only` | Sign transactions, derive keys (for remote signer) | Everything else |
+
+## Baking Custom Macaroons
+
+For permissions not covered by presets, bake a custom macaroon:
+
+```bash
+# Custom: agent can only pay and check wallet balance
+skills/macaroon-bakery/scripts/bake.sh --custom \
+    uri:/lnrpc.Lightning/SendPaymentSync \
+    uri:/lnrpc.Lightning/DecodePayReq \
+    uri:/lnrpc.Lightning/WalletBalance \
+    uri:/lnrpc.Lightning/GetInfo
+
+# Custom with explicit output path
+skills/macaroon-bakery/scripts/bake.sh --custom \
+    uri:/lnrpc.Lightning/AddInvoice \
+    uri:/lnrpc.Lightning/GetInfo \
+    --save-to ~/my-agent.macaroon
+```
+
+## Discovering Permissions
+
+```bash
+# List all available URI permissions
+skills/macaroon-bakery/scripts/bake.sh --list-permissions
+
+# Filter for specific service
+skills/macaroon-bakery/scripts/bake.sh --list-permissions | grep -i invoice
+
+# Filter for routing-related permissions
+skills/macaroon-bakery/scripts/bake.sh --list-permissions | grep -i router
+```
+
+## Inspecting Macaroons
+
+```bash
+# See what permissions a macaroon has
+skills/macaroon-bakery/scripts/bake.sh --inspect <path-to-macaroon>
+
+# Inspect the admin macaroon to see full permissions
+skills/macaroon-bakery/scripts/bake.sh --inspect ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
+```
+
+## Signer Macaroon Scoping
+
+When using the `lightning-security-module` skill, the credentials bundle includes
+`admin.macaroon` by default. For production, bake a signing-only macaroon on the
+signer machine:
+
+```bash
+# On the signer container
+skills/macaroon-bakery/scripts/bake.sh --role signer-only \
+    --container litd-signer --rpc-port 10012
+
+# Or on a native signer
+skills/macaroon-bakery/scripts/bake.sh --role signer-only \
+    --rpc-port 10012 --lnddir ~/.lnd-signer
+
+# Then re-export the credentials bundle with the scoped macaroon
+```
+
+## Macaroon Rotation
+
+Rotate macaroons regularly to limit the window if one is compromised:
+
+```bash
+# 1. Bake a new macaroon with the same role
+skills/macaroon-bakery/scripts/bake.sh --role pay-only --save-to ~/pay-only-v2.macaroon
+
+# 2. Update your agent config to use the new macaroon
+
+# 3. Delete the old macaroon's root key (invalidates it)
+skills/lnd/scripts/lncli.sh bakemacaroon --root_key_id 0
+# Note: use lncli listmacaroonids and deletemacaroonid for fine-grained control
+```
+
+## Best Practices
+
+- **One macaroon per agent role.** Don't share macaroons between agents with
+  different responsibilities.
+- **Never use admin.macaroon in production.** It's the master key.
+- **Inspect before deploying.** Always verify what a baked macaroon can do.
+- **Rotate on a schedule.** Monthly for production, immediately if compromised.
+- **Scope signer macaroons too.** The remote signer's credentials bundle should
+  use `signer-only`, not `admin`.
+- **Store with 0600 permissions.** Macaroons are bearer tokens — treat like passwords.
+
+## Common Permission URIs
+
+| Permission | Description |
+|-----------|-------------|
+| `uri:/lnrpc.Lightning/GetInfo` | Node info (version, pubkey, sync status) |
+| `uri:/lnrpc.Lightning/WalletBalance` | On-chain wallet balance |
+| `uri:/lnrpc.Lightning/ChannelBalance` | Lightning channel balance |
+| `uri:/lnrpc.Lightning/ListChannels` | List open channels |
+| `uri:/lnrpc.Lightning/ListPeers` | List connected peers |
+| `uri:/lnrpc.Lightning/SendPaymentSync` | Pay a Lightning invoice |
+| `uri:/lnrpc.Lightning/DecodePayReq` | Decode a BOLT11 invoice |
+| `uri:/lnrpc.Lightning/AddInvoice` | Create a Lightning invoice |
+| `uri:/lnrpc.Lightning/LookupInvoice` | Look up an invoice by hash |
+| `uri:/lnrpc.Lightning/ListInvoices` | List all invoices |
+| `uri:/lnrpc.Lightning/ListPayments` | List all payments |
+| `uri:/lnrpc.Lightning/ConnectPeer` | Connect to a peer |
+| `uri:/lnrpc.Lightning/OpenChannelSync` | Open a channel |
+| `uri:/lnrpc.Lightning/CloseChannel` | Close a channel |
+| `uri:/signrpc.Signer/SignOutputRaw` | Sign a transaction output |
+| `uri:/signrpc.Signer/ComputeInputScript` | Compute input script for signing |
+| `uri:/signrpc.Signer/MuSig2Sign` | MuSig2 signing |
+| `uri:/walletrpc.WalletKit/DeriveKey` | Derive a key |
+| `uri:/walletrpc.WalletKit/DeriveNextKey` | Derive next key in sequence |