@bsvkey/inference-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Embryo Space Inc. (BSVKey)
+
+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

@@ -0,0 +1,68 @@
+# @bsvkey/inference-mcp
+
+An MCP server that lets any agent buy **Claude & Grok inference metered per token,
+settled in BSV**, through the hosted gateway at **inference.bsvkey.com**. Zero
+dependencies (Node ≥ 18, uses global `fetch`). It's a thin HTTP client — it never
+holds your keys or runs models; every call is billed through the gateway.
+
+Tools: `list_models`, `infer`, `channel_balance`, `open_channel`.
+
+## Quick start
+1. **Fund a channel once** at https://inference.bsvkey.com (BRC-100 wallet, or
+   load a key in-page). Copy the key it returns: `channelId:channelSecret`.
+2. **Add the MCP server** to your agent host (below), with that key in
+   `BSVKEY_API_KEY`.
+3. Ask your agent to run inference — it calls `infer` and pays per token.
+
+`list_models` and `open_channel` work with no key; `infer` and `channel_balance`
+need a funded channel key.
+
+## Install
+
+### Claude Code
+```bash
+claude mcp add bsvkey-inference \
+  --env BSVKEY_API_KEY=channelId:channelSecret \
+  -- node /absolute/path/to/integrations/mcp/server.js
+```
+Once published to npm, replace the command with `npx -y @bsvkey/inference-mcp`.
+
+### Claude Desktop / Codex / any MCP host (JSON config)
+```json
+{
+  "mcpServers": {
+    "bsvkey-inference": {
+      "command": "node",
+      "args": ["/absolute/path/to/integrations/mcp/server.js"],
+      "env": { "BSVKEY_API_KEY": "channelId:channelSecret" }
+    }
+  }
+}
+```
+After npm publish: `"command": "npx", "args": ["-y", "@bsvkey/inference-mcp"]`.
+
+## Configuration (env)
+| Var | Default | Meaning |
+|---|---|---|
+| `BSVKEY_BASE_URL` | `https://inference.bsvkey.com/v1` | Gateway base URL (set to a self-hosted deployment if you run your own). |
+| `BSVKEY_API_KEY` | — | `channelId:channelSecret` for a funded channel. Optional; can also be passed per call as `apiKey`. |
+
+## Verify it's wired (no key needed)
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_models","arguments":{}}}' \
+  | node server.js
+```
+
+## Marketplace listing blurb
+> **BSV Inference** — Pay-per-token Claude & Grok, settled in BSV. Prepay a channel
+> once, then meter every token with no subscription, account, or card. OpenAI-
+> compatible, optional live web search, on-chain settlement. MCP + portable SKILL.md.
+
+## Publishing (operator)
+- To make `npx @bsvkey/inference-mcp` work, publish this folder to npm
+  (`npm publish --access public`) from an account that owns the `@bsvkey` scope.
+- To list on a skills marketplace (e.g. bopen.ai), submit `SKILL.md` + this README.
+- Publishing is an operator action requiring your own credentials — not done here.

package/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: bsvkey-inference
+description: Use when an agent needs to pay PER TOKEN for Claude or Grok inference settled in BSV micropayments — buying LLM calls without a subscription, account, or credit card, through the hosted inference.bsvkey.com gateway. Triggers on "pay per token", "BSV inference", "micropayment inference", "buy an LLM call with bitcoin", "metered inference", "pay-as-you-go LLM", "settle inference on-chain", "HTTP 402 inference".
+---
+
+# BSV Inference — pay-per-token LLM calls, settled in BSV
+
+An OpenAI-compatible gateway that meters every token and settles in BSV
+micropayments. An agent prepays a channel once, then calls `infer` as many times
+as it wants — each call metered per token and drawn from the channel balance. No
+subscription, no account, no card. Models: Claude (haiku/sonnet/opus) and Grok
+(grok-4.3 fast, grok-4.6), with optional live web search.
+
+Install it as an MCP server (see README.md) — this skill assumes those four tools
+are available: `list_models`, `open_channel`, `infer`, `channel_balance`.
+
+## When to use
+- The user/agent wants to buy inference on demand and pay only for what it uses.
+- Micropayment / per-token billing is preferred over a monthly plan.
+- Settlement in BSV (or an on-chain, account-free payment) is desired.
+
+## How it works (the flow)
+1. **`list_models`** — no key needed. Returns live per-1,000-token prices in
+   satoshis (they float against the live BSV/USD rate) plus which models are
+   available. Use it to pick a model or a policy (`auto` = cheapest capable).
+2. **Fund a channel once.** Funding is a real BSV payment a wallet must sign, so
+   it's done at the website, not by the agent. Call **`open_channel`** for the
+   URL + steps: open `https://inference.bsvkey.com`, fund with a BRC-100 wallet
+   (or load a key in-page), and copy the returned key `channelId:channelSecret`.
+   Put it in `BSVKEY_API_KEY` (or pass `apiKey` to `infer`).
+3. **`infer`** — run inference, paid per token from the channel. Args: `prompt`,
+   `model` (default `auto`), optional `system`, `maxTokens`, `webSearch`. Returns
+   the completion plus a receipt: `charge` (sats), `routedTo`, `balanceSatsAfter`,
+   and `truncated` (true if a long web search was cut at the host time limit but
+   still billed).
+4. **`channel_balance`** — check remaining balance, spend, and request count.
+
+## Notes for the agent
+- Payments are REAL BSV. Treat channel funds like money: fund a small amount, top
+  up as needed.
+- `auto` routing picks the cheapest capable model; name a model explicitly
+  (`claude-sonnet-5`, `grok-4.3`, …) when quality or a specific provider matters.
+- `webSearch: true` adds a small per-search fee and lets the model use live web
+  data; grok-4.6 web searches can be slow and may be truncated (still billed).
+- To point at a self-hosted deployment, set `BSVKEY_BASE_URL`.

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@bsvkey/inference-mcp",
+  "version": "1.0.0",
+  "description": "MCP server: buy Claude & Grok inference metered per token, settled in BSV, through the hosted inference.bsvkey.com gateway.",
+  "type": "module",
+  "bin": { "bsvkey-inference-mcp": "server.js" },
+  "main": "server.js",
+  "engines": { "node": ">=18" },
+  "files": ["server.js", "SKILL.md", "README.md", "LICENSE"],
+  "keywords": ["mcp", "model-context-protocol", "bsv", "inference", "pay-per-token", "http-402", "x402", "claude", "grok", "micropayments", "agents"],
+  "author": "Embryo Space Inc. DBA BSVKey",
+  "license": "MIT",
+  "homepage": "https://inference.bsvkey.com"
+}

package/server.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// BSV Inference — remote MCP server (zero dependencies).
+//
+// A thin Model-Context-Protocol client for the HOSTED broker at
+// inference.bsvkey.com. Any MCP-capable agent host (Claude Code, Claude Desktop,
+// Codex, OpenCode, custom agents) adds this one command and can then buy Claude
+// or Grok inference metered PER TOKEN, settled in BSV — every call is billed
+// through the hosted gateway, so usage flows to the operator's wallet.
+//
+// This is NOT the broker. It never holds keys or runs models; it just talks HTTP
+// to the public API. Point it at your own deployment with BSVKEY_BASE_URL.
+//
+// Config (environment):
+//   BSVKEY_BASE_URL  default https://inference.bsvkey.com/v1
+//   BSVKEY_API_KEY   "channelId:channelSecret" for a funded channel (optional —
+//                    can also be passed per call as `apiKey`). Open + fund a
+//                    channel once at the website, then paste the key here.
+//
+// Run:  node server.js      (Node >= 18 for global fetch)
+
+const BASE = (process.env.BSVKEY_BASE_URL || 'https://inference.bsvkey.com/v1').replace(/\/+$/, '');
+const SITE = BASE.replace(/\/v1$/, '');
+const ENV_KEY = process.env.BSVKEY_API_KEY || '';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_INFO = { name: 'bsvkey-inference', version: '1.0.0' };
+
+// Resolve a channel API key ("channelId:channelSecret") from arg or env.
+function keyParts(apiKey) {
+  const k = String(apiKey || ENV_KEY || '').trim();
+  const i = k.indexOf(':');
+  if (i < 0) return null;
+  return { id: k.slice(0, i), secret: k.slice(i + 1), raw: k };
+}
+
+async function http(method, path, { headers = {}, body } = {}) {
+  const res = await fetch(BASE + path, {
+    method,
+    headers: { ...(body ? { 'content-type': 'application/json' } : {}), ...headers },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json;
+  try { json = text ? JSON.parse(text) : {}; } catch { json = { _raw: text.slice(0, 500) }; }
+  return { ok: res.ok, status: res.status, json };
+}
+
+export const TOOLS = [
+  {
+    name: 'list_models',
+    description:
+      'List the models this BSV inference gateway sells, with LIVE retail price (satoshis per 1,000 tokens) at the current BSV/USD rate. No key needed. Call first to choose a model.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+  {
+    name: 'infer',
+    description:
+      'Run one metered inference (OpenAI-compatible), paid per token in BSV from your prepaid channel. Returns the completion plus a receipt: satoshis charged, model routed to, and remaining balance. Requires a funded channel key (apiKey or BSVKEY_API_KEY).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'The user prompt.' },
+        model: { type: 'string', description: 'Model id or policy: auto|cheapest|best, claude-*, grok-*.', default: 'auto' },
+        system: { type: 'string', description: 'Optional system prompt.' },
+        maxTokens: { type: 'integer', description: 'Max output tokens.', default: 512 },
+        webSearch: { type: 'boolean', description: 'Let the model search the live web (adds a per-search fee).', default: false },
+        apiKey: { type: 'string', description: 'channelId:channelSecret for a funded channel. Omit to use BSVKEY_API_KEY.' },
+      },
+      required: ['prompt'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'channel_balance',
+    description: 'Check a prepaid channel’s remaining BSV balance, spend, and request count.',
+    inputSchema: {
+      type: 'object',
+      properties: { apiKey: { type: 'string', description: 'channelId:channelSecret. Omit to use BSVKEY_API_KEY.' } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'open_channel',
+    description:
+      'Explains how to open + fund a prepaid channel. Funding is a real BSV payment signed by a wallet, so it is done once at the website; you then paste the returned channel key here (or set BSVKEY_API_KEY).',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  },
+];
+
+async function callTool(name, args = {}) {
+  switch (name) {
+    case 'list_models': {
+      const r = await http('GET', '/pricebook');
+      if (!r.ok) throw new Error(`pricebook ${r.status}`);
+      const pb = r.json;
+      const models = Object.entries(pb.models || {}).map(([id, m]) => ({
+        id,
+        label: m.label,
+        available: m.available !== false,
+        provider: m.provider,
+        retailInputSatsPer1k: m.retailInputSatsPer1k,
+        retailOutputSatsPer1k: m.retailOutputSatsPer1k,
+      }));
+      return { base: BASE, bsvUsd: pb.bsvUsd, rate: pb.rate, models, webSearch: pb.webSearch };
+    }
+    case 'infer': {
+      const k = keyParts(args.apiKey);
+      if (!k) throw new Error('No channel key. Pass apiKey "channelId:channelSecret" or set BSVKEY_API_KEY. Open one via the open_channel tool.');
+      const r = await http('POST', '/chat/completions', {
+        headers: { authorization: `Bearer ${k.raw}` },
+        body: {
+          model: args.model || 'auto',
+          messages: [
+            ...(args.system ? [{ role: 'system', content: args.system }] : []),
+            { role: 'user', content: String(args.prompt || '') },
+          ],
+          max_tokens: args.maxTokens || 512,
+          web_search: args.webSearch === true,
+        },
+      });
+      if (!r.ok) {
+        const msg = r.json?.error?.message || r.json?.error || `inference failed (${r.status})`;
+        throw new Error(typeof msg === 'string' ? msg : JSON.stringify(msg));
+      }
+      const x = r.json.x_bsv || {};
+      return {
+        model: r.json.model || args.model,
+        completion: r.json.choices?.[0]?.message?.content ?? '',
+        charge: x.charge,
+        routedTo: x.routedTo,
+        balanceSatsAfter: x.balanceSatsAfter,
+        truncated: x.truncated || false,
+      };
+    }
+    case 'channel_balance': {
+      const k = keyParts(args.apiKey);
+      if (!k) throw new Error('No channel key. Pass apiKey "channelId:channelSecret" or set BSVKEY_API_KEY.');
+      const r = await http('GET', `/channels/${encodeURIComponent(k.id)}`, { headers: { 'x-bsv-channel-secret': k.secret } });
+      if (!r.ok) {
+        const msg = r.json?.error?.message || r.json?.error || `balance check failed (${r.status})`;
+        throw new Error(typeof msg === 'string' ? msg : JSON.stringify(msg));
+      }
+      return r.json;
+    }
+    case 'open_channel': {
+      return {
+        note: 'Funding a channel is a real BSV payment your wallet must sign, so open one at the website (BRC-100 wallet, or load a key in-page), then paste the channel key here / set BSVKEY_API_KEY.',
+        fundUrl: SITE,
+        accountUrl: `${SITE}/account.html`,
+        steps: [
+          `Open ${SITE} and use the "Pay with your BSV wallet" widget to fund a channel.`,
+          'Copy the channel key it returns (format: channelId:channelSecret).',
+          'Set BSVKEY_API_KEY to that value (or pass apiKey to infer), then call infer freely until the balance runs out.',
+        ],
+      };
+    }
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+// --- MCP JSON-RPC over stdio ------------------------------------------------
+function result(id, value) { return { jsonrpc: '2.0', id, result: value }; }
+function rpcError(id, code, message) { return { jsonrpc: '2.0', id, error: { code, message } }; }
+
+export async function handleMessage(msg) {
+  if (!msg || msg.jsonrpc !== '2.0') return rpcError(msg?.id ?? null, -32600, 'invalid request');
+  const { id, method, params } = msg;
+  switch (method) {
+    case 'initialize':
+      return result(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO });
+    case 'notifications/initialized':
+    case 'initialized':
+      return null;
+    case 'ping':
+      return result(id, {});
+    case 'tools/list':
+      return result(id, { tools: TOOLS });
+    case 'tools/call': {
+      try {
+        const value = await callTool(params?.name, params?.arguments || {});
+        return result(id, { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+      } catch (e) {
+        return result(id, { content: [{ type: 'text', text: `error: ${e.message}` }], isError: true });
+      }
+    }
+    default:
+      if (id === undefined) return null;
+      return rpcError(id, -32601, `method not found: ${method}`);
+  }
+}
+
+function runStdio() {
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', async (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { process.stdout.write(JSON.stringify(rpcError(null, -32700, 'parse error')) + '\n'); continue; }
+      const res = await handleMessage(msg);
+      if (res) process.stdout.write(JSON.stringify(res) + '\n');
+    }
+  });
+  process.stderr.write(`[bsvkey-inference mcp] ready on stdio → ${BASE} (${TOOLS.length} tools)\n`);
+}
+
+const invokedDirectly = process.argv[1] && /server\.js$/.test(process.argv[1]);
+if (invokedDirectly) runStdio();