Metadata-Version: 2.5
Name: macaroonnetwork-mcp
Version: 0.3.0
Summary: MCP client for Macaroon Network -- discover and buy from a live marketplace where AI agents pay per query in Bitcoin over Lightning.
Project-URL: Homepage, https://macaroonnetwork.com
Project-URL: Repository, https://github.com/kevmoz/macaroonnetwork
Author: Kevin Smith
License-Expression: MIT
Keywords: agent-commerce,christian-api,l402,lightning,marketplace,mcp,model-context-protocol,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: jsonpath-ng>=1.6.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: http
Requires-Dist: starlette>=0.40.0; extra == 'http'
Requires-Dist: uvicorn>=0.30.0; extra == 'http'
Description-Content-Type: text/markdown

# macaroonnetwork-mcp

<!-- mcp-name: com.macaroonnetwork/mcp-server -->

MCP client for [Macaroon Network](https://macaroonnetwork.com) — a
marketplace where AI agents discover and pay for live data.

**Payment rail status, read before use:** the live marketplace's primary
payment rail is **x402 (USDC on Base mainnet)** — nearly every listing is
settled that way today. **L402 (Bitcoin Lightning)** is also supported but is
inactive for most live listings. This package's buyer code handles both:
`macaroons_execute` understands the real x402 challenge shape (a base64-JSON
`payment-required` header carrying `accepts[]` terms) exactly as it arrives
from the live registry, alongside the existing L402 `www-authenticate` flow —
whichever rail a listing actually gates on, this package raises the matching
typed result instead of an unhandled 402. As with L402, this package never
holds a wallet or signs anything itself for x402 either: it hands back the
real payment terms for you to sign with your own wallet/CDP infrastructure.
(Note: this x402 support has not yet been published to PyPI as of this
writing — `pip install macaroonnetwork-mcp` still gets the L402-only 0.2.0
release until the next publish; build from this repo's `mcp-distribution/` if
you need it now.)

## What this does

Four tools:

- **`macaroons_search`** — semantic search over the live marketplace registry
  by natural-language intent, including Christian evidence capabilities. Free.
- **`macaroons_metadata`** — free freshness/content-hash metadata for a feed
  target, before deciding whether to buy. Free.
- **`macaroons_purchase`** — pays via the Lightning L402 rail (feed-changes
  purchases only; see "Paying" below).
- **`macaroons_execute`** — pays via whichever rail the target listing
  actually uses, x402 or L402, and receives the real, predicate-verified
  result. See "Paying" below — by default this package holds no wallet and
  doesn't attempt payment for you on either rail.

## Paying

This package never holds a private key or wallet credential by default, on
either payment rail.

### x402 (USDC on Base) — `macaroons_execute` only

When an x402-gated listing needs payment, `macaroons_execute` returns an
`x402_payment_required` result instead of failing:

```json
{
  "x402_payment_required": true,
  "resource_url": "https://api.macaroonnetwork.com/execute/...",
  "amount_atomic": "3000",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "network": "eip155:8453",
  "pay_to": "0x33cc...",
  "extra_name": "USD Coin",
  "extra_version": "2",
  "max_timeout_seconds": 60,
  "x402_version": 2,
  "instructions": "Sign an exact x402 payment of amount_atomic atomic units of asset on network to pay_to with your own wallet/CDP infra, then call this same tool again with identical arguments PLUS payment_signature set to the resulting signed proof."
}
```

Sign the exact-scheme USDC payment described above with your own wallet or
Coinbase CDP infrastructure, then call `macaroons_execute` again with
identical arguments plus `payment_signature` set to the resulting signed
proof. Unlike the L402 flow below, this is a single retry — x402's "exact"
scheme settles synchronously, there's no invoice-polling step.

### L402 (Bitcoin Lightning)

When an L402-gated listing needs payment, `macaroons_purchase`/
`macaroons_execute` return a `payment_required` result instead of failing:

```json
{
  "payment_required": true,
  "invoice": "lnbc...",
  "macaroon": "eyJ...",
  "amount_msat": 250000,
  "instructions": "Pay this BOLT11 invoice with your own Lightning wallet, then call this same tool again with identical arguments PLUS resume_macaroon set to the macaroon above."
}
```

Pay the invoice with whatever Lightning wallet you actually have, then call
the same tool again with `resume_macaroon` set to the macaroon above. A
plain retry *without* `resume_macaroon` mints a brand-new invoice instead of
resuming the one you just paid — always pass it back.

If you run your own real LND node and want this package to auto-pay from
it instead of returning `payment_required`, set:

```bash
MACAROONS_BUYER_LND_MODE=external
LND_BUYER_HOST=your-node:10009
LND_BUYER_TLS=/path/to/tls.cert
LND_BUYER_MACAROON=/path/to/admin.macaroon
```

This shells out to a real `lncli` binary on your machine — install LND's
`lncli` separately, it isn't bundled here. There is no equivalent auto-pay
mode for x402: no offline/local-key signing path exists in this package for
either rail, by design (see the payment-rail status note above).

## Install

```bash
pip install macaroonnetwork-mcp
```

## Use with an MCP client

```json
{
  "mcpServers": {
    "macaroonnetwork": {
      "command": "macaroonnetwork-mcp"
    }
  }
}
```

Talks to `https://api.macaroonnetwork.com` by default. Override with
`MACAROONS_REGISTRY_URL` / `MACAROONS_FEED_URL` env vars to point at a local
dev stack instead. `MACAROONS_SESSION_BUDGET_SATS` (default 1000) caps total
spend per server process; each tool call also takes a `max_spend_sats`
per-call cap (default 100).

## License

MIT
