coinopai-mcp 2.0.2 → 2.1.0

package/README.md

@@ -8,6 +8,7 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![payments](https://img.shields.io/badge/payments-x402%20USDC-0052FF)](https://x402.org)
 [![network](https://img.shields.io/badge/network-Base-0052FF)](https://base.org)
+[![mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/forgemeshlabs/coinopai-mcp)
 
 **Auditable market context with calibrated forecast ranges and outcome verification.**
 
@@ -306,6 +307,27 @@ Route to an available symbol or wait 15 minutes for the next cycle.
 
 ---
 
+## Sponsored cards (Lulu Ads)
+
+Free-tier tool responses may carry a single disclosed sponsored card from [Lulu Ads](https://getlulu.dev). It is a plain, labelled data field on the JSON result — never text the model could read as an instruction:
+
+```json
+{
+  "results": [...],
+  "sponsored": { "label": "Sponsored", "text": "...", "url": "https://..." }
+}
+```
+
+- **Eligible tools:** `search_agent_automations`, `list_automation_categories`, `get_agent_automation`, `check_trade_preflight` — and only when the response did **not** settle an x402 payment (no `_payment` receipt). A paid response never carries a card.
+- **Current state:** one tool is free — `list_tools` (a plain fetch of `/menu`, no wallet, no payment) — so that is the only tool where a card can render today. The other four allowlisted tools are still paid, so no card attaches to them; the switch is server-side: when the operator makes one of those endpoints free (a plain `200` with no `402`), cards start appearing there with no client change.
+- **Paid tools never carry it:** `get_crypto_signals`, `get_crypto_risk`, `get_crypto_signal_history`, `get_crypto_decision`, `audit_trade_decision`, `get_crypto_forecast`, `review_signal_anomaly` never touch the ads SDK.
+- **Strip it:** `delete result.sponsored`.
+- **Where the card comes from:** ForgeMesh's own publisher card is attached server-side to `GET https://x402.coinopai.com/menu`, so `list_tools` simply passes it through — this package ships **no** ad credentials and makes **no** calls to the ads network on its own.
+- **Operator env vars (forks only):** `LULU_ADS_PUBLISHER_ID` and `LULU_ADS_API_KEY` let a fork attach its own publisher card client-side (both required; if either is missing the package makes zero calls to the ads network and responses are unchanged). `LULU_ADS_ENABLED=false` is a kill switch.
+- **Fail-open:** any SDK error or timeout (hard budget 2s) returns the original response unchanged. The only external host contacted is `ads.getlulu.dev`.
+
+---
+
 ## Affiliate Attribution (via Pyrimid)
 
 High-value tools accept an optional `affiliate_id` parameter. When provided, payment routes through the [Pyrimid](https://pyrimid.xyz) affiliate network — the affiliate earns a commission split from within the listed price. **No extra cost to the caller.**

package/ads.js

@@ -0,0 +1,127 @@
+"use strict";
+
+// Lulu Ads sponsored cards — disclosed data field, free-tier tools only.
+//
+// Contract:
+//   - Card attaches ONLY to tools in FREE_TIER_TOOLS, and only when the
+//     response carries no x402 `_payment` settlement receipt. A response
+//     that settled a payment never carries a card, even for an allowlisted
+//     tool. Every other tool (Kronos decision loop, anomaly review) is
+//     excluded by name and never touches the SDK.
+//   - The card is a plain data field `sponsored: {label, text, url}` on the
+//     tool's JSON result — never injected into prose the model could read
+//     as an instruction. Strip it with `delete result.sponsored`.
+//   - This package ships NO ad credentials. ForgeMesh's own card is attached
+//     server-side to GET /menu and passes through `list_tools` untouched
+//     (see "never clobber an upstream field" below). The env path here
+//     (LULU_ADS_PUBLISHER_ID, LULU_ADS_API_KEY) exists for forks that want
+//     their own publisher card client-side. Either missing → zero network
+//     calls, response unchanged. LULU_ADS_ENABLED=false is a kill switch.
+//   - Fail-open with a hard time budget: SDK error, timeout, or import
+//     failure → original response unchanged. Never throws.
+//
+// The SDK is deliberately NOT wired via `enableLuluAds`/`withLuluAds`
+// from "lulu-ads/mcp": those wrap every registered tool, which would put
+// cards on paid tools.
+
+// Tools whose responses may carry a card. Everything else is paid-only.
+//
+// NOTE: `list_tools` is the one genuinely free tool (plain fetch of /menu,
+// no callPaid, no `_payment`), so it is the only place a card renders today.
+// The other four still go through callPaid and settle x402, so `_payment`
+// is set and no card attaches; the switch for them is server-side — make the
+// endpoint free (200 without a 402) and cards appear with no change here.
+const FREE_TIER_TOOLS = new Set([
+  "list_tools",
+  "search_agent_automations",
+  "list_automation_categories",
+  "get_agent_automation",
+  "check_trade_preflight",
+]);
+
+// Ad category forwarded to ads-server per tool (allowlisted context key).
+const TOOL_CATEGORY = {
+  list_tools: "agents.automation",
+  search_agent_automations: "agents.automation",
+  list_automation_categories: "agents.automation",
+  get_agent_automation: "agents.automation",
+  check_trade_preflight: "crypto.tools",
+};
+
+// Hard ceiling on the whole slot call (SDK's own default is 1500ms warm /
+// 3000ms cold). We pass SDK_TIMEOUT_MS explicitly so the SDK never picks the
+// 3000ms cold budget, and race it against HARD_BUDGET_MS as a belt-and-braces
+// guard in case the SDK's AbortSignal misbehaves.
+const SDK_TIMEOUT_MS = 1500;
+const HARD_BUDGET_MS = 2000;
+
+let clientPromise = null; // lazily-built LuluAds instance (or null when inert)
+
+// Test seam: `setAdsClientForTests(fake)` swaps the SDK client; `null` resets.
+let injectedClient;
+function setAdsClientForTests(client) {
+  injectedClient = client;
+  clientPromise = null;
+}
+
+function adsEnabled(env = process.env) {
+  if (String(env.LULU_ADS_ENABLED || "").toLowerCase() === "false") return false;
+  return Boolean(env.LULU_ADS_PUBLISHER_ID && env.LULU_ADS_API_KEY);
+}
+
+// lulu-ads is ESM-only ("type": "module", `import` export only), so a
+// CommonJS caller has to dynamic-import it. Done once, lazily, and only
+// after the env guard passes — so no creds means the module is never even
+// loaded, let alone warmed up (warmUp() would otherwise POST /telemetry/init
+// with an empty key).
+function getClient() {
+  if (injectedClient !== undefined) return Promise.resolve(injectedClient);
+  if (!clientPromise) {
+    clientPromise = import("lulu-ads")
+      .then(({ LuluAds }) => {
+        const client = new LuluAds({
+          publisherId: process.env.LULU_ADS_PUBLISHER_ID,
+          apiKey: process.env.LULU_ADS_API_KEY,
+        });
+        void client.warmUp(); // fire-and-forget, never throws
+        return client;
+      })
+      .catch(() => null);
+  }
+  return clientPromise;
+}
+
+function isFreeTierResponse(toolName, data) {
+  if (!FREE_TIER_TOOLS.has(toolName)) return false;
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  if (data._payment) return false; // x402 settled → paid response, no card
+  if ("sponsored" in data) return false; // never clobber an upstream field
+  return true;
+}
+
+// Returns `data` with a `sponsored` field appended when a card is available,
+// otherwise the exact same object. Never throws, never exceeds HARD_BUDGET_MS.
+async function attachSponsored(toolName, data) {
+  try {
+    if (!adsEnabled()) return data;
+    if (!isFreeTierResponse(toolName, data)) return data;
+    const client = await getClient();
+    if (!client) return data;
+
+    const slot = client.sponsoredSlot({
+      context: { tool: toolName, category: TOOL_CATEGORY[toolName] },
+      timeoutMs: SDK_TIMEOUT_MS,
+    });
+    let timer;
+    const budget = new Promise((resolve) => { timer = setTimeout(() => resolve(null), HARD_BUDGET_MS); });
+    const sponsored = await Promise.race([slot, budget]).catch(() => null);
+    clearTimeout(timer);
+
+    if (!sponsored || !sponsored.text || !sponsored.url) return data;
+    return { ...data, sponsored: { label: "Sponsored", text: String(sponsored.text), url: String(sponsored.url) } };
+  } catch (_) {
+    return data;
+  }
+}
+
+module.exports = { attachSponsored, adsEnabled, isFreeTierResponse, FREE_TIER_TOOLS, TOOL_CATEGORY, setAdsClientForTests };

package/index.js

@@ -10,6 +10,7 @@ const { toClientEvmSigner } = require("@x402/evm");
 const { privateKeyToAccount } = require("viem/accounts");
 const { createPublicClient, createWalletClient, http, parseAbi } = require("viem");
 const { base } = require("viem/chains");
+const { attachSponsored, FREE_TIER_TOOLS } = require("./ads.js");
 
 const BASE_URL = "https://x402.coinopai.com";
 
@@ -201,6 +202,17 @@ const TOOLS = [
       }
     }
   },
+  {
+    name: "list_tools",
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+    description: "Free. Lists every CoinOpAI tool with its price, so an agent can pick before paying.",
+    inputSchema: { type: "object", properties: {} }
+  },
   {
     name: "review_signal_anomaly",
     annotations: {
@@ -358,7 +370,7 @@ async function main() {
   }
 
   const server = new Server(
-    { name: "coinopai-mcp", version: "1.2.10" },
+    { name: "coinopai-mcp", version: "2.1.0" },
     { capabilities: { tools: {} } }
   );
 
@@ -369,9 +381,16 @@ async function main() {
     try {
       // Affiliate ID: tool arg takes precedence, then env fallback, then none
       const affiliateId = args.affiliate_id || process.env.PYRIMID_AFFILIATE_ID || null;
-      const paymentContext = getPaymentContext();
+      // list_tools is free: plain fetch, no wallet, never touches callPaid
+      const paymentContext = name === "list_tools" ? null : getPaymentContext();
       let data;
       switch (name) {
+        case "list_tools": {
+          const r = await fetch(`${BASE_URL}/menu`);
+          if (!r.ok) throw new Error(`/menu returned ${r.status}`);
+          data = await r.json();
+          break;
+        }
         // Low-value utility endpoints — no affiliate routing
         case "search_agent_automations":
           data = await callPaid(paymentContext, `/api/search?q=${encodeURIComponent(args.query || "")}&limit=${args.limit || 20}`, null);
@@ -417,6 +436,9 @@ async function main() {
         default:
           throw new Error("Unknown tool: " + name);
       }
+      // Sponsored card (Lulu Ads) — free-tier tools only, skipped when the
+      // response settled an x402 payment. Paid tools never reach this call.
+      if (FREE_TIER_TOOLS.has(name)) data = await attachSponsored(name, data);
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     } catch (e) {
       return { content: [{ type: "text", text: "Error: " + e.message }], isError: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coinopai-mcp",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "mcpName": "io.github.forgemeshlabs/coinopai-mcp",
   "description": "Auditable market intelligence MCP with x402 payments, calibrated forecast ranges, anomaly review, risk context, and outcome audits",
   "main": "index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "index.js",
+    "ads.js",
     "README.md",
     "server.json"
   ],
@@ -50,6 +51,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@x402/core": "2.11.0",
     "@x402/evm": "2.11.0",
+    "lulu-ads": "^0.9.19",
     "viem": "^2.0.0"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/forgemeshlabs/coinopai-mcp",
     "source": "github"
   },
-  "version": "2.0.2",
+  "version": "2.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "coinopai-mcp",
-      "version": "2.0.2",
+      "version": "2.1.0",
       "transport": {
         "type": "stdio"
       },