@agentutility/mcp-retail 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @agentutility/mcp-retail
+
+> Product copy + product discovery, per call.
+
+Turn a product name into a marketing-ready description and selling points, and turn a shopping query into ranked products with buy links and prices. The e-commerce primitives a shopping or merchandising agent needs.
+
+**Pricing:** pay-per-call in USDC on Base. No subscriptions, no API keys. See per-tool prices below.
+
+## Install — Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agentutility-retail": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-retail"],
+      "env": { "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HEX" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. 5 tools appear in the tool palette.
+
+## Install — Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentutility-retail": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-retail"],
+      "env": { "X402_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+## Funding
+
+Send any amount of **USDC on Base mainnet** to the address derived from your `X402_PRIVATE_KEY`. The MCP server uses it to pay for tool calls automatically.
+
+USDC on Base contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+
+## Tools (5)
+
+| Tool | Description |
+|---|---|
+| `find-products` | (0.02 USDC/call) Find products API (alias of product-search). Returns ranked product results with buy links, retailer, snippet, and detected price for a shopping query. Backed by Decodo Google search scoped to buy intent. |
+| `product-describe` | (0.01 USDC/call) Product description generator / e-commerce copywriter / product listing copy / selling points API. Given a product name (and optional category, audience, attributes), returns a conversion-focused description, bullet selling points, key features, a positioning angle, and suggested listing titles. LLM-backed (Morpheus primary, Venice fallback). Generates copy from supplied facts; does not invent specs or claims. |
+| `product-description` | (0.01 USDC/call) Product description API (alias of product-describe). Turns a product name + attributes into a marketing-ready description, selling points, key features, and listing titles. LLM-backed; copy from supplied facts only. |
+| `product-search` | (0.02 USDC/call) Product search / shopping search API / find products + buy links for agents. Given a product query (and optional retailer), returns ranked shopping results with product title, buy link, retailer domain, snippet, and any detected price. Backed by Decodo Google search scoped to buy intent. For general web search use search/web-search. |
+| `shop-search` | (0.02 USDC/call) Shopping search API (alias of product-search). Find products and buy links for a query with title, buy link, retailer, snippet, and detected price. Backed by Decodo Google search scoped to buy intent. |
+
+## How it works
+
+1. Agent calls a tool (e.g. `find-products`).
+2. MCP server POSTs to `https://x402.agentutility.ai/find-products`.
+3. The endpoint responds **HTTP 402** with payment instructions.
+4. The MCP server signs an EIP-3009 USDC transfer authorization with `X402_PRIVATE_KEY` and retries.
+5. CDP facilitator settles on Base.
+6. The endpoint returns the actual response.
+
+The agent never sees the payment flow — it just gets the result.
+
+## Links
+
+- Cluster overview: https://agentutility.ai/retail/
+- All MCP packages: https://mcp.agentutility.ai/
+- Source: https://github.com/rooz21/x402/tree/main/packages/mcp-retail
+
+---
+
+**Version:** 0.1.0 · **License:** MIT

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @agentutility/mcp-<cluster> — stdio MCP server exposing the cluster's
+ * x402-paid endpoints as MCP tools. Forwards every CallToolRequest to
+ * x402.agentutility.ai, where @x402/fetch handles 402 → payment → retry
+ * using the agent's own wallet (X402_PRIVATE_KEY env var).
+ *
+ * Boilerplate is single-sourced at packages/_template/src/index.ts and
+ * copied verbatim into each packages/mcp-<cluster>/src/index.ts by
+ * scripts/generate-mcp-clusters.mjs. The codegen also writes a matching
+ * tools.generated.ts so this file imports CLUSTER_SLUG + VERSION + TOOLS
+ * rather than hard-coding.
+ *
+ * Required env: X402_PRIVATE_KEY (hex EVM key, USDC on Base).
+ * Optional env: X402_BASE_URL (default https://x402.agentutility.ai)
+ *               X402_RPC_URL  (default https://mainnet.base.org)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { TOOLS, CLUSTER_SLUG, VERSION } from "./tools.generated.js";
+const BASE_URL = (process.env.X402_BASE_URL || "https://x402.agentutility.ai").replace(/\/$/, "");
+const RPC_URL = process.env.X402_RPC_URL || "https://mainnet.base.org";
+const PK = process.env.X402_PRIVATE_KEY;
+if (!PK) {
+    console.error(`[@agentutility/mcp-${CLUSTER_SLUG}] FATAL: X402_PRIVATE_KEY env var is required.`);
+    console.error("Set it to a hex-encoded EVM private key with USDC balance on Base (chain 8453).");
+    console.error("USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+    process.exit(1);
+}
+const account = privateKeyToAccount((PK.startsWith("0x") ? PK : `0x${PK}`));
+const publicClient = createPublicClient({
+    chain: base,
+    transport: http(RPC_URL),
+});
+const signer = toClientEvmSigner(account, publicClient);
+const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+async function trackedFetch(url, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("X-Agent-Channel", `mcp-stdio-${CLUSTER_SLUG}`);
+    headers.set("X-Agent-Id", "47167");
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", `agentutility-mcp/${CLUSTER_SLUG}/${VERSION}`);
+    }
+    return paidFetch(url, { ...init, headers });
+}
+const server = new Server({ name: `agentutility-${CLUSTER_SLUG}`, version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.input_schema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    try {
+        const res = await trackedFetch(`${BASE_URL}/${tool.http_name}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req.params.arguments ?? {}),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: `HTTP ${res.status}: ${body}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: body }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `tool call failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+await server.connect(new StdioServerTransport());

package/dist/tools.generated.js

@@ -0,0 +1,151 @@
+/** Auto-generated by scripts/generate-mcp-clusters.mjs. Do not edit by hand. */
+export const CLUSTER_SLUG = "retail";
+export const VERSION = "0.1.0";
+export const TOOLS = [
+    {
+        "name": "find-products",
+        "http_name": "find-products",
+        "description": "(0.02 USDC/call) Find products API (alias of product-search). Returns ranked product results with buy links, retailer, snippet, and detected price for a shopping query. Backed by Decodo Google search scoped to buy intent.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Product to find. Max 300 chars."
+                },
+                "num_results": {
+                    "type": "number",
+                    "description": "Results to return, 1-20. Default 10."
+                },
+                "retailer": {
+                    "type": "string",
+                    "description": "Optional retailer/domain to scope to."
+                }
+            },
+            "required": [
+                "query"
+            ]
+        }
+    },
+    {
+        "name": "product-describe",
+        "http_name": "product-describe",
+        "description": "(0.01 USDC/call) Product description generator / e-commerce copywriter / product listing copy / selling points API. Given a product name (and optional category, audience, attributes), returns a conversion-focused description, bullet selling points, key features, a positioning angle, and suggested listing titles. LLM-backed (Morpheus primary, Venice fallback). Generates copy from supplied facts; does not invent specs or claims.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "product": {
+                    "type": "string",
+                    "description": "Product name or short description. Required, max 2000 chars."
+                },
+                "category": {
+                    "type": "string",
+                    "description": "Optional product category, e.g. 'running shoes'."
+                },
+                "audience": {
+                    "type": "string",
+                    "description": "Optional target audience."
+                },
+                "attributes": {
+                    "type": "array",
+                    "description": "Optional known attributes/features (strings)."
+                },
+                "tone": {
+                    "type": "string",
+                    "description": "Optional copy tone, e.g. 'premium', 'playful'."
+                }
+            },
+            "required": [
+                "product"
+            ]
+        }
+    },
+    {
+        "name": "product-description",
+        "http_name": "product-description",
+        "description": "(0.01 USDC/call) Product description API (alias of product-describe). Turns a product name + attributes into a marketing-ready description, selling points, key features, and listing titles. LLM-backed; copy from supplied facts only.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "product": {
+                    "type": "string",
+                    "description": "Product name or short description. Required, max 2000 chars."
+                },
+                "category": {
+                    "type": "string",
+                    "description": "Optional product category."
+                },
+                "audience": {
+                    "type": "string",
+                    "description": "Optional target audience."
+                },
+                "attributes": {
+                    "type": "array",
+                    "description": "Optional known attributes/features (strings)."
+                },
+                "tone": {
+                    "type": "string",
+                    "description": "Optional copy tone."
+                }
+            },
+            "required": [
+                "product"
+            ]
+        }
+    },
+    {
+        "name": "product-search",
+        "http_name": "product-search",
+        "description": "(0.02 USDC/call) Product search / shopping search API / find products + buy links for agents. Given a product query (and optional retailer), returns ranked shopping results with product title, buy link, retailer domain, snippet, and any detected price. Backed by Decodo Google search scoped to buy intent. For general web search use search/web-search.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Product to find, e.g. 'noise cancelling headphones under 200'. Max 300 chars."
+                },
+                "num_results": {
+                    "type": "number",
+                    "description": "Results to return, 1-20. Default 10."
+                },
+                "retailer": {
+                    "type": "string",
+                    "description": "Optional retailer/domain to scope to, e.g. 'amazon.com'."
+                }
+            },
+            "required": [
+                "query"
+            ]
+        }
+    },
+    {
+        "name": "shop-search",
+        "http_name": "shop-search",
+        "description": "(0.02 USDC/call) Shopping search API (alias of product-search). Find products and buy links for a query with title, buy link, retailer, snippet, and detected price. Backed by Decodo Google search scoped to buy intent.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Product to find. Max 300 chars."
+                },
+                "num_results": {
+                    "type": "number",
+                    "description": "Results to return, 1-20. Default 10."
+                },
+                "retailer": {
+                    "type": "string",
+                    "description": "Optional retailer/domain to scope to."
+                }
+            },
+            "required": [
+                "query"
+            ]
+        }
+    }
+];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agentutility/mcp-retail",
+  "version": "0.1.0",
+  "description": "MCP server for the @agentutility retail cluster — pay-per-call x402 tools, no API keys, USDC on Base.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentutility-mcp-retail": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rooz21/x402",
+    "directory": "packages/mcp-retail"
+  },
+  "homepage": "https://mcp.agentutility.ai/retail/",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "agentutility",
+    "agent-tools",
+    "retail"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@x402/fetch": "^2.12.0",
+    "@x402/evm": "^2.12.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}