baconservices-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bacon Services
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# baconservices-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server that lets an AI agent buy image work from [Bacon Services](https://baconservices.com),
+one call at a time, paid in USDC on Base over [x402](https://x402.org) from **your own wallet**,
+within spending limits you set. There's no account and no API key: the agent calls a tool, the
+server checks the price against your limits, signs a USDC payment for exactly that price, and
+returns the result.
+
+Also listed in the MCP Registry as `io.github.afmontoya/baconservices-mcp`.
+
+## Wallet safety
+
+Your wallet private key stays on your machine. Bacon Services never receives or stores it.
+Payments are signed locally and are subject to configurable per-call, session, and daily
+spending limits.
+
+## What it sells
+
+| Tool | Does | Price (2026-10-17) |
+|---|---|---|
+| `remove_background` | Removes the background from one photo; returns a transparent PNG at the photo's size | 0.20 USDC |
+| `optimize_image` | Resizes so the longest side ≤ `max_width` (64–4096, default 1600) and encodes WebP at `quality` (40–95, default 80) | 0.01 USDC |
+| `image_palette` | The colours one image is mostly made of, as JSON: up to `count` (1–12, default 6) hex colours with their share, `include_neutrals` (default true) | 0.01 USDC |
+| `brand_from_url` | Reads one public web page (`url`) and returns its brand as JSON: name, description, logo URLs, colours, fonts, social profiles. No JavaScript runs; robots.txt is respected | 0.03 USDC |
+
+Image tools take PNG, JPEG or WebP up to 8 MB, as `image_url` (public https) or `image_path` (a
+local file). `remove_background` and `optimize_image` return a signed download link (valid 24
+hours); `image_palette` and `brand_from_url` return their JSON result in the tool result. Add
+`save_to` to write either kind to disk. Prices come from Bacon's live catalog, and each paid tool
+states its current price in its description.
+
+`image_palette` and `brand_from_url` appear once Bacon's catalog publishes them with contract
+versions. A service the installed package doesn't understand is listed by `list_services` but
+can't be called until you update the package.
+
+Free tools:
+
+- `list_services`: everything Bacon sells right now, with prices, limits, and whether this
+  version of the package can run it.
+- `quote`: Bacon's current price for one service, and whether your limits and wallet allow it.
+  Nothing is signed.
+- `wallet_status`: network, whether a wallet is configured, your limits and what's left of them,
+  and whether you can afford each service (yes/no).
+
+## Before you start
+
+1. **Node.js 20 or newer.**
+2. **A dedicated wallet** holding only what you're willing to spend. Fund it with **USDC on Base**.
+   You don't need ETH: x402 payments are signed authorizations (EIP-3009), and the facilitator
+   pays the gas.
+3. **Put the private key in a file** that only you can read, for example `~/.bacon/buyer.key`.
+   Pointing `BACON_WALLET_KEY_FILE` at that file keeps the key out of MCP host configs, which are
+   often synced or shared. `BACON_WALLET_PRIVATE_KEY` also works.
+
+The key never leaves your machine. Only signatures are sent, and only to Bacon. The key is never
+logged, never written to the spend ledger, and never accepted as a tool argument.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add bacon -e BACON_WALLET_KEY_FILE=/home/you/.bacon/buyer.key -- npx -y baconservices-mcp
+```
+
+Add more `-e NAME=value` pairs for the limits below. Check it with `claude mcp list`.
+
+### Claude Desktop
+
+Settings → Developer → Edit Config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "bacon": {
+      "command": "npx",
+      "args": ["-y", "baconservices-mcp"],
+      "env": {
+        "BACON_WALLET_KEY_FILE": "/Users/you/.bacon/buyer.key",
+        "BACON_MAX_PER_CALL": "0.50",
+        "BACON_MAX_PER_SESSION": "1.00",
+        "BACON_MAX_PER_DAY": "5.00"
+      }
+    }
+  }
+}
+```
+
+On Windows, if `npx` isn't found, use `"command": "cmd"` with
+`"args": ["/c", "npx", "-y", "baconservices-mcp"]`, and write paths as
+`"C:\\Users\\you\\.bacon\\buyer.key"`. Restart Claude Desktop afterwards.
+
+### Cursor, Windsurf and other clients with an `mcpServers` file
+
+Use the same `command` / `args` / `env` block as Claude Desktop (for Cursor:
+`~/.cursor/mcp.json` or `.cursor/mcp.json` in a project).
+
+### VS Code (`.vscode/mcp.json`)
+
+VS Code can prompt for the key once and store it securely:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "bacon-key", "description": "Bacon buyer wallet private key", "password": true }
+  ],
+  "servers": {
+    "bacon": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "baconservices-mcp"],
+      "env": { "BACON_WALLET_PRIVATE_KEY": "${input:bacon-key}" }
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+It's a stdio server: run `npx -y baconservices-mcp` with the environment below.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `BACON_WALLET_KEY_FILE` | — | Path to a file containing the buyer wallet's private key. |
+| `BACON_WALLET_PRIVATE_KEY` | — | The key itself (set only one of the two). Without either, the free tools still work. |
+| `BACON_MAX_PER_CALL` | `0.50` | Largest single payment, in USDC. |
+| `BACON_MAX_PER_SESSION` | `1.00` | Most this server process may spend. |
+| `BACON_MAX_PER_DAY` | `5.00` | Most spent in any rolling 24 hours, across all processes and restarts. |
+| `BACON_CONFIRM` | `auto` | `auto`: ask before each payment when the host can; `always`: refuse to pay when it can't; `never`: don't ask (for unattended agents; the limits still apply). |
+| `BACON_NETWORK` | `base` | `base` (real USDC, baconservices.com) or `base-sepolia` (test USDC, a test copy of Bacon). |
+| `BACON_API_URL` | — | Only with `base-sepolia`: the test copy's address. |
+| `BACON_PAY_TO` | — | Only with `base-sepolia`: the test copy's receiving address. |
+| `BACON_RPC_URL` | `https://mainnet.base.org` | RPC used to check your USDC balance before paying. |
+| `BACON_LEDGER_DIR` | `~/.baconservices-mcp` | Where the spend ledger lives. |
+| `BACON_DISCLOSE_BALANCE` | `false` | `true` adds the exact balance and the wallet address to `wallet_status`. |
+
+## How your money is protected
+
+All of these checks happen before anything is signed:
+
+- **The price is Bacon's own.** Bacon answers each request with an x402 402 that names the price.
+  The server pays only if that price equals Bacon's live catalog price, for that exact endpoint,
+  in Base USDC, to Bacon's receiving address (which is pinned in the package). If any of these
+  can't be verified, it doesn't pay.
+- **Your limits.** It checks the per-call limit, an optional `max_price_usdc` on the call, the
+  per-session limit, and the 24-hour limit. The 24-hour total is kept in a local ledger file
+  shared by every process, so restarting the MCP server or running it twice doesn't open a new
+  budget. If the ledger can't be read, nothing is paid. The x402 library's own per-payment
+  cap is set to your per-call limit as a second lock.
+- **Funds.** It reads your USDC balance first. If it's too low, or the balance can't be read,
+  you get a plain message and nothing is signed.
+- **Your approval, where possible.** If the MCP host supports it, you're asked *"Pay 0.2 USDC on
+  Base to Bacon Services to run remove_background?"* Not every host can ask, so the limits are
+  the real boundary.
+- **No double payments.** Each purchase signs one payment for one request. If the connection drops,
+  the server resends that same signed payment once (Bacon answers a repeat with the same result)
+  and never signs a new one. Asking for the same thing again within 10 minutes returns the
+  earlier result for free, unless you pass `allow_repeat: true`.
+- **Only known services run.** New services in Bacon's catalog show up in `list_services`. They
+  become callable tools only once a version of this package that understands their contract
+  (inputs, outputs, version) is installed.
+
+If Bacon refuses a payment before taking it, the result says *"You have not been charged"* and
+the amount goes back to your limits. If the outcome is unknown (for example the connection was lost
+twice), the result says so and gives Bacon's request id. That amount keeps counting against your
+limits.
+
+## Test money
+
+Production Bacon sells only for real USDC. To try things without real money, run against a local
+or test copy of Bacon that sells on Base Sepolia:
+
+```bash
+BACON_NETWORK=base-sepolia BACON_API_URL=http://127.0.0.1:8000 BACON_PAY_TO=0xYourTestPayTo npx -y baconservices-mcp
+```
+
+The package refuses mismatched setups and pays nothing in each case: test money pointed at
+baconservices.com, real money pointed anywhere else, or a Bacon whose catalog is on a different
+network.
+
+## Develop
+
+```bash
+npm install
+npm test
+```
+
+The tests run against a fake Bacon that checks every payment signature for real. Nothing reaches
+a network.
+
+## Hosted services
+
+This MCP client is open source under the MIT License. Bacon Services' hosted APIs, Agent
+Commerce services, x402-paid capabilities, infrastructure, and backend implementations are
+separate services and are not licensed under the MIT License. Use of Bacon Services' hosted
+APIs and x402 services is governed by the [Bacon Services terms](https://baconservices.com/terms).
+
+## Trademark notice
+
+The MIT License applies to the source code in this repository only. "Bacon Services," the
+Bacon Services name, logos, and associated branding are not licensed under the MIT License. No
+permission is granted to use Bacon Services trademarks, logos, or branding in a way that
+suggests endorsement, sponsorship, or affiliation. See [TRADEMARKS.md](TRADEMARKS.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/TRADEMARKS.md

@@ -0,0 +1,13 @@
+# Trademark Notice
+
+The MIT License applies to the source code in this repository only. "Bacon Services," the Bacon
+Services name, logos, and associated branding are not licensed under the MIT License. No
+permission is granted to use Bacon Services trademarks, logos, or branding in a way that
+suggests endorsement, sponsorship, or affiliation.
+
+## Hosted services
+
+This MCP client is open source under the MIT License. Bacon Services' hosted APIs, Agent
+Commerce services, x402-paid capabilities, infrastructure, and backend implementations are
+separate services and are not licensed under the MIT License. Use of Bacon Services' hosted
+APIs and x402 services is governed by the Bacon Services terms: https://baconservices.com/terms

package/bin/baconservices-mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// stdio entry point. stdout carries the MCP protocol only; nothing else is ever written there.
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createBaconServer } from '../src/server.js';
+
+const { server } = createBaconServer();
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "baconservices-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server that lets an AI agent buy Bacon Services image operations (remove background, optimize for the web) per call in USDC over x402, with local spending limits.",
+  "mcpName": "io.github.afmontoya/baconservices-mcp",
+  "type": "module",
+  "bin": {
+    "baconservices-mcp": "bin/baconservices-mcp.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "TRADEMARKS.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 \"test/*.test.js\""
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "usdc",
+    "base",
+    "remove-background",
+    "image-optimization",
+    "agent-payments"
+  ],
+  "homepage": "https://baconservices.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/afmontoya/baconservices-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/afmontoya/baconservices-mcp/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@x402/core": "2.28.0",
+    "@x402/evm": "2.28.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "viem": "2.57.7",
+    "zod": "3.25.76"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,71 @@
+// The live catalog: what Bacon sells right now, matched against the contracts this package knows.
+
+import { CONTRACTS, checkEntry, contractForEntry, contractId } from './contracts.js';
+import { formatUsdc } from './money.js';
+
+export const CATALOG_PATH = '/api/agent-commerce/v1/capabilities';
+
+export function endpointFor(apiUrl, id) {
+    return `${apiUrl}${CATALOG_PATH}/${id}/execute`;
+}
+
+/**
+ * Fetches the catalog and decides, per entry, whether it is executable here.
+ * Throws with a plain message when the catalog cannot be read or is not on the configured network.
+ */
+export async function fetchCatalog(config, fetchImpl) {
+    let response;
+    try {
+        response = await fetchImpl(`${config.apiUrl}${CATALOG_PATH}`, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(15_000) });
+    } catch (error) {
+        throw new Error(`Could not reach Bacon's service catalog at ${config.apiUrl}${CATALOG_PATH} (${error.name === 'TimeoutError' ? 'timed out' : error.message}).`);
+    }
+    if (response.status === 404) {
+        throw new Error('Bacon is not selling services to agents right now (the catalog is closed).');
+    }
+    let data = null;
+    try {
+        data = await response.json();
+    } catch {
+        // checked below
+    }
+    if (!response.ok || !data || !Array.isArray(data.capabilities)) {
+        throw new Error(`Bacon's service catalog answered ${response.status} without a capability list.`);
+    }
+    if (data.protocol?.name !== 'x402' || data.protocol?.version !== 2 || data.protocol?.scheme !== 'exact') {
+        throw new Error('Bacon\'s catalog does not describe x402 v2 "exact" payments, which is all this package can make.');
+    }
+    if (data.network?.id !== config.network.id || data.network?.testnet !== config.network.testnet) {
+        throw new Error(`Bacon at ${config.apiUrl} sells on ${data.network?.id ?? 'an unknown network'}${data.network?.testnet ? ' (testnet)' : ''}, but this package is set to ${config.network.id} (${config.network.label}). Nothing can be paid until they match.`);
+    }
+
+    const services = data.capabilities.map((entry) => {
+        const contract = contractForEntry(entry);
+        const reasons = checkEntry(entry, contract, { endpoint: endpointFor(config.apiUrl, entry.id), usdc: config.network.usdc.address, catalogVersion: data.contract_version });
+        return {
+            id: entry.id,
+            name: entry.name,
+            description: entry.description,
+            contract: contractId(entry.id, entry.version),
+            tool: contract?.tool ?? null,
+            executable: reasons.length === 0,
+            not_executable_because: reasons,
+            price: entry.price && /^\d+$/.test(entry.price.amount ?? '') ? { usdc: formatUsdc(entry.price.amount), atomic: entry.price.amount } : null,
+            execution: entry.execution ?? null,
+            output: entry.output ?? null,
+            limits: entry.limits ?? null,
+            entry,
+            contractDef: contract,
+        };
+    });
+
+    return { network: data.network, contractVersion: data.contract_version ?? null, services };
+}
+
+/** The tools a catalog makes executable, in the package's own order. */
+export function executableTools(catalog) {
+    if (!catalog) {
+        return [];
+    }
+    return CONTRACTS.map((c) => catalog.services.find((s) => s.tool === c.tool && s.executable)).filter(Boolean);
+}

package/src/config.js

@@ -0,0 +1,103 @@
+// Configuration from the environment, with the network guard.
+//
+// Real money (Base) talks to https://baconservices.com and nothing else. Test money (Base
+// Sepolia) talks to a test copy of Bacon and never to production. A mismatch is a configuration
+// problem: nothing is fetched and nothing can be paid until it is fixed.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseUsdc } from './money.js';
+import { NETWORKS, PRODUCTION_API_URL } from './networks.js';
+
+export const DEFAULT_LIMITS = { perCall: '0.50', perSession: '1.00', perDay: '5.00' };
+export const CONFIRM_MODES = ['auto', 'always', 'never'];
+
+const PRODUCTION_HOSTS = ['baconservices.com', 'www.baconservices.com'];
+const LOCAL_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+
+/**
+ * @returns {{ problems: string[], network: object|null, apiUrl: string|null, limits: object, confirm: string,
+ *            ledgerDir: string, rpcUrl: string|null, payTo: string|null, discloseBalance: boolean }}
+ */
+export function loadConfig(env, { home = homedir() } = {}) {
+    const problems = [];
+    const read = (name) => (env[name] ?? '').trim();
+
+    const networkKey = read('BACON_NETWORK') || 'base';
+    const network = NETWORKS[networkKey] ?? null;
+    if (!network) {
+        problems.push(`BACON_NETWORK must be "base" (real USDC) or "base-sepolia" (test USDC), not "${networkKey}".`);
+    }
+
+    let apiUrl = null;
+    const rawApi = read('BACON_API_URL').replace(/\/+$/, '');
+    if (network) {
+        if (!network.testnet) {
+            apiUrl = PRODUCTION_API_URL;
+            if (rawApi && rawApi !== PRODUCTION_API_URL) {
+                problems.push(`BACON_NETWORK=base pays real money and only talks to ${PRODUCTION_API_URL}; BACON_API_URL is "${rawApi}". For a test copy of Bacon use BACON_NETWORK=base-sepolia.`);
+            }
+        } else if (!rawApi) {
+            problems.push('BACON_NETWORK=base-sepolia needs BACON_API_URL: the address of a test copy of Bacon (production sells for real money only).');
+        } else {
+            let url = null;
+            try {
+                url = new URL(rawApi);
+            } catch {
+                problems.push(`BACON_API_URL "${rawApi}" is not a URL.`);
+            }
+            if (url) {
+                if (PRODUCTION_HOSTS.includes(url.hostname)) {
+                    problems.push(`BACON_NETWORK=base-sepolia cannot use production (${url.hostname}): production sells for real money only. Use BACON_NETWORK=base, or point BACON_API_URL at a test copy of Bacon.`);
+                } else if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOCAL_HOSTS.includes(url.hostname))) {
+                    problems.push('BACON_API_URL must be https (plain http only for localhost).');
+                } else {
+                    apiUrl = url.origin;
+                }
+            }
+        }
+    }
+
+    let payTo = network?.payTo ?? null;
+    const rawPayTo = read('BACON_PAY_TO');
+    if (network?.testnet) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(rawPayTo)) {
+            problems.push('BACON_NETWORK=base-sepolia needs BACON_PAY_TO: the receiving address of the test copy of Bacon, so payments to anyone else are refused.');
+        } else {
+            payTo = rawPayTo;
+        }
+    } else if (network && rawPayTo && rawPayTo.toLowerCase() !== network.payTo) {
+        problems.push('BACON_PAY_TO cannot change Bacon\'s receiving address on Base; leave it unset.');
+    }
+
+    const limits = {};
+    for (const [key, name] of [['perCall', 'BACON_MAX_PER_CALL'], ['perSession', 'BACON_MAX_PER_SESSION'], ['perDay', 'BACON_MAX_PER_DAY']]) {
+        try {
+            limits[key] = parseUsdc(read(name) || DEFAULT_LIMITS[key], name);
+            if (limits[key] <= 0n) {
+                problems.push(`${name} must be more than 0.`);
+            }
+        } catch (error) {
+            problems.push(error.message);
+        }
+    }
+
+    const confirm = (read('BACON_CONFIRM') || 'auto').toLowerCase();
+    if (!CONFIRM_MODES.includes(confirm)) {
+        problems.push(`BACON_CONFIRM must be auto, always or never (got "${confirm}").`);
+    }
+
+    const rpcUrl = read('BACON_RPC_URL') || network?.rpcUrl || null;
+
+    return {
+        problems,
+        network,
+        apiUrl,
+        payTo,
+        limits,
+        confirm,
+        rpcUrl,
+        ledgerDir: read('BACON_LEDGER_DIR') || join(home, '.baconservices-mcp'),
+        discloseBalance: /^(1|true|yes)$/i.test(read('BACON_DISCLOSE_BALANCE')),
+    };
+}