@lightninglabs/lightning-mcp-server 0.2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lightninglabs/lightning-mcp-server",
+  "version": "0.2.0",
+  "description": "Lightning Network agent toolkit for Claude Code — MCP server, L402 payments, node operations, and 7 composable skills",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lightninglabs/lightning-agent-kit"
+  },
+  "homepage": "https://github.com/lightninglabs/lightning-agent-kit#quick-start",
+  "keywords": [
+    "lightning",
+    "lightning-network",
+    "lnc",
+    "l402",
+    "mcp",
+    "claude-code",
+    "bitcoin",
+    "lnd",
+    "aperture",
+    "agent"
+  ],
+  "bin": {
+    "lightning-mcp-server": "./bin/lightning-mcp-server"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "docs/",
+    ".claude-plugin/",
+    ".claude/",
+    "postinstall.js",
+    "versions.env",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/postinstall.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+// postinstall.js downloads the pre-built lightning-mcp-server binary for the
+// current platform and architecture from GitHub Releases. This follows the
+// same pattern used by esbuild, turbo, and other Go/Rust projects distributed
+// via npm.
+//
+// The binary is placed in bin/ so the npm "bin" entry in package.json can
+// reference it directly, making `npx lightning-mcp-server` work out of the
+// box.
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const os = require("os");
+
+// PLATFORM_MAP translates Node.js platform/arch identifiers to the Go build
+// system naming convention used by the release workflow.
+const PLATFORM_MAP = {
+	"darwin-arm64": "darwin-arm64",
+	"darwin-x64": "darwin-amd64",
+	"linux-arm64": "linux-arm64",
+	"linux-x64": "linux-amd64",
+	"win32-x64": "windows-amd64",
+};
+
+// REPO is the GitHub repository that hosts the release binaries.
+const REPO = "lightninglabs/lightning-agent-kit";
+
+// BINARY_NAME is the name of the binary inside the release tarball.
+const BINARY_NAME = "lightning-mcp-server";
+
+// getPackageVersion reads the version from package.json to determine which
+// GitHub release tag to download from.
+function getPackageVersion() {
+	const pkg = JSON.parse(
+		fs.readFileSync(path.join(__dirname, "package.json"), "utf8"),
+	);
+	return pkg.version;
+}
+
+// getPlatformKey returns the platform-architecture key for the current
+// system, e.g. "darwin-arm64" or "linux-x64".
+function getPlatformKey() {
+	const platform = os.platform();
+	const arch = os.arch();
+	return `${platform}-${arch}`;
+}
+
+// getBinaryPath returns the file path where the downloaded binary will be
+// placed within the package's bin directory.
+function getBinaryPath() {
+	const ext = os.platform() === "win32" ? ".exe" : "";
+	return path.join(__dirname, "bin", `${BINARY_NAME}${ext}`);
+}
+
+// fetchBuffer follows HTTP redirects (GitHub Releases redirects to a CDN)
+// and returns the final response body as a buffer.
+function fetchBuffer(url) {
+	return new Promise((resolve, reject) => {
+		const opts = { headers: { "User-Agent": "npm-postinstall" } };
+		https.get(url, opts, (res) => {
+			if (res.statusCode >= 300 && res.statusCode < 400 &&
+				res.headers.location) {
+				fetchBuffer(res.headers.location)
+					.then(resolve, reject);
+				return;
+			}
+			if (res.statusCode !== 200) {
+				reject(new Error(
+					`Download failed: HTTP ${res.statusCode} ` +
+					`from ${url}`,
+				));
+				return;
+			}
+			const chunks = [];
+			res.on("data", (chunk) => chunks.push(chunk));
+			res.on("end", () => resolve(Buffer.concat(chunks)));
+			res.on("error", reject);
+		}).on("error", reject);
+	});
+}
+
+// extractTarGz extracts a .tar.gz buffer to the specified directory using
+// the system tar command. The binary is expected at the root of the archive.
+function extractTarGz(buffer, destDir) {
+	const tmpFile = path.join(
+		os.tmpdir(), `${BINARY_NAME}-${Date.now()}.tar.gz`,
+	);
+	fs.writeFileSync(tmpFile, buffer);
+	try {
+		execSync(`tar xzf "${tmpFile}" -C "${destDir}"`, {
+			stdio: "pipe",
+		});
+	} finally {
+		fs.unlinkSync(tmpFile);
+	}
+}
+
+// main downloads and installs the correct binary for the current platform.
+async function main() {
+	const platformKey = getPlatformKey();
+	const goTarget = PLATFORM_MAP[platformKey];
+
+	if (!goTarget) {
+		console.error(
+			`Unsupported platform: ${platformKey}. ` +
+			`Supported: ${Object.keys(PLATFORM_MAP).join(", ")}`,
+		);
+		console.error(
+			"You can build from source instead:\n" +
+			"  cd mcp-server && make build",
+		);
+		process.exit(1);
+	}
+
+	const version = getPackageVersion();
+	const tag = `v${version}`;
+	const assetName = `${BINARY_NAME}-${goTarget}.tar.gz`;
+	const url =
+		`https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
+
+	console.log(
+		`Downloading ${BINARY_NAME} ${tag} for ${goTarget}...`,
+	);
+
+	try {
+		const buffer = await fetchBuffer(url);
+
+		// Ensure the bin directory exists before extracting.
+		const binDir = path.join(__dirname, "bin");
+		fs.mkdirSync(binDir, { recursive: true });
+
+		extractTarGz(buffer, binDir);
+
+		// Make the binary executable on Unix systems.
+		const binaryPath = getBinaryPath();
+		if (os.platform() !== "win32") {
+			fs.chmodSync(binaryPath, 0o755);
+		}
+
+		console.log(`Installed ${BINARY_NAME} to ${binaryPath}`);
+	} catch (err) {
+		console.error(
+			`Failed to download ${BINARY_NAME}: ${err.message}`,
+		);
+		console.error("");
+		console.error("You can build from source instead:");
+		console.error("  cd mcp-server && make build");
+		console.error("");
+		console.error(
+			"Or download from: " +
+			`https://github.com/${REPO}/releases/tag/${tag}`,
+		);
+		process.exit(1);
+	}
+}
+
+main();

package/skills/aperture/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: aperture
+description: Install and run Aperture, the L402 Lightning reverse proxy from Lightning Labs. Use when creating L402 paywalls, configuring paid API endpoints, hosting paid content for other agents, or testing L402 authentication flows.
+---
+
+# Aperture - L402 Lightning Reverse Proxy
+
+Aperture is a reverse proxy that implements the L402 protocol, enabling
+payment-gated API access via the Lightning Network. It sits in front of your
+backend services and requires Lightning micropayments before granting access.
+
+**Source:** `github.com/lightninglabs/aperture`
+
+## Quick Start
+
+```bash
+# 1. Install aperture
+skills/aperture/scripts/install.sh
+
+# 2. Generate config (connects to local lnd)
+skills/aperture/scripts/setup.sh
+
+# 3. Start aperture
+skills/aperture/scripts/start.sh
+
+# 4. Test with lnget
+lnget -k --no-pay https://localhost:8081/api/test
+```
+
+## How Aperture Works
+
+1. Client requests a protected resource through Aperture
+2. Aperture responds with HTTP 402 + `WWW-Authenticate: L402` header containing
+   a macaroon and a Lightning invoice
+3. Client pays the invoice and obtains the preimage
+4. Client retries with `Authorization: L402 <macaroon>:<preimage>`
+5. Aperture validates the token and proxies to the backend service
+
+## Installation
+
+```bash
+skills/aperture/scripts/install.sh
+```
+
+This will:
+- Verify Go is installed
+- Run `go install github.com/lightninglabs/aperture/cmd/aperture@latest`
+- Verify `aperture` is on `$PATH`
+
+To install manually:
+
+```bash
+go install github.com/lightninglabs/aperture/cmd/aperture@latest
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/lightninglabs/aperture.git
+cd aperture
+make install
+```
+
+## Setup
+
+```bash
+skills/aperture/scripts/setup.sh
+```
+
+This generates `~/.aperture/aperture.yaml` from the config template with
+sensible defaults. The setup script auto-detects the local lnd node paths.
+
+**Options:**
+
+```bash
+# Custom network
+setup.sh --network testnet
+
+# Custom lnd paths
+setup.sh --lnd-host localhost:10009 \
+         --lnd-tls ~/.lnd/tls.cert \
+         --lnd-macdir ~/.lnd/data/chain/bitcoin/mainnet
+
+# Custom listen port
+setup.sh --port 8081
+
+# Disable TLS (development only)
+setup.sh --insecure
+
+# Disable auth (no payments required)
+setup.sh --no-auth
+```
+
+## Running Aperture
+
+### Start
+
+```bash
+skills/aperture/scripts/start.sh
+```
+
+Starts aperture as a background process reading `~/.aperture/aperture.yaml`.
+
+**Options:**
+
+```bash
+start.sh --foreground         # Run in foreground
+start.sh --config /path/to   # Custom config path
+```
+
+### Stop
+
+```bash
+skills/aperture/scripts/stop.sh
+```
+
+## Configuration
+
+Config file: `~/.aperture/aperture.yaml`
+
+### Minimal Agent Configuration
+
+This is the minimal config for an agent hosting paid endpoints with a local
+lnd node:
+
+```yaml
+listenaddr: "localhost:8081"
+insecure: true
+debuglevel: "info"
+dbbackend: "sqlite"
+sqlite:
+  dbfile: "~/.aperture/aperture.db"
+
+authenticator:
+  network: "mainnet"
+  lndhost: "localhost:10009"
+  tlspath: "~/.lnd/tls.cert"
+  macdir: "~/.lnd/data/chain/bitcoin/mainnet"
+
+services:
+  - name: "my-api"
+    hostregexp: ".*"
+    pathregexp: "^/api/.*$"
+    address: "127.0.0.1:8080"
+    protocol: http
+    price: 100
+```
+
+### Service Configuration
+
+Each service entry defines a backend to protect:
+
+```yaml
+services:
+  - name: "service-name"
+    # Match requests by host (regex).
+    hostregexp: "^api.example.com$"
+
+    # Match requests by path (regex).
+    pathregexp: "^/paid/.*$"
+
+    # Backend address to proxy to.
+    address: "127.0.0.1:8080"
+
+    # Protocol: http or https.
+    protocol: http
+
+    # Static price in satoshis.
+    price: 100
+
+    # Macaroon capabilities granted at base tier.
+    capabilities: "read,write"
+
+    # Token expiry in seconds (31557600 = 1 year).
+    timeout: 31557600
+
+    # Paths exempt from payment.
+    authwhitelistpaths:
+      - "^/health$"
+      - "^/public/.*$"
+
+    # Per-endpoint rate limits (token bucket).
+    ratelimits:
+      - pathregexp: "^/api/query.*$"
+        requests: 10
+        per: 1s
+        burst: 20
+```
+
+### Authentication Backends
+
+#### Direct LND Connection
+
+```yaml
+authenticator:
+  network: "mainnet"
+  lndhost: "localhost:10009"
+  tlspath: "~/.lnd/tls.cert"
+  macdir: "~/.lnd/data/chain/bitcoin/mainnet"
+```
+
+#### Lightning Node Connect (LNC)
+
+```yaml
+authenticator:
+  network: "mainnet"
+  passphrase: "your-pairing-phrase"
+  mailboxaddress: "mailbox.terminal.lightning.today:443"
+```
+
+#### Disable Authentication
+
+```yaml
+authenticator:
+  disable: true
+```
+
+### Database Backends
+
+**SQLite (recommended for agents):**
+
+```yaml
+dbbackend: "sqlite"
+sqlite:
+  dbfile: "~/.aperture/aperture.db"
+```
+
+**PostgreSQL:**
+
+```yaml
+dbbackend: "postgres"
+postgres:
+  host: "localhost"
+  port: 5432
+  user: "aperture"
+  password: "secret"
+  dbname: "aperture"
+```
+
+### TLS Configuration
+
+```yaml
+# Auto Let's Encrypt certificate.
+autocert: true
+servername: "api.example.com"
+
+# Or disable TLS (development/local only).
+insecure: true
+```
+
+If neither is set, Aperture generates self-signed certs in `~/.aperture/`.
+
+### Dynamic Pricing
+
+Connect to a gRPC price server instead of static prices:
+
+```yaml
+services:
+  - name: "my-api"
+    dynamicprice:
+      enabled: true
+      grpcaddress: "127.0.0.1:10010"
+      insecure: false
+      tlscertpath: "/path/to/pricer/tls.cert"
+```
+
+## Hosting Paid Content for Agents
+
+A common pattern is hosting information that other agents pay to access:
+
+```bash
+# 1. Start a simple HTTP backend with your content
+mkdir -p /tmp/paid-content
+echo '{"data": "valuable information"}' > /tmp/paid-content/info.json
+cd /tmp/paid-content && python3 -m http.server 8080 &
+
+# 2. Configure aperture to protect it
+skills/aperture/scripts/setup.sh --insecure --port 8081
+
+# 3. Start aperture
+skills/aperture/scripts/start.sh
+
+# 4. Other agents can now pay and fetch
+lnget --max-cost 100 https://localhost:8081/api/info.json
+```
+
+## Integration with lnget and lnd
+
+With all three components running:
+
+```bash
+# Verify lnd is running
+skills/lnd/scripts/lncli.sh getinfo
+
+# Start aperture (uses same lnd for invoice generation)
+skills/aperture/scripts/start.sh
+
+# Fetch a paid resource
+lnget --max-cost 1000 https://localhost:8081/api/data
+
+# Check tokens
+lnget tokens list
+```
+
+## File Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.aperture/aperture.yaml` | Configuration file |
+| `~/.aperture/aperture.db` | SQLite database |
+| `~/.aperture/tls.cert` | TLS certificate |
+| `~/.aperture/tls.key` | TLS private key |
+| `~/.aperture/aperture.log` | Log file |
+
+## Troubleshooting
+
+### Port already in use
+Change `listenaddr` in config to a different port, or use `setup.sh --port`.
+
+### LND connection refused
+Verify lnd is running and wallet is unlocked. Check `lndhost`, `tlspath`, and
+`macdir` in the config point to the correct lnd instance.
+
+### No 402 challenge returned
+Check that the request path matches a service's `pathregexp` and is not in
+`authwhitelistpaths`. Verify `authenticator.disable` is not `true`.
+
+### Token validation fails
+The client must present the exact macaroon from the challenge with the correct
+preimage. Verify the preimage matches the payment hash.

package/skills/aperture/scripts/install.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Install aperture from source.
+#
+# Usage:
+#   install.sh                          # Install latest
+#   install.sh --version v0.3.3-beta    # 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 aperture L402 reverse proxy."
+            echo ""
+            echo "Options:"
+            echo "  --version VERSION  Go module version (e.g., v0.3.3-beta)"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+echo "=== Installing Aperture ==="
+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 aperture.
+echo "Installing aperture..."
+go install "github.com/lightninglabs/aperture/cmd/aperture${VERSION}"
+echo "Done."
+echo ""
+
+# Verify installation.
+if command -v aperture &>/dev/null; then
+    echo "aperture installed: $(which aperture)"
+else
+    echo "Warning: aperture 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. Setup config: skills/aperture/scripts/setup.sh"
+echo "  2. Start:        skills/aperture/scripts/start.sh"