@blockrun/mcp 0.22.1 → 0.22.3

package/README.md

@@ -93,6 +93,14 @@ claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest
 The `-s user` flag installs globally (available in every project). The `--` separator
 ensures `-y` is passed to `npx`, not parsed by `claude mcp add`.
 
+> 💡 **Homebrew / nvm users:** if the server doesn't connect after install, Claude Code
+> likely can't find `node`/`npx` on its launcher PATH. Install with your shell PATH passed
+> through — works on CLI and desktop:
+> ```bash
+> claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest
+> ```
+> See [Troubleshooting](#troubleshooting) if it persists.
+
 **Tool profiles** — expose a trimmed tool set so the client loads fewer schemas into
 context. Pass `--profile <name>` (or set `BLOCKRUN_MCP_PROFILE`); omit it for the full set.
 
@@ -179,7 +187,7 @@ Then send USDC (SPL) on the **Solana** network — from Coinbase (pick "Solana")
 | Tool | Data source | Cost |
 |------|-------------|------|
 | `blockrun_chat` | 66+ LLMs (GPT, Claude, Gemini, DeepSeek, Kimi K2.6, GLM, NVIDIA free tier, ...) with `mode` tier routing | per token |
-| `blockrun_image` | GPT Image 1/2, Nano Banana / Pro (up to 4K), Grok Imagine, CogView-4 — generation + img2img editing | $0.015–0.15 |
+| `blockrun_image` | Generation: openai/gpt-image-2 ($0.06–0.12) — flagship, reasoning + text; openai/gpt-image-1 ($0.02–0.04); google/nano-banana ($0.05) / nano-banana-pro ($0.10–0.15, 4K); xai/grok-imagine-image ($0.02) / -pro ($0.07); zai/cogview-4 ($0.015). Edit: openai/gpt-image-*, google/nano-banana* (img2img, inpaint, fusion). | $0.015–0.15 |
 | `blockrun_video` | Sora 2 + xAI Grok Imagine Video + ByteDance Seedance 1.5/2.0/2.0-fast (720p + audio defaults); RealFace asset → real-person video | $0.05–0.30/sec |
 | `blockrun_realface` | Enroll a real person (phone liveness) or an AI character (Virtual Portrait, no liveness) as a `ta_xxxx` asset for Seedance 2.0 video | free; $0.01 to enroll |
 | `blockrun_music` | MiniMax music generation | per track |
@@ -281,7 +289,13 @@ Delegate a spending budget to a child agent with `agent_id`. The child is auto-b
 
 - **`Insufficient balance` / HTTP 402 after retry** → Run `blockrun_wallet action:"setup"`. Send USDC on Base (or Solana — see [Environment Variables](#environment-variables)).
 - **`Smart routing (ClawRouter) is not available on Solana`** → Pass `model:` or `mode:` explicitly to `blockrun_chat`, or switch back to Base with `echo base > ~/.blockrun/.chain`.
-- **`claude mcp list` doesn't show `blockrun`** → Check `node -v` (must be ≥18). Clear the npx cache: `rm -rf ~/.npm/_npx`. Re-run the install command from above.
+- **`blockrun` doesn't connect / "MCP server failed" / `spawn npx ENOENT`** → Almost always a **PATH issue**: Claude Code can't find `node`/`npx` on the PATH its MCP launcher uses. Common with **Homebrew** (`/opt/homebrew/bin`) or **nvm**, where node isn't on that PATH — and it affects the **CLI as well as the desktop app** (the launcher doesn't always inherit your interactive shell PATH). Fix by passing your shell PATH at install:
+  ```bash
+  claude mcp remove blockrun -s user
+  claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@latest
+  ```
+  Then restart Claude Code (or `/mcp` to reconnect — MCP tools load at session start). Or pin absolute paths: `claude mcp add blockrun -s user -- /opt/homebrew/bin/npx -y @blockrun/mcp@latest` (use `which npx` for your path).
+- **`claude mcp list` doesn't show `blockrun`** → Check `node -v` (must be ≥18). Clear the npx cache: `rm -rf ~/.npm/_npx`. Re-run the install command from above (see the PATH fix above if node/npx aren't found).
 - **`fetch failed` / timeout when checking wallet balance** → Base RPC transient outage. The tool already falls through 3 public RPCs; retry after 30s. Persistent failures usually = local proxy / firewall blocking outbound RPC.
 - **`ENOENT: ~/.blockrun/.session`** → Expected on first run. The server auto-creates the wallet; check stderr for the `WALLET_CREATED` line confirming the address.
 - **`Video generation timed out` (5-min cap)** → Upstream Seedance / xAI queue congestion. **No charge** (payment-on-completion). Retry, or pick a faster model (`bytedance/seedance-1.5-pro`).

package/dist/index.js

@@ -1104,6 +1104,43 @@ ${lines.join("\n")}` }],
 // src/tools/image.ts
 import { z as z4 } from "zod";
 import { PaymentError } from "@blockrun/llm";
+import { readFile } from "fs/promises";
+var REFERENCE_IMAGE_MAX_BYTES = 4e6;
+var IMAGE_EXT_MIME = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp"
+};
+async function toImageDataUri(ref) {
+  if (ref.startsWith("data:image/")) return ref;
+  if (/^https?:\/\//i.test(ref)) {
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), 3e4);
+    try {
+      const res = await fetch(ref, { signal: ctrl.signal });
+      if (!res.ok) throw new Error(`fetch failed: ${res.status} ${res.statusText}`);
+      const mime2 = (res.headers.get("content-type") || "").toLowerCase().split(";")[0].trim();
+      if (!mime2.startsWith("image/")) throw new Error(`URL returned non-image content-type: ${mime2 || "(none)"}`);
+      const buffer2 = Buffer.from(await res.arrayBuffer());
+      if (buffer2.byteLength > REFERENCE_IMAGE_MAX_BYTES) {
+        throw new Error(`image too large: ${(buffer2.byteLength / 1e6).toFixed(1)}MB > ${REFERENCE_IMAGE_MAX_BYTES / 1e6}MB cap`);
+      }
+      return `data:${mime2};base64,${buffer2.toString("base64")}`;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  const ext = ref.split(".").pop()?.toLowerCase() ?? "";
+  const mime = IMAGE_EXT_MIME[ext];
+  if (!mime) throw new Error(`unsupported image extension ".${ext}"; use png/jpg/jpeg/gif/webp`);
+  const buffer = await readFile(ref);
+  if (buffer.byteLength > REFERENCE_IMAGE_MAX_BYTES) {
+    throw new Error(`image too large: ${(buffer.byteLength / 1e6).toFixed(1)}MB > ${REFERENCE_IMAGE_MAX_BYTES / 1e6}MB cap; resize or crop first`);
+  }
+  return `data:${mime};base64,${buffer.toString("base64")}`;
+}
 var GENERATE_MODEL_COST = {
   "zai/cogview-4": 0.015,
   "xai/grok-imagine-image": 0.02,
@@ -1125,6 +1162,11 @@ var EDIT_MODELS = /* @__PURE__ */ new Set([
   "google/nano-banana",
   "google/nano-banana-pro"
 ]);
+var MAX_EDIT_IMAGES_BY_PREFIX = {
+  "openai/": 4,
+  "google/": 3
+};
+var MASK_MODELS = /* @__PURE__ */ new Set(["openai/gpt-image-1", "openai/gpt-image-2"]);
 var IMAGE_MODELS = [
   "zai/cogview-4",
   "google/nano-banana",
@@ -1160,18 +1202,21 @@ Generation models (1024x1024 base price; larger sizes cost more on gpt-image-*):
 - xai/grok-imagine-image-pro ($0.07) \u2014 higher quality Grok Imagine
 - zai/cogview-4 ($0.015) \u2014 cheapest, photorealistic detailed scenes
 
-Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/nano-banana, google/nano-banana-pro`,
+Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/nano-banana, google/nano-banana-pro
+Multi-image edit: pass an array of 2\u20134 source images to "image" to fuse them in one render (openai/* up to 4, google/* up to 3) \u2014 e.g. a subject plus a sprite layout guide, or a reference plus a brand logo.
+Source images and masks accept a base64 data URI, an http(s) URL, or a local file path (auto-encoded). Inpaint mask (openai/gpt-image-* only) via "mask"; not combinable with multiple source images.`,
       inputSchema: {
         prompt: z4.string().describe("Image description or edit instructions"),
         action: z4.enum(["generate", "edit"]).optional().default("generate").describe("generate: create from text; edit: transform existing image"),
         model: z4.enum(IMAGE_MODELS).optional().describe("Model to use (default: openai/gpt-image-2 for both generate and edit). gpt-image-2 renders on-image text best; nano-banana-pro for 4K photorealism; cogview-4 / grok-imagine-image for cheap drafts."),
-        image: z4.string().optional().describe("Source image for edit action: base64-encoded image or URL"),
+        image: z4.union([z4.string(), z4.array(z4.string()).min(1).max(4)]).optional().describe("Source image(s) for edit action: a base64 data URI, an http(s) URL, or a local file path (auto-encoded to a data URI) \u2014 or an array of 2\u20134 to fuse into one render (e.g. subject + layout guide, or reference + brand logo). openai/* accepts up to 4, google/* up to 3; a mask cannot be combined with multiple images."),
+        mask: z4.string().optional().describe("Inpaint mask for edit action (openai/gpt-image-* only): a base64 data URI, http(s) URL, or local file path. Transparent areas of the mask are regenerated. Cannot be combined with multiple source images."),
         size: z4.string().optional().default("1024x1024").describe("Image size. Common values: 1024x1024 (all models), 1536x1024 / 1024x1536 (gpt-image-*), 2048x2048 / 4096x4096 (nano-banana-pro)"),
         quality: z4.enum(["standard", "hd"]).optional().default("standard"),
         agent_id: z4.string().optional().describe("Agent identifier for budget tracking and enforcement.")
       }
     },
-    async ({ prompt, action, model, image, size, quality, agent_id }) => {
+    async ({ prompt, action, model, image, mask, size, quality, agent_id }) => {
       try {
         if (getChain() !== "base") {
           return {
@@ -1194,6 +1239,40 @@ Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/
               isError: true
             };
           }
+          const sourceImages = Array.isArray(image) ? image : [image];
+          const maxImages = MAX_EDIT_IMAGES_BY_PREFIX[`${selectedModel.split("/")[0]}/`] ?? 1;
+          if (sourceImages.length > maxImages) {
+            return {
+              content: [{ type: "text", text: formatError(`${selectedModel} accepts at most ${maxImages} source image${maxImages > 1 ? "s" : ""} per edit (got ${sourceImages.length}).`) }],
+              isError: true
+            };
+          }
+          if (mask) {
+            if (!MASK_MODELS.has(selectedModel)) {
+              return {
+                content: [{ type: "text", text: formatError("mask (inpaint) is supported only by openai/gpt-image-1 and openai/gpt-image-2") }],
+                isError: true
+              };
+            }
+            if (sourceImages.length > 1) {
+              return {
+                content: [{ type: "text", text: formatError("mask cannot be combined with multiple source images; send a single image with a mask, or multiple images without a mask") }],
+                isError: true
+              };
+            }
+          }
+          let normalizedImage;
+          let normalizedMask;
+          try {
+            const dataUris = await Promise.all(sourceImages.map(toImageDataUri));
+            normalizedImage = dataUris.length === 1 ? dataUris[0] : dataUris;
+            if (mask) normalizedMask = await toImageDataUri(mask);
+          } catch (e) {
+            return {
+              content: [{ type: "text", text: formatError(`Could not load source image: ${e instanceof Error ? e.message : String(e)}`) }],
+              isError: true
+            };
+          }
           const estimatedCost = estimateCost(selectedModel, size);
           const budgetCheck = checkBudget(budget, agent_id, estimatedCost);
           if (!budgetCheck.allowed) {
@@ -1202,9 +1281,10 @@ Edit (img2img) models: openai/gpt-image-2 (default), openai/gpt-image-1, google/
               isError: true
             };
           }
-          response = await getImageClient().edit(prompt, image, {
+          response = await getImageClient().edit(prompt, normalizedImage, {
             model: selectedModel,
-            size
+            size,
+            ...normalizedMask ? { mask: normalizedMask } : {}
           });
           recordSpending(budget, estimatedCost, agent_id);
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Give your AI agent web search, deep research, prediction markets, crypto data, X/Twitter intelligence. Paid via x402 micropayments.",
   "type": "module",