@lightninglabs/lightning-mcp-server 0.2.0

package/docs/mcp-server.md

@@ -0,0 +1,285 @@
+# MCP Server
+
+> Connecting AI assistants to Lightning nodes through the Model Context
+> Protocol and Lightning Node Connect.
+
+Lightning Agent Tools includes an MCP server that gives AI assistants
+read-only access to a Lightning node. It uses Lightning Node Connect (LNC) for
+transport, which means the assistant never needs direct network access to the
+node, never handles TLS certificates, and never stores macaroons on disk. A
+10-word pairing phrase is all it takes to establish an encrypted tunnel.
+
+The server exposes 18 tools, all read-only, that let an assistant query
+node status, inspect channels, decode invoices, look up payments, and explore
+the network graph. It cannot send payments, open channels, or modify any node
+state.
+
+## How LNC Works
+
+Lightning Node Connect establishes an end-to-end encrypted WebSocket tunnel
+between two parties through a mailbox relay server. Both the MCP server (on the
+agent's machine) and the lnd node (running Lightning Terminal) connect outbound
+to the mailbox. Neither needs to accept inbound connections, which means no
+firewall configuration and no port forwarding.
+
+```mermaid
+graph LR
+    CC["Claude Code<br/>(stdio)"] <--> MCP["mcp-lnc-server"]
+    MCP <-->|"encrypted<br/>WebSocket"| MB["Mailbox Relay<br/>mailbox.terminal.lightning.today"]
+    MB <-->|"encrypted<br/>WebSocket"| LND["lnd + Lightning Terminal"]
+
+    style MB fill:#f5f5f5,stroke:#999
+```
+
+Authentication works through a 10-word pairing phrase generated in Lightning
+Terminal. When the MCP server connects, it generates an ephemeral ECDSA keypair,
+uses the pairing phrase to derive a shared secret, and establishes the encrypted
+tunnel. The keypair exists only in memory for the duration of the session --
+when the connection closes, the keypair is discarded and no credentials remain
+on disk.
+
+The mailbox relay cannot read the traffic passing through it. It sees encrypted
+WebSocket frames and routes them between the two endpoints based on connection
+identifiers derived from the pairing phrase.
+
+## Setup
+
+Three scripts handle the full setup:
+
+### 1. Build the server
+
+```bash
+skills/mcp-lnc/scripts/install.sh
+```
+
+This compiles `mcp-lnc-server` from the `mcp-server/` directory in the
+repository and installs it to `$GOPATH/bin`. Requires Go 1.24+.
+
+### 2. Configure the environment
+
+```bash
+# Production (Lightning Terminal on mainnet)
+skills/mcp-lnc/scripts/configure.sh --production
+
+# Development (local regtest)
+skills/mcp-lnc/scripts/configure.sh --dev --mailbox aperture:11110
+```
+
+This generates `mcp-server/.env` with the following variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LNC_MAILBOX_SERVER` | `mailbox.terminal.lightning.today:443` | Mailbox relay address |
+| `LNC_DEV_MODE` | `false` | Enable development mode |
+| `LNC_INSECURE` | `false` | Skip TLS verification (dev only) |
+| `LNC_CONNECT_TIMEOUT` | `30` | Connection timeout in seconds |
+
+### 3. Register with Claude Code
+
+```bash
+# Project-level (recommended)
+skills/mcp-lnc/scripts/setup-claude-config.sh --scope project
+
+# Global
+skills/mcp-lnc/scripts/setup-claude-config.sh --scope global
+```
+
+This adds the MCP server to `.mcp.json` (project) or `~/.claude.json` (global).
+Restart Claude Code after running this script for the new tools to appear.
+
+The resulting configuration looks like:
+
+```json
+{
+  "mcpServers": {
+    "lnc": {
+      "command": "mcp-lnc-server",
+      "env": {
+        "LNC_MAILBOX_SERVER": "mailbox.terminal.lightning.today:443"
+      }
+    }
+  }
+}
+```
+
+### 4. Connect
+
+After restarting Claude Code, the `lnc_connect` tool becomes available. Connect
+with a pairing phrase from Lightning Terminal:
+
+```
+Connect to my Lightning node with pairing phrase: "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10"
+```
+
+The assistant will call `lnc_connect`, establish the tunnel, and then all 18
+read-only tools become operational.
+
+## Available Tools
+
+The server organizes its 18 tools into seven categories:
+
+### Connection
+
+| Tool | Description |
+|------|-------------|
+| `lnc_connect` | Establish LNC tunnel with a pairing phrase and password |
+| `lnc_disconnect` | Close the active tunnel and discard the ephemeral keypair |
+
+### Node
+
+| Tool | Description |
+|------|-------------|
+| `lnc_get_info` | Node alias, public key, version, sync status, current block height |
+| `lnc_get_balance` | On-chain wallet balance and total channel balance |
+
+### Channels
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_channels` | All open channels with capacity, local/remote balances, and activity |
+| `lnc_pending_channels` | Channels being opened, closed, or force-closed |
+
+### Invoices
+
+| Tool | Description |
+|------|-------------|
+| `lnc_decode_invoice` | Decode a BOLT11 payment request into its components |
+| `lnc_list_invoices` | Paginated list of created invoices with status |
+| `lnc_lookup_invoice` | Look up a specific invoice by payment hash |
+
+### Payments
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_payments` | Paginated payment history with status, amounts, and routes |
+| `lnc_track_payment` | Track a specific in-flight or completed payment by hash |
+
+### Peers and Network
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_peers` | Connected peers with addresses, bytes sent/received, and ping times |
+| `lnc_describe_graph` | Sample of the Lightning Network topology (nodes and channels) |
+| `lnc_get_node_info` | Detailed information about a specific node by public key |
+
+### On-Chain
+
+| Tool | Description |
+|------|-------------|
+| `lnc_list_unspent` | Unspent transaction outputs (UTXOs) with confirmation counts |
+| `lnc_get_transactions` | On-chain transaction history |
+| `lnc_estimate_fee` | Fee rate estimates for target confirmation windows |
+
+## MCP-LNC vs Direct gRPC
+
+The MCP server and direct gRPC access (via `lncli` or the `lnd` skill) serve
+different purposes:
+
+| | MCP-LNC | Direct gRPC |
+|---|---------|-------------|
+| **Credentials** | 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 |
+| **Capabilities** | Read-only (18 query tools) | Full node control |
+| **Permissions** | Hardcoded read-only | Configurable via macaroon scope |
+| **Setup** | Pairing phrase from Lightning Terminal | Export TLS cert and macaroon files |
+
+**Use MCP-LNC when** the agent only needs to observe node state: checking
+balances, listing channels, monitoring payments, inspecting the network graph.
+The read-only constraint and lack of stored credentials make it the safest
+option for giving an AI assistant access to node data.
+
+**Use direct gRPC when** the agent needs to perform actions: sending payments,
+opening channels, creating invoices. Direct gRPC requires the `lnd` skill and
+appropriate macaroons (scoped via `macaroon-bakery`).
+
+## Server Internals
+
+The MCP server is a Go application in the `mcp-server/` directory. It runs on
+stdio transport. The MCP client launches it as a subprocess and communicates over
+stdin/stdout.
+
+The entry point (`daemon.go`) handles signal-based shutdown (SIGINT, SIGTERM)
+with a graceful timeout. The server (`server.go`) initializes a service manager
+(`internal/services/manager.go`) that creates one service per tool category and
+registers all 18 tools with the
+[MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk).
+
+When `lnc_connect` is called, the manager creates a Lightning client using the
+LNC library (`github.com/lightninglabs/lightning-node-connect/mailbox`),
+establishes the tunnel, and distributes the client to all services via the
+`onLNCConnectionEstablished` callback. When `lnc_disconnect` is called, the
+connection is closed and all services are reset.
+
+### Building from Source
+
+```bash
+cd mcp-server
+make build           # debug binary
+make build-release   # optimized binary
+make install         # install to $GOPATH/bin
+make check           # run fmt, lint, mod-check, and unit tests
+```
+
+### Docker
+
+For containerized deployment:
+
+```bash
+cd mcp-server
+make docker-build
+```
+
+The Docker configuration in `.mcp.json`:
+
+```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"
+      ]
+    }
+  }
+}
+```
+
+## Development Setup
+
+For local regtest environments, enable development mode to skip TLS verification
+and connect to a local mailbox:
+
+```bash
+skills/mcp-lnc/scripts/configure.sh --dev --mailbox localhost:11110 --insecure
+```
+
+This sets `LNC_DEV_MODE=true` and `LNC_INSECURE=true` in the `.env` file.
+
+### Prerequisites
+
+- **Go 1.24+** for building from source
+- **Lightning Terminal** (litd) on the target lnd node for generating pairing
+  phrases
+- **Claude Code** for MCP integration
+
+### Troubleshooting
+
+**"pairing phrase must be exactly 10 words"**: The pairing phrase is generated
+in Lightning Terminal's Sessions UI. It must be exactly 10 space-separated
+words.
+
+**"connection timeout"**: Verify the mailbox server is reachable. For
+production, this is `mailbox.terminal.lightning.today:443`. For local
+development, ensure the local mailbox is running.
+
+**"TLS handshake failure"**: For local regtest, enable insecure mode:
+`skills/mcp-lnc/scripts/configure.sh --dev --insecure`
+
+**Tools not appearing in Claude Code**: Restart Claude Code after running
+`setup-claude-config.sh`. Verify the binary is on your PATH with
+`which mcp-lnc-server`.

package/docs/quickref.md

@@ -0,0 +1,263 @@
+# Quick Reference
+
+> Every important command in one place.
+
+## Installation
+
+```bash
+# Docker image pull is the default; add --source to build from source instead.
+skills/lnd/scripts/install.sh                              # litd container image
+skills/lnget/scripts/install.sh                            # lnget CLI (always built from source)
+skills/aperture/scripts/install.sh                         # aperture (always built from source)
+skills/mcp-lnc/scripts/install.sh                          # MCP server (always built from source)
+skills/lightning-security-module/scripts/install.sh         # lnd signer container image
+```
+
+## Node Operations
+
+```bash
+# Start/stop (Docker container by default; --native for local binary)
+skills/lnd/scripts/start-lnd.sh                            # start litd container (standalone)
+skills/lnd/scripts/start-lnd.sh --watchonly                # watch-only + signer containers
+skills/lnd/scripts/start-lnd.sh --regtest                  # regtest + bitcoind containers
+skills/lnd/scripts/start-lnd.sh --profile debug            # start with debug logging profile
+skills/lnd/scripts/docker-start.sh --list-profiles         # list available profiles
+skills/lnd/scripts/stop-lnd.sh                             # stop containers
+skills/lnd/scripts/stop-lnd.sh --clean                     # stop + remove Docker volumes
+
+# Node queries (auto-detects containers)
+skills/lnd/scripts/lncli.sh getinfo                        # node status
+skills/lnd/scripts/lncli.sh walletbalance                  # on-chain balance
+skills/lnd/scripts/lncli.sh channelbalance                 # channel balance
+skills/lnd/scripts/unlock-wallet.sh                        # unlock after restart
+```
+
+## Wallet
+
+```bash
+# Watch-only with Docker (signer on Docker network, no --signer-host needed)
+skills/lnd/scripts/import-credentials.sh --bundle <path>
+skills/lnd/scripts/create-wallet.sh                        # auto-detects container
+
+# Watch-only with native (signer on separate machine)
+skills/lnd/scripts/import-credentials.sh --bundle <path>
+skills/lnd/scripts/create-wallet.sh --native --signer-host <ip>:10012
+
+# Standalone (testing, generates local seed)
+skills/lnd/scripts/create-wallet.sh --mode standalone
+
+# Funding
+skills/lnd/scripts/lncli.sh newaddress p2tr               # generate address
+skills/lnd/scripts/lncli.sh walletbalance                  # check balance
+```
+
+## Channels
+
+```bash
+skills/lnd/scripts/lncli.sh connect <pubkey>@<host>:9735                      # connect to peer
+skills/lnd/scripts/lncli.sh openchannel --node_key=<pubkey> --local_amt=N      # open channel
+skills/lnd/scripts/lncli.sh listchannels                                       # list channels
+skills/lnd/scripts/lncli.sh pendingchannels                                    # pending opens/closes
+skills/lnd/scripts/lncli.sh closechannel --funding_txid=<txid> --output_index=N  # close channel
+skills/lnd/scripts/lncli.sh listpeers                                          # connected peers
+skills/lnd/scripts/lncli.sh disconnect <pubkey>                                # disconnect peer
+```
+
+## Payments
+
+```bash
+skills/lnd/scripts/lncli.sh addinvoice --amt=1000 --memo="description"    # create invoice
+skills/lnd/scripts/lncli.sh decodepayreq <bolt11>                          # decode invoice
+skills/lnd/scripts/lncli.sh sendpayment --pay_req=<bolt11>                 # pay invoice
+skills/lnd/scripts/lncli.sh listpayments                                   # payment history
+skills/lnd/scripts/lncli.sh listinvoices                                   # invoice history
+```
+
+## Macaroon Bakery
+
+```bash
+# Preset roles
+skills/macaroon-bakery/scripts/bake.sh --role pay-only
+skills/macaroon-bakery/scripts/bake.sh --role invoice-only
+skills/macaroon-bakery/scripts/bake.sh --role read-only
+skills/macaroon-bakery/scripts/bake.sh --role channel-admin
+skills/macaroon-bakery/scripts/bake.sh --role signer-only
+
+# Custom
+skills/macaroon-bakery/scripts/bake.sh --custom \
+    uri:/lnrpc.Lightning/SendPaymentSync \
+    uri:/lnrpc.Lightning/DecodePayReq \
+    uri:/lnrpc.Lightning/GetInfo
+
+# Inspect
+skills/macaroon-bakery/scripts/bake.sh --inspect <path-to-macaroon>
+
+# List all available permissions
+skills/macaroon-bakery/scripts/bake.sh --list-permissions
+
+# Save to specific path
+skills/macaroon-bakery/scripts/bake.sh --role pay-only --save-to ~/agent.macaroon
+```
+
+## lnget
+
+```bash
+# Fetch
+lnget https://api.example.com/data.json                   # fetch to stdout
+lnget -o data.json https://api.example.com/data.json       # fetch to file
+lnget -q https://api.example.com/data.json | jq .          # quiet mode, pipe
+lnget -X POST -d '{"q":"test"}' https://api.example.com    # POST with body
+
+# Cost control
+lnget --max-cost 500 https://api.example.com/data          # max auto-pay amount
+lnget --no-pay https://api.example.com/data                # preview without paying
+lnget --no-pay --json https://... | jq '.invoice_amount_sat'  # check price
+
+# Tokens
+lnget tokens list                                          # list cached tokens
+lnget tokens show api.example.com                          # show specific token
+lnget tokens remove api.example.com                        # force re-payment
+lnget tokens clear --force                                 # clear all tokens
+
+# Configuration
+lnget config init                                          # initialize config
+lnget config show                                          # show current config
+
+# Backend status
+lnget ln status                                            # connection status
+lnget ln info                                              # backend info
+
+# LNC pairing
+lnget ln lnc pair "ten word pairing phrase here"           # pair with LNC
+lnget ln lnc sessions                                      # list LNC sessions
+lnget ln lnc revoke <session-id>                           # revoke session
+
+# Neutrino (embedded wallet)
+lnget ln neutrino init                                     # initialize
+lnget ln neutrino fund                                     # funding address
+lnget ln neutrino balance                                  # check balance
+```
+
+## Aperture
+
+```bash
+skills/aperture/scripts/setup.sh                           # generate config
+skills/aperture/scripts/setup.sh --insecure --port 8081    # dev mode
+skills/aperture/scripts/setup.sh --network testnet         # testnet
+skills/aperture/scripts/start.sh                           # start proxy
+skills/aperture/scripts/stop.sh                            # stop proxy
+```
+
+## MCP Server
+
+```bash
+skills/mcp-lnc/scripts/install.sh                         # build from source
+skills/mcp-lnc/scripts/configure.sh                        # generate .env
+skills/mcp-lnc/scripts/configure.sh --production           # mainnet config
+skills/mcp-lnc/scripts/configure.sh --dev --insecure       # regtest config
+skills/mcp-lnc/scripts/setup-claude-config.sh --scope project   # add to .mcp.json
+skills/mcp-lnc/scripts/setup-claude-config.sh --scope global    # add to ~/.claude.json
+```
+
+## Remote Signer
+
+```bash
+# On signer machine (Docker container by default)
+skills/lightning-security-module/scripts/install.sh        # pull lnd signer image
+skills/lightning-security-module/scripts/setup-signer.sh   # create wallet + export creds (auto-detects container)
+skills/lightning-security-module/scripts/start-signer.sh   # start signer container
+skills/lightning-security-module/scripts/stop-signer.sh    # stop signer container
+skills/lightning-security-module/scripts/stop-signer.sh --clean  # stop + remove volumes
+skills/lightning-security-module/scripts/export-credentials.sh   # re-export bundle
+
+# On agent machine (Docker)
+skills/lnd/scripts/import-credentials.sh --bundle <path>
+skills/lnd/scripts/create-wallet.sh                        # auto-detects container
+skills/lnd/scripts/start-lnd.sh --watchonly                # watch-only + signer containers
+
+# On agent machine (native, signer on separate host)
+skills/lnd/scripts/import-credentials.sh --bundle <path>
+skills/lnd/scripts/create-wallet.sh --native --signer-host <ip>:10012
+skills/lnd/scripts/start-lnd.sh --native --signer-host <ip>:10012
+
+# Scope signer macaroon (container or native)
+skills/macaroon-bakery/scripts/bake.sh --role signer-only --container litd-signer
+skills/macaroon-bakery/scripts/bake.sh --role signer-only --rpc-port 10012 --lnddir ~/.lnd-signer
+```
+
+## Docker Containers
+
+Docker is the default deployment method. Container lifecycle:
+
+```bash
+# Lifecycle (these are the primary entry points)
+skills/lnd/scripts/start-lnd.sh                            # standalone litd container
+skills/lnd/scripts/start-lnd.sh --watchonly                # litd + signer containers
+skills/lnd/scripts/start-lnd.sh --regtest                  # litd + bitcoind containers
+skills/lnd/scripts/start-lnd.sh --regtest --profile debug  # regtest with debug logging
+skills/lnd/scripts/stop-lnd.sh                             # stop all mode containers
+skills/lnd/scripts/stop-lnd.sh --clean                     # stop + remove volumes
+skills/lnd/scripts/docker-start.sh --list-profiles         # show available profiles
+```
+
+All `lncli` and bakery commands auto-detect running containers. Use `--container`
+to target a specific container by name:
+
+```bash
+skills/lnd/scripts/lncli.sh getinfo                        # auto-detects litd container
+skills/lnd/scripts/lncli.sh --container litd-bob getinfo   # target specific container
+skills/macaroon-bakery/scripts/bake.sh --role pay-only --container litd
+skills/lightning-security-module/scripts/export-credentials.sh --container litd-signer
+```
+
+## Remote Nodes
+
+All scripts support direct connection to remote lnd nodes:
+
+```bash
+skills/lnd/scripts/lncli.sh \
+    --rpcserver remote-host:10009 \
+    --tlscertpath ~/remote-tls.cert \
+    --macaroonpath ~/remote-admin.macaroon \
+    getinfo
+
+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
+```
+
+## File Paths
+
+| Path | Purpose |
+|------|---------|
+| `~/.lnget/lnd/lnd.conf` | lnd configuration |
+| `~/.lnget/lnd/wallet-password.txt` | Wallet passphrase (0600) |
+| `~/.lnget/lnd/seed.txt` | Wallet seed, standalone only (0600) |
+| `~/.lnget/lnd/signer-credentials/` | Imported signer credentials |
+| `~/.lnget/signer/signer-lnd.conf` | Signer configuration |
+| `~/.lnget/signer/wallet-password.txt` | Signer passphrase (0600) |
+| `~/.lnget/signer/seed.txt` | Signer seed (0600) |
+| `~/.lnget/signer/credentials-bundle/` | Exported signer credentials |
+| `~/.lnget/config.yaml` | lnget configuration |
+| `~/.lnget/tokens/<domain>/` | L402 cached tokens |
+| `~/.lnd/` | lnd data (chain, macaroons, TLS) |
+| `~/.lnd/data/chain/bitcoin/<network>/admin.macaroon` | Admin macaroon |
+| `~/.lnd/tls.cert` | lnd TLS certificate |
+| `~/.lnd-signer/` | Signer lnd data |
+| `~/.aperture/aperture.yaml` | Aperture configuration |
+| `~/.aperture/aperture.db` | Aperture token database |
+| `mcp-server/.env` | MCP server config |
+
+## Ports
+
+| Port | Service | Daemon |
+|------|---------|--------|
+| 8443 | HTTPS (UI + gRPC + REST) | litd (container) |
+| 9735 | Lightning P2P | lnd |
+| 10009 | gRPC | lnd |
+| 8080 | REST | lnd |
+| 10012 | gRPC | signer lnd |
+| 10013 | REST | signer lnd |
+| 8081 | HTTP/L402 | aperture (configurable) |