byclaw-mcp 0.4.11 → 0.4.13

package/dist/index.js

@@ -4,6 +4,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const fs_1 = require("fs");
+const path_1 = require("path");
+// Single source of truth for the version string. Used in serverInfo,
+// startup banner, User-Agent, and as a [byclaw-mcp vX.Y.Z] prefix on
+// every tool description so MCP clients (and the model running inside
+// them) can see at a glance which version they're talking to without
+// peeking at the MCP-internal serverInfo handshake metadata.
+const SERVER_VERSION = (() => {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+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.';
 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
@@ -22,7 +57,7 @@ async function fetchImageBase64(url) {
     try {
         const res = await fetch(url, {
             signal: AbortSignal.timeout(8000),
-            headers: { 'User-Agent': 'Mozilla/5.0 (compatible; byclaw-mcp/0.4.11)' },
+            headers: { 'User-Agent': `Mozilla/5.0 (compatible; byclaw-mcp/${SERVER_VERSION})` },
             redirect: 'follow',
         });
         if (!res.ok)
@@ -50,7 +85,7 @@ async function apiCall(path, options = {}) {
     });
     return res.json();
 }
-const server = new index_js_1.Server({ name: 'byclaw', version: '0.4.11' }, { capabilities: { tools: {}, prompts: {} } });
+const server = new index_js_1.Server({ name: 'byclaw', version: SERVER_VERSION }, { capabilities: { tools: {}, prompts: {} } });
 // Prompts
 server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async () => ({
     prompts: [{
@@ -61,7 +96,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), and `disclosure` (string).\n\nWhen presenting the result:\n1. Render the picked product image inline using markdown image syntax: `![title](image_url)`. Do the same for every alternative — users need to SEE what they\'re being recommended.\n2. Show the recommended product with its price and the advisor\'s reasoning\n3. Link the recommendation using its `affiliate_url` field (format: "<merchant> →" as a clickable link)\n4. List every alternative with its title, price, merchant and link each using its `affiliate_url` field — do not show alternatives as plain text, they must be clickable links and visible images\n5. ALWAYS display the `disclosure` text verbatim at the end, as a small italic note — this is legally required\n\nThe server also emits native MCP image content blocks alongside the JSON for clients that render them natively (Claude Code). Markdown-only clients (Claude Desktop today) should render via `image_url`. If your client supports both, prefer markdown so the order matches the textual context.\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` (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.' },
         }],
 }));
 // ═══════════════════════════════════════
@@ -72,7 +107,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ── Core: one-shot shopping ──
         {
             name: 'shop',
-            description: '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). Render every product image inline using markdown image syntax: `![title](image_url)`. The server also emits native MCP image content blocks for clients that render them natively — use whichever your client supports, prefer markdown when in doubt.',
+            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.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -88,7 +123,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ── Optional: browse & explore ──
         {
             name: 'search_products',
-            description: '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) — render it inline with markdown `![title](image_url)` so users see what each product looks like.',
+            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)`).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -103,7 +138,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'leave_review',
-            description: 'Write a product review. Only call if the user explicitly asks to leave a review. Only de and en allowed.',
+            description: TOOL_PREFIX + 'Write a product review. Only call if the user explicitly asks to leave a review. Only de and en allowed.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -119,17 +154,17 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         // ── Discovery ──
         {
             name: 'list_categories',
-            description: 'Browse all available product categories.',
+            description: TOOL_PREFIX + 'Browse all available product categories.',
             inputSchema: { type: 'object', properties: {} },
         },
         {
             name: 'get_trending',
-            description: 'Get trending products that agents are buying right now.',
+            description: TOOL_PREFIX + 'Get trending products that agents are buying right now.',
             inputSchema: { type: 'object', properties: {} },
         },
         {
             name: 'get_product_reviews',
-            description: 'Get agent reviews for a product.',
+            description: TOOL_PREFIX + 'Get agent reviews for a product.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -139,13 +174,13 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
         },
         {
             name: 'get_platform_stats',
-            description: 'Get platform statistics: products compared, reviews written, recommendations sent.',
+            description: TOOL_PREFIX + 'Get platform statistics: products compared, reviews written, recommendations sent.',
             inputSchema: { type: 'object', properties: {} },
         },
         // ── QA / Testing ──
         {
             name: 'test_web_search',
-            description: 'Test the web agent search endpoint (same as dashboard search). Use for QA to verify web search behavior vs MCP shop behavior.',
+            description: TOOL_PREFIX + 'Test the web agent search endpoint (same as dashboard search). Use for QA to verify web search behavior vs MCP shop behavior.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -279,6 +314,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                             alternatives: d.gift_picks.slice(1).map((p) => p.title),
                         };
                         return { content: [{ type: 'text', text: JSON.stringify({
+                                        _render_hint: RENDER_HINT,
                                         type: 'gift_found',
                                         advisor: advisorLabel,
                                         advisor_profile: d.advisor_profile || null,
@@ -352,6 +388,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                     else {
                         const hasPick = !!d.picked;
                         content.push({ type: 'text', text: JSON.stringify({
+                                _render_hint: RENDER_HINT,
                                 type: d.status || 'product_found',
                                 advisor: advisorLabel,
                                 advisor_profile: d.advisor_profile || null,
@@ -425,7 +462,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                         result.data = result.data.map((p) => ({ ...p, image_url: imageUrlOf(p) }));
                     }
                 }
-                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+                return { content: [{ type: 'text', text: JSON.stringify({ _render_hint: RENDER_HINT, ...result }, null, 2) }] };
             }
             case 'leave_review': {
                 const lang = args?.language;
@@ -498,6 +535,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 // Gift responses
                 if (d.status === 'gift_found' && d.gift_picks) {
                     return { content: [{ type: 'text', text: JSON.stringify({
+                                    _render_hint: RENDER_HINT,
                                     type: 'gift_found',
                                     advisor: d.advisor_profile?.name || d.agent?.personality || null,
                                     advisor_profile: d.advisor_profile || null,
@@ -513,6 +551,7 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
                 // (no fallback to d.message — that produced bit-identical strings on no_match)
                 const hasPick = !!d.picked;
                 return { content: [{ type: 'text', text: JSON.stringify({
+                                _render_hint: RENDER_HINT,
                                 type: d.status || 'no_match',
                                 advisor: d.advisor_profile?.name || d.agent?.personality || null,
                                 advisor_profile: d.advisor_profile || null,
@@ -538,6 +577,6 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    console.error('byclaw MCP server v0.4.11 running on stdio');
+    console.error(`byclaw MCP server v${SERVER_VERSION} running on stdio`);
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byclaw-mcp",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "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": {