byclaw-mcp 0.4.13 → 0.4.15

package/dist/index.js

@@ -21,24 +21,26 @@ const SERVER_VERSION = (() => {
     }
 })();
 const TOOL_PREFIX = `[byclaw-mcp v${SERVER_VERSION}] `;
-// Different MCP clients render product images very differently:
-//   - Claude Code / Cursor: render `![title](image_url)` markdown inline,
-//     and also render native MCP image content blocks → markdown wins by
-//     keeping ordering aligned with text.
-//   - claude.ai web + Claude Desktop App: render NEITHER external markdown
-//     images NOR MCP image content blocks from tool results in the user UI.
-//     Inline images only show when wrapped in an HTML artifact (the model
-//     calls a `visualize`/`show_widget`-style tool, e.g.
-//     `mcp__visualize__show_widget`, with `<img src="...">` inside).
-// We surface this hint in every product_found tool result and in the tool
-// descriptions so the model can pick the right rendering for its client
-// without us having to detect the client server-side.
-const RENDER_HINT = 'If your client renders external images inline (Claude Code, Cursor, etc.), ' +
-    'emit `![title](image_url)` markdown for each product. ' +
-    'If your client does NOT render external images in chat (claude.ai web, ' +
-    'Claude Desktop App), wrap the picked product and every alternative in an ' +
-    'HTML artifact via the `visualize`/`show_widget` tool with `<img src="image_url">` ' +
-    'tags, so the user actually sees the products. The affiliate_url is the buy link.';
+// Render guidance for the model. Stays consistent across clients now:
+//   - Claude Code / Cursor / browsers: inline images via `![title](image_url)`
+//     work directly.
+//   - claude.ai web + Claude Desktop App: same markdown renders as a
+//     "Bild anzeigen" click-to-load placeholder (their external-image
+//     privacy gate). We accept this — Finding 093 ruled out HTML artifact
+//     widgets (sandbox CSP blocks our CDNs) and inline base64 (too many
+//     tokens / too slow). Placeholder is the cheapest acceptable UX.
+// Surfaced in every shop / search_products / test_web_search response as
+// the `_render_hint` field so the model never falls back to widget tricks.
+const RENDER_HINT = 'Emit `![title](image_url)` markdown for each product inline with the text. ' +
+    'Clients render this differently: Claude Code / Cursor / browsers show the ' +
+    'image immediately; claude.ai web + Claude Desktop App show a "Bild anzeigen" ' +
+    'click-to-load placeholder (their privacy gate for external images) — that ' +
+    'is acceptable, do not try to work around it with HTML widgets or any other ' +
+    'tool, the artifact sandbox CSP blocks our CDNs and the user just gets empty ' +
+    'boxes. The placeholder is the best we get in claude.ai today. Always wrap ' +
+    'each product\'s merchant link as a clickable "<merchant> →" using ' +
+    'affiliate_url. Keep replies tight — one image-markdown line + one buy line ' +
+    'per product.';
 const API_BASE = process.env.BYCLAW_API_URL || 'https://byclaw.io';
 const API_KEY = process.env.BYCLAW_API_KEY || '';
 // Brand fallback when the catalog row has no image. Clients (Claude Desktop
@@ -51,39 +53,43 @@ function imageUrlOf(p) {
     const url = typeof p?.image_url === 'string' ? p.image_url.trim() : '';
     return url.startsWith('https://') || url.startsWith('http://') ? url : IMAGE_FALLBACK;
 }
-async function fetchImageBase64(url) {
-    if (!url || url.includes('picsum.photos'))
-        return null;
-    try {
-        const res = await fetch(url, {
-            signal: AbortSignal.timeout(8000),
-            headers: { 'User-Agent': `Mozilla/5.0 (compatible; byclaw-mcp/${SERVER_VERSION})` },
-            redirect: 'follow',
-        });
-        if (!res.ok)
-            return null;
-        const contentType = res.headers.get('content-type') || 'image/jpeg';
-        if (!contentType.startsWith('image/'))
-            return null;
-        const buffer = await res.arrayBuffer();
-        if (buffer.byteLength < 100 || buffer.byteLength > 500000)
-            return null; // skip tiny errors or huge files
-        return { data: Buffer.from(buffer).toString('base64'), mimeType: contentType };
-    }
-    catch {
-        return null;
-    }
-}
+// Hard cap on every backend request. Without it, if the backend is wedged
+// (Anthropic 503 + SDK retry storm, ES lock, …) the MCP process would hang
+// forever and the client (Claude Desktop) would only break out at its own
+// 4 min cap with a "Server disconnected" disconnect — the very symptom
+// Finding 094 described. 60 s is comfortably above normal backend latency
+// (10-15 s for /api/mcp/shop) but below the client timeout, so the user
+// gets a real error message instead of a stall.
+const BACKEND_TIMEOUT_MS = 60000;
 async function apiCall(path, options = {}) {
     const headers = {
         'Authorization': `Bearer ${API_KEY}`,
         'Content-Type': 'application/json',
     };
-    const res = await fetch(`${API_BASE}${path}`, {
-        ...options,
-        headers: { ...headers, ...options.headers },
-    });
-    return res.json();
+    try {
+        const res = await fetch(`${API_BASE}${path}`, {
+            ...options,
+            signal: AbortSignal.timeout(BACKEND_TIMEOUT_MS),
+            headers: { ...headers, ...options.headers },
+        });
+        return res.json();
+    }
+    catch (err) {
+        // AbortError fires when the timeout above kicks in. Translate to an
+        // ok=false body the existing call sites already know how to print.
+        if (err?.name === 'AbortError' || err?.name === 'TimeoutError') {
+            return {
+                ok: false,
+                error: `Backend timeout after ${BACKEND_TIMEOUT_MS / 1000}s (${path})`,
+                retryable: true,
+            };
+        }
+        return {
+            ok: false,
+            error: `Backend request failed: ${err?.message || 'unknown error'} (${path})`,
+            retryable: false,
+        };
+    }
 }
 const server = new index_js_1.Server({ name: 'byclaw', version: SERVER_VERSION }, { capabilities: { tools: {}, prompts: {} } });
 // Prompts
@@ -96,7 +102,7 @@ server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async () => ({
 server.setRequestHandler(types_js_1.GetPromptRequestSchema, async () => ({
     messages: [{
             role: 'user',
-            content: { type: 'text', text: 'You are connected to byclaw.io — a product comparison platform that searches across thousands of online shops to find the best products. When the user asks for a product, use the "shop" tool.\n\nThe tool returns structured JSON with: `picked` (title, price, brand, merchant, affiliate_url, image_url), `alternatives` (each with title, price, brand, merchant, affiliate_url, image_url), `compared` (int), `reasoning` (string), `review` (string), `disclosure` (string), and `_render_hint` (string).\n\n**Image rendering** — different clients need different approaches and the response\'s `_render_hint` field tells you which one to use:\n  • If running inside **claude.ai web or Claude Desktop App**, the chat UI does NOT render external markdown images or MCP image content blocks. You MUST surface the products via an HTML artifact — call the `visualize` / `show_widget`-style tool and emit `<img src="image_url">` tags inside the widget so the user actually sees the products.\n  • If running inside **Claude Code, Cursor, or another MCP client with inline image support**, emit `![title](image_url)` markdown for each product directly in your reply.\n\nWhen presenting the result:\n1. Follow `_render_hint` for images (HTML widget on claude.ai/Desktop, markdown elsewhere).\n2. Show the recommended product with its price and the advisor\'s reasoning.\n3. Link the recommendation using its `affiliate_url` field as a clickable link (label: "<merchant> →").\n4. List every alternative with its title, price, merchant and link each using its `affiliate_url` field — never as plain text.\n5. ALWAYS display the `disclosure` text verbatim at the end, as a small italic note — this is legally required.\n\nbyclaw.io is operated by NJUDEV S.L., a European company.' },
+            content: { type: 'text', text: 'You are connected to byclaw.io — a product comparison platform that searches across thousands of online shops to find the best products. When the user asks for a product, use the "shop" tool.\n\nThe tool returns structured JSON with: `picked` (title, price, brand, merchant, affiliate_url, image_url), `alternatives` (same fields), `compared` (int), `reasoning` (string), `review` (string), `disclosure` (string), and `_render_hint` (string).\n\n**Presenting the result:**\n1. For each product (picked first, then each alternative), emit one image markdown line `![title](image_url)` and one buy line as a clickable `[<merchant> →](affiliate_url)`. Keep replies tight — image line + buy line per product, plus a one-sentence rationale below the picked.\n2. Claude Code / Cursor / browsers render the image inline. claude.ai web + Claude Desktop App show a "Bild anzeigen" click-to-load placeholder — accept that, do not try HTML widgets or other workarounds (the artifact sandbox blocks our CDNs).\n3. ALWAYS display the `disclosure` text verbatim at the end as a small italic note — this is legally required.\n\nbyclaw.io is operated by NJUDEV S.L., a European company.' },
         }],
 }));
 // ═══════════════════════════════════════
@@ -107,7 +113,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ── Core: one-shot shopping ──
         {
             name: 'shop',
-            description: TOOL_PREFIX + 'Search and compare products across multiple shops. Returns a JSON object with `picked` (the recommendation) and `alternatives` (other candidates). Each product object includes `title`, `price`, `brand`, `merchant`, `affiliate_url`, and `image_url` (absolute HTTPS URL). The response also includes a `_render_hint` field that tells you exactly how to display images for your current client: claude.ai / Claude Desktop need an HTML artifact via the `visualize`/`show_widget` tool with `<img>` tags; Claude Code / Cursor / other MCP clients with image support can use markdown `![title](image_url)` directly. ALWAYS follow that `_render_hint` so the user actually sees the products. The server additionally emits native MCP image content blocks for clients that render them natively.',
+            description: TOOL_PREFIX + 'Search and compare products across multiple shops. Returns a JSON object with `picked` (the recommendation) and `alternatives` (other candidates). Each product object includes `title`, `price`, `brand`, `merchant`, `affiliate_url`, and `image_url` (absolute HTTPS URL). Emit `![title](image_url)` markdown for each product so the image renders inline in clients that support it (Claude Code, Cursor, browsers). claude.ai web / Claude Desktop App will show a click-to-load placeholder for those markdown images — that is fine, accept it. Do NOT try to build HTML widgets or other workarounds; the artifact sandbox blocks our product CDNs. See `_render_hint` in every response for the exact rendering recipe.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -123,7 +129,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ── Optional: browse & explore ──
         {
             name: 'search_products',
-            description: TOOL_PREFIX + 'Browse products without triggering a recommendation. Use this only if the user explicitly wants to see a list of options. Each result item has `image_url` (absolute HTTPS URL). The response includes a `_render_hint` field — follow it to pick markdown vs HTML-widget rendering for the current client (claude.ai/Desktop need an HTML widget; Claude Code/Cursor can use markdown `![title](image_url)`).',
+            description: TOOL_PREFIX + 'Browse products without triggering a recommendation. Use this only if the user explicitly wants to see a list of options. Each result item has `image_url` (absolute HTTPS URL). Emit `![title](image_url)` markdown inline; claude.ai web / Desktop will gate it behind a click-to-load placeholder, other clients render directly. See `_render_hint`.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -361,18 +367,11 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                     }, null, 2) }] };
                     }
                     // ── NORMAL / FOLLOW-UP MODE ──
+                    // No more server-side image prefetch — `image_url` is a plain
+                    // string in each product object, the client (or the model in
+                    // claude.ai-style clients) decides what to do with it. Cuts
+                    // ~1-8s of network round-trip per call.
                     const content = [];
-                    // Fetch all images in parallel (picked + up to 3 alternatives)
-                    const allProducts = [d.picked, ...(d.alternatives || []).slice(0, 3)];
-                    const allImages = await Promise.all(allProducts.map(async (p) => {
-                        if (!p?.image_url)
-                            return null;
-                        return fetchImageBase64(p.image_url);
-                    }));
-                    // Add picked image only when we actually have a product_found
-                    if (d.status === 'product_found' && allImages[0]) {
-                        content.push({ type: 'image', data: allImages[0].data, mimeType: allImages[0].mimeType });
-                    }
                     // F1: canonical fields. F6: no message_de/message_en. F2: no fallback to message.
                     if (d.status === 'no_match') {
                         content.push({ type: 'text', text: JSON.stringify({
@@ -416,11 +415,6 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                                 ...(d.note ? { note: d.note } : {}),
                             }, null, 2) });
                     }
-                    // Add alternative images
-                    allImages.slice(1).forEach((img) => {
-                        if (img)
-                            content.push({ type: 'image', data: img.data, mimeType: img.mimeType });
-                    });
                     // Track session for follow-ups (only on product_found, not no_match)
                     if (d.status !== 'no_match' && d.picked) {
                         lastShopContext = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byclaw-mcp",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "MCP Server for byclaw.io — Your AI shopping advisor. Connects Claude Desktop and other MCP clients to the byclaw.io product catalog.",
   "main": "dist/index.js",
   "bin": {
@@ -36,7 +36,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
-    "tsx": "^4.0.0"
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
   }
 }