boltwork-mcp 0.1.0__tar.gz

boltwork_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: boltwork-mcp
+Version: 0.1.0
+Summary: MCP server for Boltwork — AI services via Bitcoin Lightning. PDF summarisation, code review, translation, and more.
+Project-URL: Homepage, https://github.com/Squidboy30/boltwork-mcp
+Project-URL: Repository, https://github.com/Squidboy30/boltwork-mcp
+Project-URL: Issues, https://github.com/Squidboy30/boltwork-mcp/issues
+Project-URL: API, https://parsebit.fly.dev
+Author-email: Cracked Minds <hello@crackedminds.co.uk>
+License: MIT
+Keywords: agents,ai,bitcoin,code-review,l402,lightning,mcp,model-context-protocol,pdf,summarisation,translation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: nwc
+Requires-Dist: pynostr>=0.6.0; extra == 'nwc'
+Requires-Dist: websockets>=12.0; extra == 'nwc'
+Description-Content-Type: text/markdown
+
+# boltwork-mcp
+
+**MCP server for Boltwork — AI services that pay for themselves via Bitcoin Lightning.**
+
+Give your AI agent PDF summarisation, code review, translation, web extraction, document comparison, and persistent memory — all paid autonomously in sats. No API keys. No subscriptions. No accounts.
+
+[![PyPI](https://img.shields.io/pypi/v/boltwork-mcp)](https://pypi.org/project/boltwork-mcp/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![API](https://img.shields.io/badge/API-parsebit.fly.dev-green)](https://parsebit.fly.dev)
+
+---
+
+## What this is
+
+[Boltwork](https://parsebit.fly.dev) is a pay-per-call AI services API that uses the [L402 protocol](https://github.com/lightninglabs/L402) — your agent makes a request, receives a Lightning invoice, pays it automatically, and gets the result back. No human involved.
+
+This package wraps Boltwork as an [MCP server](https://modelcontextprotocol.io) so any MCP-compatible AI (Claude, Cursor, Windsurf, etc.) can use it as a tool — with payments handled transparently in the background.
+
+## Install
+
+```bash
+pip install boltwork-mcp
+
+# If using NWC (Nostr Wallet Connect):
+pip install "boltwork-mcp[nwc]"
+```
+
+Or use directly with `uvx` — no install needed:
+
+```bash
+uvx boltwork-mcp
+```
+
+## Setup
+
+### 1. Get a Lightning wallet
+
+You need a Lightning wallet that supports either:
+
+**Option A — NWC (recommended, easiest)**
+- [Alby](https://getalby.com) — browser extension, free, gives you an NWC connection string
+- [Mutiny Wallet](https://mutinywallet.com) — self-custodial mobile wallet
+
+**Option B — Phoenixd**
+- [Phoenixd](https://phoenix.acinq.co/server) — self-hosted Lightning node, simple REST API
+
+### 2. Add to your MCP config
+
+**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "boltwork": {
+      "command": "uvx",
+      "args": ["boltwork-mcp"],
+      "env": {
+        "NWC_CONNECTION_STRING": "nostr+walletconnect://your-connection-string-here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — edit `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "boltwork": {
+      "command": "uvx",
+      "args": ["boltwork-mcp"],
+      "env": {
+        "NWC_CONNECTION_STRING": "nostr+walletconnect://your-connection-string-here"
+      }
+    }
+  }
+}
+```
+
+**Using Phoenixd instead of NWC:**
+
+```json
+{
+  "mcpServers": {
+    "boltwork": {
+      "command": "uvx",
+      "args": ["boltwork-mcp"],
+      "env": {
+        "PHOENIXD_URL": "http://localhost:9740",
+        "PHOENIXD_PASSWORD": "your-phoenixd-password"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart your AI and start using tools
+
+That's it. Your agent now has access to all Boltwork tools and will pay invoices automatically when it uses them.
+
+---
+
+## Available tools
+
+| Tool | What it does | Cost |
+|------|-------------|------|
+| `summarise_pdf` | Summarise a PDF from URL | 500 sats |
+| `review_code` | Review code for bugs, security, quality | 2000 sats |
+| `review_code_url` | Review code from GitHub/GitLab URL | 2000 sats |
+| `summarise_webpage` | Summarise any web page | 100 sats |
+| `extract_data` | Extract structured data from PDF | 200 sats |
+| `translate` | Translate text or document to 24 languages | 150 sats |
+| `extract_tables` | Extract tables from PDF as structured JSON | 300 sats |
+| `compare_documents` | Diff two PDFs | 500 sats |
+| `explain_code` | Explain code in plain English | 500 sats |
+| `memory_store` | Store persistent key-value memory | 10 sats |
+| `memory_retrieve` | Read stored memory | 5 sats |
+| `memory_delete` | Delete a memory key | free |
+| `run_workflow` | Chain services in a single pipeline | 1000 sats |
+
+---
+
+## Example prompts
+
+Once configured, just talk to your AI naturally:
+
+```
+"Summarise this research paper: https://arxiv.org/pdf/2301.00000"
+
+"Review the code at https://github.com/me/repo/blob/main/app.py"
+
+"Translate this contract to Spanish: https://example.com/contract.pdf"
+
+"Compare these two versions of our terms of service:
+  v1: https://example.com/tos-v1.pdf
+  v2: https://example.com/tos-v2.pdf"
+
+"Remember that the last file I asked you to review was app.py 
+ and the score was 7/10"
+```
+
+Your agent handles the payment automatically — you just see the result.
+
+---
+
+## Workflow pipelines
+
+Chain multiple services in one call with `run_workflow`:
+
+```
+"Fetch the Bitcoin whitepaper, translate the summary to French,
+ and store the translation in my agent memory"
+```
+
+The `$from` syntax passes outputs between steps:
+
+```json
+{
+  "steps": [
+    {"service": "pdf",       "input": {"url": "https://bitcoin.org/bitcoin.pdf"}},
+    {"service": "translate", "input": {"text": {"$from": 0}, "target_language": "french"}}
+  ]
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NWC_CONNECTION_STRING` | One of these two | Nostr Wallet Connect string from Alby/Mutiny |
+| `PHOENIXD_URL` | One of these two | Phoenixd base URL e.g. `http://localhost:9740` |
+| `PHOENIXD_PASSWORD` | With Phoenixd | Phoenixd HTTP Basic auth password |
+| `BOLTWORK_GATEWAY` | Optional | Override gateway URL (default: `https://parsebit-lnd.fly.dev`) |
+
+---
+
+## Pricing
+
+All prices are in satoshis (sats). At current rates, 1000 sats ≈ $0.60 — but this varies with Bitcoin's price.
+
+There is no subscription, no monthly fee, no minimum spend. You pay exactly for what your agent uses, nothing more.
+
+---
+
+## How L402 works
+
+1. Agent calls a Boltwork tool
+2. `boltwork-mcp` sends the request to `parsebit-lnd.fly.dev`
+3. Receives HTTP 402 with a Lightning invoice (e.g. 500 sats for PDF summarisation)
+4. Pays the invoice via your configured wallet (NWC or Phoenixd)
+5. Retries the request with the payment proof
+6. Returns the result to your agent
+
+The whole flow takes 1-3 seconds. Your agent sees only the final result.
+
+---
+
+## Try before you pay
+
+Boltwork has free trial endpoints — no Lightning wallet needed:
+
+```bash
+curl -X POST https://parsebit.fly.dev/trial/review \
+  -H "Content-Type: application/json" \
+  -d '{"code": "def add(a, b): return a + b"}'
+```
+
+---
+
+## Links
+
+- [Boltwork API](https://parsebit.fly.dev) — the service this MCP server wraps
+- [Agent spec](https://parsebit.fly.dev/agent-spec.md) — full API reference
+- [L402 Index](https://402index.io) — directory of L402 services
+- [MCP documentation](https://modelcontextprotocol.io) — learn about MCP
+- [Cracked Minds](https://crackedminds.co.uk) — the team behind Boltwork
+
+---
+
+## License
+
+MIT

boltwork_mcp-0.1.0/README.md

@@ -0,0 +1,226 @@
+# boltwork-mcp
+
+**MCP server for Boltwork — AI services that pay for themselves via Bitcoin Lightning.**
+
+Give your AI agent PDF summarisation, code review, translation, web extraction, document comparison, and persistent memory — all paid autonomously in sats. No API keys. No subscriptions. No accounts.
+
+[![PyPI](https://img.shields.io/pypi/v/boltwork-mcp)](https://pypi.org/project/boltwork-mcp/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![API](https://img.shields.io/badge/API-parsebit.fly.dev-green)](https://parsebit.fly.dev)
+
+---
+
+## What this is
+
+[Boltwork](https://parsebit.fly.dev) is a pay-per-call AI services API that uses the [L402 protocol](https://github.com/lightninglabs/L402) — your agent makes a request, receives a Lightning invoice, pays it automatically, and gets the result back. No human involved.
+
+This package wraps Boltwork as an [MCP server](https://modelcontextprotocol.io) so any MCP-compatible AI (Claude, Cursor, Windsurf, etc.) can use it as a tool — with payments handled transparently in the background.
+
+## Install
+
+```bash
+pip install boltwork-mcp
+
+# If using NWC (Nostr Wallet Connect):
+pip install "boltwork-mcp[nwc]"
+```
+
+Or use directly with `uvx` — no install needed:
+
+```bash
+uvx boltwork-mcp
+```
+
+## Setup
+
+### 1. Get a Lightning wallet
+
+You need a Lightning wallet that supports either:
+
+**Option A — NWC (recommended, easiest)**
+- [Alby](https://getalby.com) — browser extension, free, gives you an NWC connection string
+- [Mutiny Wallet](https://mutinywallet.com) — self-custodial mobile wallet
+
+**Option B — Phoenixd**
+- [Phoenixd](https://phoenix.acinq.co/server) — self-hosted Lightning node, simple REST API
+
+### 2. Add to your MCP config
+
+**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "boltwork": {
+      "command": "uvx",
+      "args": ["boltwork-mcp"],
+      "env": {
+        "NWC_CONNECTION_STRING": "nostr+walletconnect://your-connection-string-here"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — edit `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "boltwork": {
+      "command": "uvx",
+      "args": ["boltwork-mcp"],
+      "env": {
+        "NWC_CONNECTION_STRING": "nostr+walletconnect://your-connection-string-here"
+      }
+    }
+  }
+}
+```
+
+**Using Phoenixd instead of NWC:**
+
+```json
+{
+  "mcpServers": {
+    "boltwork": {
+      "command": "uvx",
+      "args": ["boltwork-mcp"],
+      "env": {
+        "PHOENIXD_URL": "http://localhost:9740",
+        "PHOENIXD_PASSWORD": "your-phoenixd-password"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart your AI and start using tools
+
+That's it. Your agent now has access to all Boltwork tools and will pay invoices automatically when it uses them.
+
+---
+
+## Available tools
+
+| Tool | What it does | Cost |
+|------|-------------|------|
+| `summarise_pdf` | Summarise a PDF from URL | 500 sats |
+| `review_code` | Review code for bugs, security, quality | 2000 sats |
+| `review_code_url` | Review code from GitHub/GitLab URL | 2000 sats |
+| `summarise_webpage` | Summarise any web page | 100 sats |
+| `extract_data` | Extract structured data from PDF | 200 sats |
+| `translate` | Translate text or document to 24 languages | 150 sats |
+| `extract_tables` | Extract tables from PDF as structured JSON | 300 sats |
+| `compare_documents` | Diff two PDFs | 500 sats |
+| `explain_code` | Explain code in plain English | 500 sats |
+| `memory_store` | Store persistent key-value memory | 10 sats |
+| `memory_retrieve` | Read stored memory | 5 sats |
+| `memory_delete` | Delete a memory key | free |
+| `run_workflow` | Chain services in a single pipeline | 1000 sats |
+
+---
+
+## Example prompts
+
+Once configured, just talk to your AI naturally:
+
+```
+"Summarise this research paper: https://arxiv.org/pdf/2301.00000"
+
+"Review the code at https://github.com/me/repo/blob/main/app.py"
+
+"Translate this contract to Spanish: https://example.com/contract.pdf"
+
+"Compare these two versions of our terms of service:
+  v1: https://example.com/tos-v1.pdf
+  v2: https://example.com/tos-v2.pdf"
+
+"Remember that the last file I asked you to review was app.py 
+ and the score was 7/10"
+```
+
+Your agent handles the payment automatically — you just see the result.
+
+---
+
+## Workflow pipelines
+
+Chain multiple services in one call with `run_workflow`:
+
+```
+"Fetch the Bitcoin whitepaper, translate the summary to French,
+ and store the translation in my agent memory"
+```
+
+The `$from` syntax passes outputs between steps:
+
+```json
+{
+  "steps": [
+    {"service": "pdf",       "input": {"url": "https://bitcoin.org/bitcoin.pdf"}},
+    {"service": "translate", "input": {"text": {"$from": 0}, "target_language": "french"}}
+  ]
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NWC_CONNECTION_STRING` | One of these two | Nostr Wallet Connect string from Alby/Mutiny |
+| `PHOENIXD_URL` | One of these two | Phoenixd base URL e.g. `http://localhost:9740` |
+| `PHOENIXD_PASSWORD` | With Phoenixd | Phoenixd HTTP Basic auth password |
+| `BOLTWORK_GATEWAY` | Optional | Override gateway URL (default: `https://parsebit-lnd.fly.dev`) |
+
+---
+
+## Pricing
+
+All prices are in satoshis (sats). At current rates, 1000 sats ≈ $0.60 — but this varies with Bitcoin's price.
+
+There is no subscription, no monthly fee, no minimum spend. You pay exactly for what your agent uses, nothing more.
+
+---
+
+## How L402 works
+
+1. Agent calls a Boltwork tool
+2. `boltwork-mcp` sends the request to `parsebit-lnd.fly.dev`
+3. Receives HTTP 402 with a Lightning invoice (e.g. 500 sats for PDF summarisation)
+4. Pays the invoice via your configured wallet (NWC or Phoenixd)
+5. Retries the request with the payment proof
+6. Returns the result to your agent
+
+The whole flow takes 1-3 seconds. Your agent sees only the final result.
+
+---
+
+## Try before you pay
+
+Boltwork has free trial endpoints — no Lightning wallet needed:
+
+```bash
+curl -X POST https://parsebit.fly.dev/trial/review \
+  -H "Content-Type: application/json" \
+  -d '{"code": "def add(a, b): return a + b"}'
+```
+
+---
+
+## Links
+
+- [Boltwork API](https://parsebit.fly.dev) — the service this MCP server wraps
+- [Agent spec](https://parsebit.fly.dev/agent-spec.md) — full API reference
+- [L402 Index](https://402index.io) — directory of L402 services
+- [MCP documentation](https://modelcontextprotocol.io) — learn about MCP
+- [Cracked Minds](https://crackedminds.co.uk) — the team behind Boltwork
+
+---
+
+## License
+
+MIT

boltwork_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "boltwork-mcp"
+version = "0.1.0"
+description = "MCP server for Boltwork — AI services via Bitcoin Lightning. PDF summarisation, code review, translation, and more."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Cracked Minds", email = "hello@crackedminds.co.uk" }
+]
+keywords = [
+    "mcp", "model-context-protocol", "lightning", "bitcoin", "l402",
+    "ai", "pdf", "summarisation", "code-review", "translation", "agents"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+nwc = [
+    "pynostr>=0.6.0",
+    "websockets>=12.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage    = "https://github.com/Squidboy30/boltwork-mcp"
+Repository  = "https://github.com/Squidboy30/boltwork-mcp"
+Issues      = "https://github.com/Squidboy30/boltwork-mcp/issues"
+API         = "https://parsebit.fly.dev"
+
+[project.scripts]
+boltwork-mcp = "boltwork_mcp.server:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/boltwork_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "README.md",
+    "LICENSE",
+]

boltwork_mcp-0.1.0/src/boltwork_mcp/payment.py

@@ -0,0 +1,274 @@
+"""
+Boltwork MCP - L402 Payment Handler
+=====================================
+Handles the full L402 payment flow transparently.
+
+Supported wallet backends:
+  - NWC  (Nostr Wallet Connect) - works with Alby, Mutiny, etc.
+  - Phoenixd - self-hosted Lightning node
+
+Flow:
+  1. Request hits L402 gateway → 402 response
+  2. Extract macaroon + invoice from WWW-Authenticate header
+  3. Pay invoice via configured wallet backend
+  4. Return Authorization header value for retry
+"""
+
+import os
+import re
+import json
+import asyncio
+import httpx
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# WWW-Authenticate header parsing
+# ---------------------------------------------------------------------------
+
+def parse_402(www_authenticate: str) -> tuple[str, str]:
+    """
+    Parse the WWW-Authenticate header from a 402 response.
+    Returns (macaroon, invoice).
+    
+    Header format:
+      L402 macaroon="<base64>", invoice="<bolt11>"
+    """
+    macaroon_match = re.search(r'macaroon="([^"]+)"', www_authenticate)
+    invoice_match  = re.search(r'invoice="([^"]+)"', www_authenticate)
+
+    if not macaroon_match or not invoice_match:
+        raise ValueError(
+            f"Could not parse L402 header: {www_authenticate[:200]}"
+        )
+
+    return macaroon_match.group(1), invoice_match.group(1)
+
+
+# ---------------------------------------------------------------------------
+# NWC payment backend
+# ---------------------------------------------------------------------------
+
+async def pay_invoice_nwc(invoice: str, nwc_string: str) -> str:
+    """
+    Pay a Lightning invoice via Nostr Wallet Connect.
+    Returns the payment preimage as a hex string.
+
+    NWC connection string format:
+      nostr+walletconnect://<pubkey>?relay=<relay_url>&secret=<secret>
+
+    Uses the pynostr-based NWC flow via a lightweight websocket exchange.
+    """
+    try:
+        from pynostr.key import PrivateKey
+        from pynostr.encrypted_dm import EncryptedDirectMessage
+        import websockets
+        import uuid
+        import time
+    except ImportError:
+        raise ImportError(
+            "NWC requires: pip install pynostr websockets\n"
+            "Or install the full package: pip install boltwork-mcp[nwc]"
+        )
+
+    # Parse NWC connection string
+    # nostr+walletconnect://<wallet_pubkey>?relay=<url>&secret=<hex_secret>
+    match = re.match(
+        r"nostr\+walletconnect://([0-9a-fA-F]+)\?.*relay=([^&]+).*secret=([0-9a-fA-F]+)",
+        nwc_string
+    )
+    if not match:
+        raise ValueError("Invalid NWC connection string format")
+
+    wallet_pubkey_hex = match.group(1)
+    relay_url         = match.group(2).rstrip("/")
+    secret_hex        = match.group(3)
+
+    client_privkey = PrivateKey(bytes.fromhex(secret_hex))
+    client_pubkey  = client_privkey.public_key.hex()
+
+    # Build pay_invoice request
+    request_id = str(uuid.uuid4())
+    payload    = json.dumps({
+        "id":     request_id,
+        "method": "pay_invoice",
+        "params": {"invoice": invoice},
+    })
+
+    # Encrypt the request to the wallet pubkey
+    dm = EncryptedDirectMessage(
+        recipient_pubkey=wallet_pubkey_hex,
+        cleartext_content=payload,
+    )
+    dm.encrypt(client_privkey.hex())
+
+    event = dm.to_event()
+    event.sign(client_privkey.hex())
+
+    timeout    = 30.0
+    deadline   = asyncio.get_event_loop().time() + timeout
+    preimage   = None
+
+    async with websockets.connect(relay_url) as ws:
+        # Subscribe to responses addressed to us from the wallet
+        sub_id  = str(uuid.uuid4())[:8]
+        sub_msg = json.dumps([
+            "REQ", sub_id,
+            {"kinds": [23195], "#p": [client_pubkey], "since": int(time.time()) - 5}
+        ])
+        await ws.send(sub_msg)
+
+        # Send the payment request
+        await ws.send(json.dumps(["EVENT", event.to_dict()]))
+
+        # Wait for response
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                raw = await asyncio.wait_for(ws.recv(), timeout=5.0)
+                msg = json.loads(raw)
+                if msg[0] == "EVENT" and msg[1] == sub_id:
+                    ev = msg[2]
+                    # Decrypt response
+                    dm_resp = EncryptedDirectMessage.from_event_dict(ev)
+                    dm_resp.decrypt(client_privkey.hex(), public_key_hex=wallet_pubkey_hex)
+                    resp = json.loads(dm_resp.cleartext_content)
+                    if resp.get("result_type") == "pay_invoice":
+                        if "error" in resp:
+                            raise RuntimeError(f"NWC payment failed: {resp['error']}")
+                        preimage = resp["result"]["preimage"]
+                        break
+            except asyncio.TimeoutError:
+                continue
+
+    if not preimage:
+        raise TimeoutError("NWC payment timed out after 30s")
+
+    return preimage
+
+
+# ---------------------------------------------------------------------------
+# Phoenixd payment backend
+# ---------------------------------------------------------------------------
+
+async def pay_invoice_phoenixd(invoice: str, phoenixd_url: str, phoenixd_password: str) -> str:
+    """
+    Pay a Lightning invoice via Phoenixd REST API.
+    Returns the payment preimage as a hex string.
+
+    phoenixd_url:      e.g. http://localhost:9740
+    phoenixd_password: the HTTP Basic auth password from phoenixd config
+    """
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.post(
+            f"{phoenixd_url}/payinvoice",
+            data={"invoice": invoice},
+            auth=("", phoenixd_password),
+        )
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"Phoenixd payment failed: HTTP {response.status_code} — {response.text[:200]}"
+            )
+        data = response.json()
+        if "preimage" not in data:
+            raise RuntimeError(f"Phoenixd response missing preimage: {data}")
+        return data["preimage"]
+
+
+# ---------------------------------------------------------------------------
+# Main payment dispatcher
+# ---------------------------------------------------------------------------
+
+async def pay_invoice(invoice: str) -> str:
+    """
+    Pay a Lightning invoice using the configured wallet backend.
+    Returns the preimage as a hex string.
+
+    Reads configuration from environment variables:
+      NWC_CONNECTION_STRING  — use NWC backend
+      PHOENIXD_URL           — use Phoenixd backend (also needs PHOENIXD_PASSWORD)
+      PHOENIXD_PASSWORD      — Phoenixd HTTP Basic auth password
+    """
+    nwc_string        = os.environ.get("NWC_CONNECTION_STRING", "").strip()
+    phoenixd_url      = os.environ.get("PHOENIXD_URL", "").strip()
+    phoenixd_password = os.environ.get("PHOENIXD_PASSWORD", "").strip()
+
+    if nwc_string:
+        return await pay_invoice_nwc(invoice, nwc_string)
+    elif phoenixd_url and phoenixd_password:
+        return await pay_invoice_phoenixd(invoice, phoenixd_url, phoenixd_password)
+    else:
+        raise RuntimeError(
+            "No wallet configured. Set one of:\n"
+            "  NWC_CONNECTION_STRING=nostr+walletconnect://...\n"
+            "  PHOENIXD_URL=http://localhost:9740 + PHOENIXD_PASSWORD=..."
+        )
+
+
+# ---------------------------------------------------------------------------
+# Full L402 request helper — use this from tool handlers
+# ---------------------------------------------------------------------------
+
+async def l402_request(
+    method: str,
+    url: str,
+    gateway_url: str,
+    json_body: Optional[dict] = None,
+    files: Optional[dict] = None,
+) -> dict:
+    """
+    Make an L402-authenticated request.
+
+    1. Sends request to gateway_url (the L402 gateway)
+    2. If 402, pays the invoice and retries with credentials
+    3. Returns the parsed JSON response
+
+    Args:
+        method:      HTTP method ("GET", "POST")
+        url:         The logical endpoint path (e.g. "/summarise/url")
+        gateway_url: Full URL to the L402 gateway endpoint
+        json_body:   JSON request body (for POST)
+        files:       Multipart files (for file upload)
+    """
+    async with httpx.AsyncClient(timeout=120.0, follow_redirects=True) as client:
+
+        # First attempt — expect either 200 or 402
+        kwargs = {}
+        if json_body is not None:
+            kwargs["json"] = json_body
+        if files is not None:
+            kwargs["files"] = files
+
+        response = await client.request(method, gateway_url, **kwargs)
+
+        if response.status_code == 200:
+            return response.json()
+
+        if response.status_code != 402:
+            raise RuntimeError(
+                f"Unexpected HTTP {response.status_code} from {gateway_url}: "
+                f"{response.text[:300]}"
+            )
+
+        # Parse 402 and pay
+        www_auth = response.headers.get("WWW-Authenticate", "")
+        if not www_auth:
+            raise RuntimeError("Got 402 but no WWW-Authenticate header")
+
+        macaroon, invoice = parse_402(www_auth)
+        preimage = await pay_invoice(invoice)
+
+        # Retry with L402 credentials
+        auth_header = f"L402 {macaroon}:{preimage}"
+        response2 = await client.request(
+            method, gateway_url,
+            headers={"Authorization": auth_header},
+            **kwargs,
+        )
+
+        if response2.status_code != 200:
+            raise RuntimeError(
+                f"L402 retry failed: HTTP {response2.status_code} — "
+                f"{response2.text[:300]}"
+            )
+
+        return response2.json()

boltwork_mcp-0.1.0/src/boltwork_mcp/server.py

@@ -0,0 +1,467 @@
+"""
+Boltwork MCP Server
+====================
+Exposes all Boltwork AI services as MCP tools.
+Handles L402 Lightning payments transparently.
+
+Usage:
+  pip install boltwork-mcp
+  
+  Then add to claude_desktop_config.json or .cursor/mcp.json:
+  {
+    "mcpServers": {
+      "boltwork": {
+        "command": "uvx",
+        "args": ["boltwork-mcp"],
+        "env": {
+          "NWC_CONNECTION_STRING": "nostr+walletconnect://..."
+        }
+      }
+    }
+  }
+"""
+
+import os
+import asyncio
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp import types
+
+from boltwork_mcp.payment import l402_request
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+GATEWAY = os.environ.get("BOLTWORK_GATEWAY", "https://parsebit-lnd.fly.dev")
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+
+app = Server("boltwork")
+
+
+@app.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+
+        # ── Summarisation ────────────────────────────────────────────────
+        types.Tool(
+            name="summarise_pdf",
+            description=(
+                "Summarise a PDF document from a URL. Returns a structured summary "
+                "including title, key points, sentiment, topics, and word count. "
+                "Costs 500 sats via Lightning. "
+                "Use for: research papers, reports, contracts, any PDF."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "url":       {"type": "string",  "description": "URL of the PDF to summarise"},
+                    "max_pages": {"type": "integer", "description": "Max pages to process (default 20)", "default": 20},
+                },
+                "required": ["url"],
+            },
+        ),
+
+        # ── Code Review ──────────────────────────────────────────────────
+        types.Tool(
+            name="review_code",
+            description=(
+                "Review source code and return a structured analysis covering bugs, "
+                "security issues, code quality, strengths, and recommended actions. "
+                "Returns an overall score 1-10. "
+                "Costs 2000 sats via Lightning. "
+                "Supports: Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, "
+                "C#, Ruby, PHP, Swift, Kotlin, Scala, Shell, SQL, Terraform, and more."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "code":     {"type": "string", "description": "The source code to review"},
+                    "language": {"type": "string", "description": "Language hint (optional, auto-detected if omitted)"},
+                    "filename": {"type": "string", "description": "Filename hint for language detection (optional)"},
+                },
+                "required": ["code"],
+            },
+        ),
+
+        types.Tool(
+            name="review_code_url",
+            description=(
+                "Review code fetched from a URL. Supports GitHub and GitLab blob URLs "
+                "(auto-converted to raw). "
+                "Costs 2000 sats via Lightning."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "url":      {"type": "string", "description": "URL to the code file (GitHub/GitLab/raw)"},
+                    "language": {"type": "string", "description": "Language hint (optional)"},
+                },
+                "required": ["url"],
+            },
+        ),
+
+        # ── Web Extraction ───────────────────────────────────────────────
+        types.Tool(
+            name="summarise_webpage",
+            description=(
+                "Summarise any web page by URL. Returns title, summary, key points, "
+                "content type, sentiment, and topics. "
+                "Costs 100 sats via Lightning. "
+                "Use for: articles, blogs, documentation, product pages, news."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "url": {"type": "string", "description": "URL of the web page to summarise"},
+                },
+                "required": ["url"],
+            },
+        ),
+
+        # ── Data Extraction ──────────────────────────────────────────────
+        types.Tool(
+            name="extract_data",
+            description=(
+                "Extract structured data from a PDF document. Returns document type, "
+                "dates, parties, amounts, line items, and reference numbers. "
+                "Costs 200 sats via Lightning. "
+                "Use for: invoices, contracts, receipts, forms."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "url":       {"type": "string",  "description": "URL of the PDF"},
+                    "max_pages": {"type": "integer", "description": "Max pages to process (default 20)", "default": 20},
+                },
+                "required": ["url"],
+            },
+        ),
+
+        # ── Translation ──────────────────────────────────────────────────
+        types.Tool(
+            name="translate",
+            description=(
+                "Translate text or a document URL to any of 24 supported languages. "
+                "Detects source language automatically. "
+                "Costs 150 sats via Lightning. "
+                "Supported languages: Spanish, French, German, Italian, Portuguese, "
+                "Dutch, Russian, Japanese, Chinese, Korean, Arabic, Hindi, Turkish, "
+                "Polish, Swedish, Danish, Norwegian, Finnish, Czech, Romanian, "
+                "Hungarian, Greek, Hebrew, Thai."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "text":            {"type": "string", "description": "Text to translate (provide either text or url)"},
+                    "url":             {"type": "string", "description": "URL of document to translate (provide either text or url)"},
+                    "target_language": {"type": "string", "description": "Target language (e.g. 'spanish', 'french', 'japanese')"},
+                },
+                "required": ["target_language"],
+            },
+        ),
+
+        # ── Analysis ─────────────────────────────────────────────────────
+        types.Tool(
+            name="extract_tables",
+            description=(
+                "Extract all tables from a PDF as structured JSON. "
+                "Returns table count, headers, rows, and a summary. "
+                "Costs 300 sats via Lightning. "
+                "Use for: financial reports, research data, invoices with line items."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "url":       {"type": "string",  "description": "URL of the PDF"},
+                    "max_pages": {"type": "integer", "description": "Max pages to process (default 20)", "default": 20},
+                },
+                "required": ["url"],
+            },
+        ),
+
+        types.Tool(
+            name="compare_documents",
+            description=(
+                "Compare two PDF documents and return a structured diff. "
+                "Identifies additions, removals, modifications, and overall similarity. "
+                "Costs 500 sats via Lightning. "
+                "Use for: contract versions, policy updates, paper revisions."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "url_a":     {"type": "string",  "description": "URL of the first PDF (original)"},
+                    "url_b":     {"type": "string",  "description": "URL of the second PDF (revised)"},
+                    "max_pages": {"type": "integer", "description": "Max pages per document (default 20)", "default": 20},
+                },
+                "required": ["url_a", "url_b"],
+            },
+        ),
+
+        types.Tool(
+            name="explain_code",
+            description=(
+                "Explain what code does in plain English. Unlike code review (which finds "
+                "problems), this explains purpose and behaviour to a non-programmer. "
+                "Costs 500 sats via Lightning. "
+                "Use for: understanding inherited code, due diligence, onboarding docs."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "code":     {"type": "string", "description": "Source code to explain (provide either code or url)"},
+                    "url":      {"type": "string", "description": "URL of code file to explain (provide either code or url)"},
+                    "language": {"type": "string", "description": "Language hint (optional)"},
+                },
+            },
+        ),
+
+        # ── Agent Memory ─────────────────────────────────────────────────
+        types.Tool(
+            name="memory_store",
+            description=(
+                "Store persistent key-value memory for your agent. "
+                "Data persists across sessions, keyed by agent_id. "
+                "Up to 100 keys per agent, 10 keys per write call. "
+                "Costs 10 sats via Lightning."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "agent_id": {"type": "string", "description": "Stable identifier for your agent"},
+                    "entries":  {"type": "object", "description": "Key-value pairs to store (max 10 keys, values must be JSON-serialisable)"},
+                },
+                "required": ["agent_id", "entries"],
+            },
+        ),
+
+        types.Tool(
+            name="memory_retrieve",
+            description=(
+                "Retrieve stored memory for your agent. "
+                "Returns all keys or a specific subset. "
+                "Costs 5 sats via Lightning."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "agent_id": {"type": "string",       "description": "Agent identifier"},
+                    "keys":     {"type": "array",        "description": "Specific keys to fetch (omit to return all)", "items": {"type": "string"}},
+                },
+                "required": ["agent_id"],
+            },
+        ),
+
+        types.Tool(
+            name="memory_delete",
+            description="Delete a single key from your agent's memory store. Free.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "agent_id": {"type": "string", "description": "Agent identifier"},
+                    "key":      {"type": "string", "description": "Key to delete"},
+                },
+                "required": ["agent_id", "key"],
+            },
+        ),
+
+        # ── Workflow Pipelines ────────────────────────────────────────────
+        types.Tool(
+            name="run_workflow",
+            description=(
+                "Chain multiple Boltwork services in a single call. "
+                "Pay once, describe a pipeline of up to 5 steps, get the final result "
+                "plus all intermediate outputs. "
+                "Use {\"$from\": N} in any input value to pass the primary output of "
+                "step N into the current step. "
+                "Costs 1000 sats via Lightning. "
+                "Supported services: webpage, pdf, summarise, translate, data, "
+                "tables, explain, review, compare. "
+                "Example: fetch a webpage, translate the summary to French — "
+                "steps: [{service: webpage, input: {url: ...}}, "
+                "{service: translate, input: {text: {$from: 0}, target_language: french}}]"
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "steps": {
+                        "type": "array",
+                        "description": "Pipeline steps, each with 'service' and 'input'",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "service": {"type": "string"},
+                                "input":   {"type": "object"},
+                            },
+                            "required": ["service", "input"],
+                        },
+                        "maxItems": 5,
+                    },
+                    "label": {"type": "string", "description": "Optional label for this pipeline"},
+                },
+                "required": ["steps"],
+            },
+        ),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Tool call handlers
+# ---------------------------------------------------------------------------
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+    try:
+        result = await _dispatch(name, arguments)
+        import json
+        return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+    except Exception as e:
+        return [types.TextContent(type="text", text=f"Error: {e}")]
+
+
+async def _dispatch(name: str, args: dict) -> dict:
+    match name:
+
+        case "summarise_pdf":
+            return await l402_request(
+                "POST", "/summarise/url",
+                f"{GATEWAY}/summarise/url",
+                json_body={"url": args["url"], "max_pages": args.get("max_pages", 20)},
+            )
+
+        case "review_code":
+            return await l402_request(
+                "POST", "/review/code",
+                f"{GATEWAY}/review/code",
+                json_body={
+                    "code":     args["code"],
+                    "language": args.get("language"),
+                    "filename": args.get("filename"),
+                },
+            )
+
+        case "review_code_url":
+            return await l402_request(
+                "POST", "/review/url",
+                f"{GATEWAY}/review/url",
+                json_body={"url": args["url"], "language": args.get("language")},
+            )
+
+        case "summarise_webpage":
+            return await l402_request(
+                "POST", "/extract/webpage",
+                f"{GATEWAY}/extract/webpage",
+                json_body={"url": args["url"]},
+            )
+
+        case "extract_data":
+            return await l402_request(
+                "POST", "/extract/data",
+                f"{GATEWAY}/extract/data",
+                json_body={"url": args["url"], "max_pages": args.get("max_pages", 20)},
+            )
+
+        case "translate":
+            body = {"target_language": args["target_language"]}
+            if "text" in args:
+                body["text"] = args["text"]
+            if "url" in args:
+                body["url"] = args["url"]
+            return await l402_request(
+                "POST", "/translate",
+                f"{GATEWAY}/translate",
+                json_body=body,
+            )
+
+        case "extract_tables":
+            return await l402_request(
+                "POST", "/analyse/tables",
+                f"{GATEWAY}/analyse/tables",
+                json_body={"url": args["url"], "max_pages": args.get("max_pages", 20)},
+            )
+
+        case "compare_documents":
+            return await l402_request(
+                "POST", "/analyse/compare",
+                f"{GATEWAY}/analyse/compare",
+                json_body={
+                    "url_a":     args["url_a"],
+                    "url_b":     args["url_b"],
+                    "max_pages": args.get("max_pages", 20),
+                },
+            )
+
+        case "explain_code":
+            body = {}
+            if "code" in args:
+                body["code"] = args["code"]
+            if "url" in args:
+                body["url"] = args["url"]
+            if "language" in args:
+                body["language"] = args["language"]
+            return await l402_request(
+                "POST", "/analyse/explain",
+                f"{GATEWAY}/analyse/explain",
+                json_body=body,
+            )
+
+        case "memory_store":
+            return await l402_request(
+                "POST", "/memory/store",
+                f"{GATEWAY}/memory/store",
+                json_body={"agent_id": args["agent_id"], "entries": args["entries"]},
+            )
+
+        case "memory_retrieve":
+            body = {"agent_id": args["agent_id"]}
+            if "keys" in args:
+                body["keys"] = args["keys"]
+            return await l402_request(
+                "POST", "/memory/retrieve",
+                f"{GATEWAY}/memory/retrieve",
+                json_body=body,
+            )
+
+        case "memory_delete":
+            return await l402_request(
+                "POST", "/memory/delete",
+                f"{GATEWAY}/memory/delete",
+                json_body={"agent_id": args["agent_id"], "key": args["key"]},
+            )
+
+        case "run_workflow":
+            return await l402_request(
+                "POST", "/workflow/run",
+                f"{GATEWAY}/workflow/run",
+                json_body={"steps": args["steps"], "label": args.get("label")},
+            )
+
+        case _:
+            raise ValueError(f"Unknown tool: {name}")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(
+            read_stream,
+            write_stream,
+            app.create_initialization_options(),
+        )
+
+
+def run():
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()