[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_119":120},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":49,"_69":70,"_71":72,"_73":74,"_75":76,"_77":78,"_79":-5,"_80":-5,"_81":-5,"_82":49,"_83":-5,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95,"_96":97},"apiUrl","https://odel.app/api","creator","lulu-the-narwhal","moduleId","lulu-ads","@lulu-the-narwhal/lulu-ads","displayName","Lulu Ads — Publisher Concierge","tagline","Self-serve publisher onboarding for Lulu Ads. 70% CPA, disclosed sponsored field.","iconKey","https://avatars.githubusercontent.com/u/253140923?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://ads.getlulu.dev/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1784521468000,"updatedAt",1788775773000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Lulu-The-Narwhal%2Flulu-ads","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",2,"upstreamUpdatedAt",1788725375000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt","githubRepoUrl","https://github.com/Lulu-The-Narwhal/lulu-ads","githubRepoFullName","Lulu-The-Narwhal/lulu-ads","releaseId","ext-lulu-the-narwhal-lulu-ads","version","0.2.0","descriptionMarkdown","

\n\n# lulu-ads\n\n### *The monetization layer for the agent economy.*\n\n**Monetize your MCP server or agent tool with one labeled sponsored line.**\n\n[![PyPI](https://img.shields.io/pypi/v/lulu-ads.svg)](https://pypi.org/project/lulu-ads/)\n[![npm](https://img.shields.io/npm/v/lulu-ads.svg)](https://www.npmjs.com/package/lulu-ads)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Backend](https://img.shields.io/badge/backend-live-brightgreen)](https://ads.getlulu.dev/health)\n[![Publisher beta](https://img.shields.io/badge/publisher_beta-open-E07A00)](https://getlulu.dev/publishers)\n[![Rev share](https://img.shields.io/badge/rev_share-70%25-blueviolet)](docs/contract.md)\n[![Lulu MCPs](https://getlulu.dev/api/mcps/badge/lulu-ads)](https://getlulu.dev/mcps/lulu-ads)\n\n[Quickstart](#quickstart) · [Integrations](#framework-integrations) · [Supported hosts](#supported-hosts) · [Supported surfaces](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/supported-surfaces.md) · [stdio servers](#stdio-servers) · [Guarantees](#guarantees-enforced-in-code-not-just-promised) · [API contract](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/contract.md) · [Hosted docs](https://getlulu.dev/docs) · [Blog](https://getlulu.dev/blog) · [Become a publisher](https://getlulu.dev/publishers)\n\n $\"Lulu,$ \n\n`70% to publishers · CPA only · 800ms fail-open · 0 prompt injections, by design`\n\n[![Sponsored](https://getlulu.dev/api/mcps/sponsor/lulu-ads)](https://getlulu.dev/api/mcps/sponsor-click/lulu-ads)\n
_{↑ live rendered sponsor card — real rotating ad demand, refreshes every ~60s. Any claimed listing can embed this in its own README.}\n\n

\n\nLulu Ads attaches a disclosed, labeled data field to your tool's own result.\nThe host model — Claude, Cursor, any agent — decides on its own judgment\nwhether it's relevant enough to surface. We never instruct it to.\n\n\n\n\n\n\n\n\n\n\n

What the SDK ships (a data field)	What the host renders (its choice)
\n\n```json\n{\n \"sponsored\": {\n \"label\": \"Sponsored\",\n \"text\": \"Direct flights TLV–BKK from $412\",\n \"url\": \"https://ads.getlulu.dev/c/9f2a1c\"\n }\n}\n```\n\n	\n\n> Sponsored — Direct flights TLV–BKK from $412\n> [ads.getlulu.dev/c/9f2a1c](https://ads.getlulu.dev/c/9f2a1c)\n\n

\n\nZero-friction start — add the MCP server and let your agent do the rest:\n\n```bash\nclaude mcp add --transport http lulu-ads https://ads.getlulu.dev/mcp\n```\n\n> monetize my server\n\nIt'll fetch the right integration guide for your stack, register a publisher\n(with your consent), wire up the one-liner, and verify a slot went live.\n\n**If it renders and gets clicked, you earn 70% on CPA. If it doesn't — nobody\npays, nothing breaks.**\n\n**No prompt injection — we ship a data field; the host decides.**\n\n## Quickstart\n\n**Python**\n\n```bash\npip install lulu-ads\n# or: uv add lulu-ads\n# or: poetry add lulu-ads\n```\n\n```python\nfrom lulu_ads import LuluAds\nads = LuluAds(publisher_id=\"pub_123\", api_key=\"lk_...\")\n\nresult = search_flights(\"TLV\", \"BKK\", dates)\nresult[\"sponsored\"] = await ads.sponsored_slot(\n context={\"tool\": \"search_flights\", \"category\": \"travel.flights\"},\n)\nreturn result\n```\n\nFastMCP servers get it in one call — credentials come from the environment,\nand every tool (present and future) gets both the plain `sponsored` data\nfield AND, in hosts that support it (e.g. Claude.ai), the rendered\nSponsored-card widget, automatically:\n\n```bash\nexport LULU_ADS_PUBLISHER_ID=pub_123\nexport LULU_ADS_API_KEY=lk_...\n```\n\n```python\nfrom lulu_ads.enable import enable_lulu_ads\n\nenable_lulu_ads(mcp, endpoint_url=\"https://my-server.example.com/mcp\")\n```\n\nJust want the data field, no widget? The plain middleware still works on\nits own:\n\n```python\nmcp.add_middleware(LuluAdsMiddleware())\n```\n\n**TypeScript**\n\n```bash\nnpm install lulu-ads\n# or: pnpm add lulu-ads\n# or: yarn add lulu-ads\n# or: bun add lulu-ads\n```\n\n```ts\nimport { LuluAds } from \"lulu-ads\";\nconst ads = new LuluAds({ publisherId: \"pub_123\", apiKey: \"lk_...\" });\nresult.sponsored = await ads.sponsoredSlot({ context: { tool: \"search_flights\" } });\n```\n\nMCP servers built on the official TS SDK get the same one-call treatment —\ndata field AND widget on every tool, automatically:\n\n```ts\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { enableLuluAds } from \"lulu-ads/mcp\";\n\nconst server = new McpServer({ name: \"my-server\", version: \"1.0.0\" });\nawait enableLuluAds(server, { endpointUrl: \"https://my-server.example.com/mcp\" });\n```\n\nNo publisher ID yet? See [`docs/quickstart.md`](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/quickstart.md) — three\nways to get one, none of them gated on the others.\n\n**Tiered pricing (ads on a free tier, ad-free on paid)?** Pass `enabled` —\nyour own subscription check decides the value, no separate deployment or\nscattered conditionals needed:\n\n```python\nresult[\"sponsored\"] = await ads.sponsored_slot(\n context={\"tool\": \"search_flights\"},\n enabled=user.tier != \"paid\", # False resolves instantly, no network call\n)\n```\n\n```ts\nresult.sponsored = await ads.sponsoredSlot({\n context: { tool: \"search_flights\" },\n enabled: user.tier !== \"paid\",\n});\n```\n\n## Framework integrations\n\n| Stack | One-liner | Docs |\n|---|---|---|\n| FastMCP (Python), data + widget | `enable_lulu_ads(mcp, endpoint_url=...)` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#fastmcp-python) |\n| FastMCP (Python), data only | `mcp.add_middleware(LuluAdsMiddleware())` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#fastmcp-python) |\n| MCP TS SDK, data + widget | `await enableLuluAds(server, { endpointUrl })` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#mcp-servers-typescript) |\n| LangChain / LangGraph (Python) | `middleware=[LuluAdsAgentMiddleware()]` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#langchain--langgraph-python) |\n| CrewAI (Python) | `lulu_crewai.install()` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#crewai-python) |\n| MCP TS SDK, data only | `withLuluAds(server)` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#mcp-servers-typescript) |\n| Skybridge (TypeScript) | `withLuluAdsSkybridge(server)` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#skybridge-typescript) |\n| Runtime owners (chat bots, WhatsApp/Telegram agents) | `model_output + format_suffix(sponsored)` | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#runtime-owners-response-suffix) |\n| Any other runtime / language | `sponsored_slot(context)` over the raw contract | [→](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md#any-agent-runtime) |\n\n## Result widgets — templates for your OWN tool output (0.8.5)\n\n**One widget, every host.** The frame speaks three bridges — stable MCP\nApps (`ui/initialize`, 2026-01-26), the draft-era fallback, and ChatGPT's\n`window.openai` — and the SDK registers both template keys\n(`_meta.ui.resourceUri` + `openai/outputTemplate`) and both CSP dialects\nautomatically. Verified rendering live on claude.ai and ChatGPT, including\nthe rendered-impression beacon (impressions count what a human actually\nsaw, never mere API output). After upgrading, refresh your connector in\nChatGPT's plugin settings — it caches tool metadata.\n\n**The SPONSORED strip's own format is separately configurable** via\n`sponsor_template=` (independent of `template=`, this widget's own body\nlayout):\n\n```python\nregister_result_widget(\n mcp, \"search_flights\",\n template=\"table-card\",\n mapping={\"rows\": \"flights\", \"columns\": [...]},\n endpoint_url=\"https://my-server.example.com/mcp\",\n sponsor_template=\"flip-card\", # or \"carousel\", \"scratch-reveal\" -- \"card\" is the default\n)\n```\n\n## Supported hosts\n\nThe plain `sponsored` JSON field is the always-on baseline: it ships on\nevery tool result, on every MCP host, because it's nothing more than an\nextra key on a dict — no host-specific support is required for it to work,\nand the model decides on its own whether to surface it. The **rendered**\nMCP Apps widget above that is additive, and only paints where a host has\nactually implemented the `ui/initialize` handshake. This table says exactly\nwhich is which per host, based on our own production verification where we\nhave it and a fresh survey (2026-08-25) everywhere else — a host only gets\na \"Live\" widget status here when we've confirmed it ourselves or the\nvendor has published concrete, checkable implementation detail, never on a\ngeneric \"should work\" assumption.\n\n

\n $\"Claude\"$ \n \n $\"ChatGPT\"$ \n \n $\"CopilotKit\"$ \n \n $\"VS$ \n \n $\"Cursor\"$ \n \n $\"Goose\"$ \n \n $\"Grok$ \n \n $\"Windsurf\"$ \n \n $\"Cline\"$ \n \n $\"Zed\"$ \n

\n\n_{Hosts we've looked at — logos are not a support claim on their own;\nread the Status column below for what each one actually does. (Continue.dev\nis in the table but not the strip above: it's a discontinued product, kept\nhere only for completeness.)}\n\n| Host | MCP tool-calling | Rendered widget | Status |\n|---|---|---|---|\n| Claude (claude.ai) | Yes | Yes | Live, verified in production — real rendered-impression beacons observed on live traffic. |\n| ChatGPT | Yes | Yes | Live, verified in production. |\n| CopilotKit (`@ag-ui/mcp-apps-middleware`) | Yes | In progress | Fix in review, [PR #8](https://github.com/Lulu-The-Narwhal/lulu-ads/pull/8), unverified end-to-end — a tool-discovery bug was found and fixed, but the fix has not been tested against a full chat UI (no LLM available in that pass) and is not yet released to npm/PyPI. Do not treat CopilotKit as supported until that PR lands and is verified live. The plain `sponsored` field is unaffected by this bug and already flows today. |\n| VS Code (native MCP + GitHub Copilot Chat agent mode) | Yes | Reported live | Microsoft's own 2026-01-26 blog post and current docs describe VS Code as \"the first major AI code editor with full MCP Apps support\" and document concrete, checkable implementation detail (sandboxed iframes, CSP domain config, the `ui/initialize` handshake, the App SDK) — credible, but this is a vendor claim we have not independently reproduced ourselves. Plain MCP tool-calling (Copilot Chat agent mode) has been GA since v1.102. |\n| Cursor | Yes | Reported, unverified | Named as an MCP Apps implementer on the upstream [modelcontextprotocol.io Extension Support Matrix](https://modelcontextprotocol.io/extensions/client-matrix) — a third-party listing, not Cursor's own docs, so weaker evidence than VS Code/Goose's vendor-published detail above. We actually tried to verify this ourselves live (2026-08-25) and got blocked before reaching the test: Cursor's free-tier Agent usage cap (2 prompts) hit before a real tool call went through. Real attempt, real blocker, still unconfirmed — not a claim we're dodging. |\n| Goose (Block / AAIF) | Yes | Live (experimental) | Goose's own docs confirm the `ui/initialize` handshake and sandboxed-iframe rendering (Goose Desktop 1.19.1+), but explicitly flag it as \"experimental and based on a draft specification; the implementation is minimal and may change.\" Treat as live-but-unstable, not a guaranteed render target. |\n| Grok (xAI) — grok.com connectors, Grok Build CLI, xAI API Remote MCP Tools | Yes | No evidence found | MCP-capable across all three xAI surfaces (plain tool discovery + calling), but no official doc, changelog, or third-party host-support matrix credits Grok with the MCP Apps UI extension as of this survey. The sponsored data field still flows and still renders purely on the model's own judgment via the always-on JSON fallback — the rich widget just has nothing to render into. |\n| Windsurf (Codeium) | Yes | No evidence found | Windsurf's own docs state it supports \"an MCP server's tools, resources, and prompts\" only; every third-party MCP Apps host-support list we found omits it. Sponsored data field still works via the always-on JSON fallback. |\n| Cline (VS Code extension) | Yes | No evidence found | Mature MCP client (tools, resources, prompts, a built-in MCP marketplace); no `ui/initialize`, `ui://`, or iframe-rendering code found anywhere in the repo. Sponsored data field still works via the always-on JSON fallback. |\n| Zed editor | Yes | No evidence found | Zed's own docs state plainly it \"currently supports MCP's Tools and Prompts features\" — no Resources-based UI rendering. Sponsored data field still works via the always-on JSON fallback. |\n| Continue.dev | Yes (historically) | No evidence found | Discontinued: acquired by Cursor in June 2026, and the `continuedev/continue` repo is now read-only with no further development. It supported plain MCP tools/resources/prompts while active, with no evidence it ever rendered MCP Apps widgets. Not a viable integration target going forward — listed here only for completeness. |\n\n### Why some hosts need zero extra code and others don't\n\nDifferent hosts converged on different conventions for how a tool\nadvertises \"I have a renderable UI\" — and where a host's convention differs\nfrom the one we shipped first, discovery silently fails before rendering\never gets a chance to run (that was the CopilotKit gap [PR #8](https://github.com/Lulu-The-Narwhal/lulu-ads/pull/8)\nfixed, 2026-08-25). We track each convention we've confirmed and register\nagainst all of them on every widget-capable tool — additive only, never a\nrewrite, so a host that doesn't recognize one signal just ignores it. That's\nthe practical reason Claude and VS Code render with zero extra code (they\nshare a convention) while CopilotKit needed a targeted fix, and it's why\n\"no evidence found\" in the table below means exactly that — evidence not\nfound yet, not evidence of absence.\n\nAnything else not listed above (LangGraph Studio, custom in-house agent\nharnesses, and every host we simply haven't looked at yet): unknown / not\nyet investigated — the plain `sponsored` field is designed to fail open and\ndegrade gracefully on any of them regardless, per the [Guarantees](#guarantees-enforced-in-code-not-just-promised)\nbelow. If you've verified rendering on a host not in this table, open an\nissue or PR — this list is meant to stay honest, not exhaustive.\n\nThis table is specifically about **widget rendering in chat hosts**.\nFor the fuller picture — agentic SDKs/frameworks (most reach the data\nfield via MCP passthrough, no dedicated adapter needed), response-suffix\nruntimes (WhatsApp/Telegram/Slack/SMS bots, background agents), AI app\nbuilders (not yet evaluated), and MCP hosting/registries (irrelevant to\nthis SDK by design) — see\n[**Supported surfaces**](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/supported-surfaces.md).\n\nDon't design UI. Pick one of four predefined, host-native-quality result\nwidgets and map your tool's `structuredContent` fields into it — the frame,\ndesign tokens, and the disclosed SPONSORED strip are fixed by the SDK. The\nstrip renders only when a live `sponsored` payload exists, always at the\nbottom, always labeled, with the advertiser's logo (letter-tile fallback\nwhen none loads). Your body can't remove or restyle it.\n\nTemplates: `stat-card` (big value + chips + optional condition-keyed\natmospheric background), `table-card` (headed rows, mono numerics, best-row\nhighlight), `notice-card` (verdict glyph + detail rows), `carousel-card`\n(3–8 swipeable option cards).\n\n```python\nfrom lulu_ads.widgets import register_result_widget\n\n# after your @mcp.tool definitions:\nregister_result_widget(\n mcp, \"get_weather\",\n template=\"stat-card\",\n mapping={\n \"eyebrow\": \"location.name\",\n \"value\": {\"path\": \"temperature_c\", \"suffix\": \"°\"},\n \"condition\": \"conditions\",\n \"chips\": [{\"path\": \"humidity_pct\", \"prefix\": \"💧 \", \"suffix\": \"%\"}],\n \"atmosphere\": \"weather_code\", # WMO code or words -> sky gradient\n },\n endpoint_url=\"https://my-server.example.com/mcp\",\n)\n```\n\nTypeScript: `import { registerResultWidget } from \"lulu-ads/widgets\"` —\nsame templates and mapping shape; spread the returned `_meta` into\n`server.registerTool(...)`. Mapping entries are dot-paths or\n`{path, prefix, suffix}`; a `body_html=` escape hatch accepts custom\nmarkup composed from the `.lw-*` primitives for the cases the templates\ndon't cover. Calling it for a tool deliberately replaces the generic\nsponsored card from `enable_lulu_ads` on that tool — the sponsored data\nstill flows and renders in the widget's own strip.\n\n## Widget rendering (MCP Apps UI)\n\nThe plain `sponsored` field always ships and always works — some hosts\nrender it as a card purely on the model's own judgment, no instruction\nanywhere. For hosts that support the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)\nextension (`io.modelcontextprotocol/ui`), `enable_lulu_ads` / `enableLuluAds`\n(see Quickstart above) already register an actual rendered widget and\nattach it to every tool automatically — you don't need anything below this\nline for that. It exists as a distinct step at all because\n`register_sponsored_widget()` requires your server's exact public endpoint\nURL, which `LuluAdsMiddleware`/`withLuluAds` alone have no way to know.\n\n**Prefer per-tool control** (a different widget on different tools, or\nonly some tools get one)? Use the lower-level building block directly\ninstead of `enable_lulu_ads`:\n\n```python\nfrom fastmcp import FastMCP\nfrom lulu_ads.widget import register_sponsored_widget\n\nmcp = FastMCP(\"my-server\")\nsponsored_app = register_sponsored_widget(\n mcp,\n endpoint_url=\"https://my-server.example.com/mcp\", # your public MCP connector URL\n text=\"Save 15% at checkout\",\n url=\"https://example.com/deal\",\n logo=\"https://example.com/logo.png\", # optional, see \"Logos\" below\n)\n\n@mcp.tool(app=sponsored_app)\ndef search(...): ...\n```\n\nSame helper, official TS SDK, for MCP servers built in Node instead of Python\n(registration is `async` — it may fetch a logo before returning):\n\n```typescript\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { registerSponsoredWidget } from \"lulu-ads/widget\";\n\nconst server = new McpServer({ name: \"my-server\", version: \"1.0.0\" });\nconst appMeta = await registerSponsoredWidget(server, {\n endpointUrl: \"https://my-server.example.com/mcp\", // your public MCP connector URL\n text: \"Save 15% at checkout\",\n url: \"https://example.com/deal\",\n logo: \"https://example.com/logo.png\", // optional, see \"Logos\" below\n});\n\nserver.registerTool(\"search\", { ...appMeta }, handler);\n```\n\n**Card formats.** `template=` picks the widget's visual layout — a\nregistration-time choice, same shape as `register_result_widget`'s own\n`template=` (Result widgets, above). Defaults to `\"card\"` (the layout\nshown above); pass a different name for a different format:\n\n```python\nsponsored_app = register_sponsored_widget(\n mcp,\n endpoint_url=\"https://my-server.example.com/mcp\",\n text=\"Save 15% at checkout\",\n url=\"https://example.com/deal\",\n template=\"banner\", # full-width horizontal strip -- see Templates below\n)\n```\n\n```typescript\nconst appMeta = await registerSponsoredWidget(server, {\n endpointUrl: \"https://my-server.example.com/mcp\",\n text: \"Save 15% at checkout\",\n url: \"https://example.com/deal\",\n template: \"banner\",\n});\n```\n\nAn unrecognized `template` raises immediately (before any network call,\ne.g. the logo fetch) rather than silently falling back — same fail-fast\ncontract `register_result_widget`'s template validation already has.\n\n`\"hero\"` accepts one more option, `background_image`/`backgroundImage` — a\nURL fetched once at registration time and inlined the same way `logo` is:\n\n```python\nsponsored_app = register_sponsored_widget(\n mcp,\n endpoint_url=\"https://my-server.example.com/mcp\",\n text=\"Save 15% at checkout\",\n url=\"https://example.com/deal\",\n template=\"hero\",\n background_image=\"https://example.com/hero-bg.jpg\", # optional -- falls back to the gradient\n)\n```\n\n**Templates:**\n\n| `template=` | Layout | Notes |\n|---|---|---|\n| `\"card\"` (default) | Stacked: label line, then logo + text/CTA row | The original hand-built layout — every existing integrator gets this unchanged. |\n| `\"banner\"` | Single horizontal row: label, logo, text/CTA all inline | Better fit for wide-but-short layouts (VS Code sidebar, wide CLI panes) where a stacked card wastes vertical space. |\n| `\"hero\"` | Full-bleed background image (or the shared gradient) with logo/text/CTA anchored over a legibility scrim | `background_image` is optional and integrator-supplied — not yet something ads-server's automatic ad matching can select on its own. |\n| `\"flip-card\"` | Tap/click flips a 3D card — front shows the label, back reveals text + CTA | The disclosed label is always on the front; only the offer's own details are behind the flip. |\n| `\"scratch-reveal\"` | A scratch-off canvas layer over the offer | Auto-reveals after 3s regardless of interaction — the offer is identical either way, this is decoration, never gated content. |\n| `\"spin\"` | A decorative spin-and-settle flourish on the logo badge | Deterministic — always the one real offer, never a variable-outcome mechanic. |\n\nMore formats land here as they ship (carousel, comparison, testimonial,\ncountdown, quiz, video — see the gallery tracked in Linear). Every\ntemplate shares the exact same guarantees: skeleton-on-load, the\ndisclosed `Sponsored` label, the \"Powered by Lulu Ads\" footer, and\nfail-open on missing/malformed data — none of that is renegotiable per\ntemplate.\n\nThis is also what `enable_lulu_ads`/`enableLuluAds` do internally, on your\nbehalf, for every tool — found live (2026-07-26) that getting this step\nright per-tool is easy to forget: our own dogfood server had it wired onto\nexactly one tool by hand, and every tool added since then silently never\ngot it. If you want automatic coverage with no per-tool step, use\n`enable_lulu_ads`/`enableLuluAds` instead of this directly.\n\nShips a floating, rounded, gradient card (same visual system as\n[getlulu.dev](https://getlulu.dev)) with a disclosed `Sponsored` label —\nstill just markup, never a directive. Three host-specific quirks this\nhandles for you: Claude requires an undocumented `_meta.ui.domain` value\nderived from your endpoint URL (self-computed here, not a credential), the\nwidget must send a `ui/notifications/initialized` handshake on load or\nClaude keeps the iframe hidden, and logos are inlined rather than linked\n(next section) so the widget sandbox's own CSP can't silently drop them.\nVerified live against production\n(`dali.getlulu.dev/mcp`, [ext-apps#671](https://github.com/modelcontextprotocol/ext-apps/issues/671)),\ncurrent as of 2026-07-19 — Claude's own rendering of MCP Apps widgets was\nbroken platform-wide before that fix landed, so treat any \"should render\"\nclaim (including this one, elsewhere) as unverified until you've checked\nit live in your own host.\n\nThe widget shows a shadcn `` immediately on load, then swaps to\nreal content only once a live tool call arrives — `text`/`url`/`logo`\npassed to `register_sponsored_widget()` are **not** rendered as initial\ncontent; only `label`/`cta`/`accent*` from those options are actually used\nby the live path (as defaults for fields the wire payload omits, and as\nthe static per-integrator brand theme). On every real tool call, the\nwidget listens for the MCP Apps host's own `ui/notifications/tool-result`\npush (a fresh iframe is mounted per call, not reused — \"per call, not per\ntool\" is a protocol guarantee, nothing had to be built server-side to get\nit) and renders with *that call's* `structuredContent.sponsored` — live,\nper-call ad content, not a fixed payload baked in once at registration. A\nhost that never sends the notification keeps showing the skeleton\nindefinitely (not a fallback ad — see the open gap noted in\n`js/widget-src/src/mcpBridge.ts`'s `InitialOptions` docstring); a call\nwith no `sponsored` field (the normal fail-open case) renders an empty\ncard with only the footer. Card, skeleton, and the \"Powered by Lulu Ads\"\nfooter are one compiled React/shadcn bundle shared byte-for-byte between\nthe Python and TypeScript SDKs (`js/widget-src/`, checked in, embedded by\nboth languages), and the footer always renders inside that same\npersistent card shell, in every state.\n\n### Logos\n\n`logo` takes a URL to **fetch a brand mark from**, not a URL to embed\ndirectly — pass it and the SDK downloads the image right there at\nregistration time and inlines it into the widget as a `data:` URI. This\nisn't incidental: the MCP Apps spec has hosts enforce `img-src 'self' data:\n` inside the widget's sandboxed iframe, and unless *you*\nseparately declare your logo's domain in that resource's CSP config, a\n`

` gets silently dropped — no\nerror anywhere, the card just renders with a blank slot forever, in every\nhost. `data:` URIs are always allowed under that same rule, so fetching and\ninlining server-side sidesteps the whole failure mode — there is no CSP\nconfig for you to get right or forget.\n\nA bad or unreachable `logo` never breaks registration — it's skipped (with\na warning log) and the card renders without one, same as leaving `logo`\nunset. Only `image/png`, `image/jpeg`, `image/svg+xml`, `image/webp`, and\n`image/gif` are accepted, capped at 200KB (the logo renders at 28×28 in the\ncard — there's no reason to ship more than that over the wire).\n\n## CLI rendering\n\nTerminals have no widget surface — the model's own text is the only\noutput there is, and it's genuinely the model's judgment call whether to\nmention the disclosed line at all (never forced, ever — see Guarantees).\n`LuluAdsMiddleware` / `withLuluAds` detect known CLI clients via the MCP\n`clientInfo.name` sent at `initialize` (currently: `claude-code`, verified\nlive) and, when connected from one, append a bordered plain-text card to\n`content[]` in addition to the plain field — still just data, still zero\ninstruction to the model, just formatted so it reads as a distinct block\ninstead of a plain sentence if the model does choose to relay it:\n\n```\n╭─ Sponsored ────────────────────────────────────╮\n│ Search 700+ airlines in one place — Kiwi.com │\n│ finds routes other search engines miss. │\n╰─ via Lulu Ads ─────────────────────────────────╯\n→ https://ads.getlulu.dev/c/9f2a1c\n```\n\nKnown limitation, disclosed here rather than glossed over: some MCP\nclients don't forward every `content[]` block to the model when\n`structuredContent` is also present on the same result — an open\nclient-side bug in Claude Code, twice reported and twice closed without a\nfix ([#55677](https://github.com/anthropics/claude-code/issues/55677) →\nconsolidated into\n[#45575](https://github.com/anthropics/claude-code/issues/45575) →\nauto-closed stale). Live-tested against Claude Code specifically\n(2026-07-21): with `structuredContent` present (the shipped default), the\nboxed card never reaches the model, but the plain `sponsored` field still\ndoes — the model reliably surfaces it as an honest, labeled\n\"Sponsored: ...\" line in its own words, 3/3 runs, no issues.\n\n### `cliTextMode` — opt-in fix for the client bug above\n\nWe also tested the obvious-looking fix — omit `structuredContent` so\n`content[]` has nothing competing with it — and the result depended\nentirely on what else was in `content[]`:\n\n- Ad **alone**, no real tool data alongside it: the card arrives every\n time, but the model flags it as a suspected prompt-injection attempt\n and warns the user off it, 3/3 runs. Worse than not showing it.\n- Ad **alongside a real, complete rendering of the tool's own result**:\n the card arrives every time, the model treats it as an ordinary\n disclosed ad and mentions it neutrally, 3/3 runs. No suspicion.\n\nSo the fix is real, but conditional on your tool's own behavior — which\nthis SDK can't verify for you, hence opt-in, off by default:\n\n```python\nmcp.add_middleware(LuluAdsMiddleware(cli_text_mode=True))\n```\n\n```typescript\nwithLuluAds(server, ads, { cliTextMode: true });\n```\n\nTurn this on only if your tool's `content[]` already contains a\ncomplete, human-readable rendering of the result on its own — not a\nplaceholder like \"see structuredContent\". When on, detected CLI clients\nwith no declared `outputSchema` get `structuredContent` stripped so\n`content[]` (your tool's own text + our card) reliably reaches the\nmodel. Tools that declare an `outputSchema` are never touched by this —\nstripping `structuredContent` there would break client-side schema\nvalidation outright (confirmed: `fastmcp.exceptions.ToolError`\n\"outputSchema defined but no structured output returned\"), which is a\nbroken tool call, a strictly worse outcome than a dropped card. This SDK\nnever drops `structuredContent.sponsored` on schema'd tools to chase card\nvisibility, `cliTextMode` or not.\n\nUntil the upstream client bug is fixed, treat the CLI card as \"renders\nreliably once you opt in and your tool qualifies, on top of a disclosure\nthat already works either way\" — same verify-in-your-own-host caveat as\nthe widget path above.\n\n## stdio servers\n\nEverything above the \"Widget rendering\" section works unmodified on a\nstdio-transport server — the SDK is a library your code imports and calls;\nit doesn't know or care how your own server talks to *its* clients. The\nplain `sponsored` data field (`LuluAdsMiddleware` / `mcp.add_middleware()`,\n`withLuluAds(server)`) takes no endpoint argument and makes a plain\noutbound HTTPS call to `ads.getlulu.dev/slot` — same request whether your\nprocess is a long-running remote server or a `npx`/`uvx`-launched local\none. The CLI text-card path (see \"CLI rendering\" above) is the common\nreal-world case here: Claude Code launches most of its MCP servers over\nstdio, and that's exactly the client this SDK already detects and renders\na disclosed plain-text card for.\n\nThe rendered **MCP Apps widget is the one piece that doesn't apply** —\n`enable_lulu_ads`/`enableLuluAds` and the lower-level\n`register_sponsored_widget`/`registerSponsoredWidget` all require a real\n`endpoint_url`, hashed into Claude's undocumented `_meta.ui.domain` value\nfor the widget's iframe CSP. That's not a Lulu Ads limit; MCP Apps'\n`ui/initialize` handshake is a network protocol between the host and your\nserver's own HTTP endpoint, and a stdio server has none. If your server is\nstdio-only, call `LuluAdsMiddleware`/`mcp.add_middleware()` directly (or\n`withLuluAds(server)` in TypeScript) — never `enable_lulu_ads` — and you\nget the data field plus the CLI text-card, with nothing to configure for\nthe endpoint you don't have.\n\nPublisher-side note: the marketplace's automatic \"monetized\" badge\ncurrently matches a listing to your registered publisher account by\n`remote_url` — a stdio listing has none, so it won't auto-badge even once\nyou've integrated the SDK and are earning. The SDK/earnings path itself is\nunaffected; this is purely a marketplace-listing display gap, being\ntracked separately.\n\n## Guarantees (enforced in code, not just promised)\n\n| Guarantee | How |\n|---|---|\n| A tool call can never break because of ads | every failure path returns `None`/`null`; hard 800ms wall-clock timeout (3000ms when the call implies server-side classification) |\n| Always disclosed | `label: \"Sponsored\"` is set by the SDK, never sourced from the response body |\n| No prompt injection, ever | we ship a data field; there is no display instruction anywhere in the contract |\n| No PII leaves your server | `context` is filtered against an allowlist client-side, before any request is built |\n| Quality-gated | every creative passes [Dali](https://dali.getlulu.dev) scoring (≥70) before it can fill a slot |\n| Intent, not identity | targeting uses this call's stated context only — no user profiles, no cross-session ID |\n| Misconfigured? Still safe | missing credentials → client is inert, returns `None`/`null`, zero network calls |\n\n## Why not just…\n\n**…tell the model to mention a sponsor in its reply?**\nDisplay instructions get MCP servers delisted by registries that scan for\ninjected directives. We ship a plain data object — `label`, `text`, `url` —\nwith no field, anywhere in the contract, that tells a model how to render or\nphrase anything.\n\n**…count impressions and charge per view?**\nAn \"impression\" only exists if a model actually rendered it, and that's\nunverifiable from the server side — easy to game, hard to audit. We charge\nCPA only, on a click that redeems a signed, server-verified token. Payment\nmaps to a real user action, not a claim.\n\n**…scan the conversation to target better?**\nReading transcripts to target ads is a privacy trap: everything a user says\nbecomes ad-targeting data. We accept six allowlisted context keys — `tool`,\n`category`, `query`, `route`, `locale`, `country` — stated intent for this\ncall only. No transcripts, no profiles, no PII fields exist in the schema.\n\n## How it works\n\n```\ntool call\n │\n ▼\nyour tool's own result\n │\n ▼\nPOST /slot (1500ms cap — 3000ms when classifying a raw prompt — allowlisted context only)\n │\n ▼\nlabeled data field { label: \"Sponsored\", text, url } ← attached, never injected\n │\n ▼\nhost / model judgment → renders it, or doesn't — not our call\n │ user clicks\n ▼\nGET /c/{token} → signed redirect, click recorded\n │\n ▼\nadvertiser's affiliate rails → POST /postback on conversion\n │\n ▼\n70% publisher / 30% Lulu, on the ledger. Earnings accrue to your balance from the first audited conversion — cash out from $100.\n```\n\nFull wire-level detail: [`docs/contract.md`](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/contract.md).\n\n---\n\nDocs: https://getlulu.dev/docs · [Quickstart](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/quickstart.md) ·\n[API contract](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/contract.md) · [Integrations](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/integrations.md) ·\n[Publisher signup](https://getlulu.dev/publishers) · Quality gate:\n[Dali](https://dali.getlulu.dev) · [MIT](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/LICENSE)\n\n## Changelog\n\n- **0.9.13** — Fixed a rendered-impression billing gap (LUL-71) in the\n standalone sponsor-card widget (`register_sponsored_widget()`/\n `registerSponsoredWidget()` — the React-built card, banner, flip-card,\n scratch-reveal, spin, and hero templates): the wire payload's `imp_url`/\n `impUrl` field was parsed and exposed by both clients (`Sponsored.impUrl`\n in the Node SDK, `imp_url` in the Python client) but silently dropped by\n the widget bundle's own message parsing before it ever reached the\n React components — so the rendered-impression beacon (a 1px `` that\n confirms a human actually saw the ad, which CPM is billed against) never\n fired for this widget at all, for any template, since it shipped. Fixed\n centrally in `App.tsx`'s loading→\"loaded\" transition — the same moment\n every template's disclosed content becomes visible, including\n flip-card's front teaser (fires before the user ever flips it, matching\n `register_result_widget()`'s footer strip's own already-correct\n behavior) and scratch-reveal's covered content (fires before anyone\n scratches). `register_sponsored_widget()`/`registerSponsoredWidget()`\n also now declare the `ads.getlulu.dev` resource/connect CSP domains the\n beacon pixel needs to not be silently blocked by a host's default\n `img-src 'self' data:` policy — the same declaration\n `register_result_widget()` already had. Verified live: the beacon fires\n a real HTTP request the instant a `tool-result` with `imp_url` arrives,\n confirmed via a local server's access log, not just unit tests.\n- **0.9.12** — Result-widget footer `sponsor_template=` (LUL-69) redesigned\n from a slim single-line strip into a cover card: a colorful cover band —\n a real sponsor image when the live payload supplies `cover_image_url`/\n `coverImageUrl`, an animated gradient otherwise — with the logo tile\n overlapping the seam into the body, bigger type, and a real pill CTA\n button. `\"flip-card\"`'s teaser now carries the same cover identity\n instead of a bare label. `\"spin\"` is removed: a coin-flip `scaleX`\n animation on a small, often-flat letter-tile logo turned out visually\n illegible in practice (mid-animation it shrinks to a near-invisible\n sliver against a busy cover background), caught live rather than\n inferred. It's replaced by `\"carousel\"` — auto-cycles through three\n framings of the *same* single sponsored payload (a bigger brand logo,\n the offer text, then the CTA), never multiple sponsors: this frame only\n ever gets one sponsored payload per call, so unlike the standalone\n gallery's carousel template there is no multi-advertiser rotation here\n (see LUL-49 for that separate, still-blocked, backend question).\n `\"scratch-reveal\"` is restyled as a lottery-ticket foil stub — gold\n metallic gradient, diagonal hatching, a dashed perforation line, a\n ticket glyph — and its auto-reveal window is 5s now, not 3s, long enough\n to actually register as an interaction; it remains a strictly\n deterministic reveal with no \"win/lose\" state, which is what keeps the\n ticket styling out of actual gambling-mechanic territory. The \"single\n row, no room for a full-bleed image\" reasoning that used to also exclude\n `\"hero\"` no longer holds now that the strip itself is cover-height —\n noted as an open follow-up, not resolved by this release.\n- **0.9.11** — `register_result_widget()`/`registerResultWidget()` gain\n `sponsor_template=`/`sponsorTemplate:` (LUL-69): the SPONSORED strip built\n into a result widget's footer (`stat-card`/`table-card`/`notice-card`/\n `carousel-card` — a publisher's own tool output, not the standalone\n sponsor-card widget) can now pick a visual format too, independent of\n `template=`, this widget's own body layout. `\"card\"` (default) is the\n original always-visible strip. `\"flip-card\"` is a compact \"Sponsored\"\n teaser that crossfades to reveal the real offer on tap — the front\n face carries an actual prompt (\"Tap to reveal →\"), not just a bare\n disclosure label, so there's a reason to tap it. `\"spin\"` is a\n decorative spin-settle flourish on the logo badge, content visible\n immediately, never gated (no variable outcomes — see the spin\n guardrail below). `\"scratch-reveal\"` is a canvas scratch-off layer,\n auto-revealing after 3s regardless of interaction — the offer\n underneath is identical whether or not anyone scratches. `\"banner\"`/\n `\"hero\"` are deliberately not offered here: this strip is already one\n horizontal row (banner would be a no-op) and a full-bleed background\n doesn't fit a slim footer bar. This is a different system from the\n standalone sponsor-card gallery above (`register_sponsored_widget()`'s\n own `template=`) — same template *names* where they overlap, ported\n into this frame's own vanilla-JS renderer rather than sharing code,\n since the two frames are independent implementations by design.\n- **0.9.10** — Four more templates: `\"flip-card\"` (LUL-53, a CSS 3D flip on\n tap revealing the offer on the back face — front always shows the\n disclosed label first, never hides *what* this is, only the offer\n details), `\"scratch-reveal\"` (LUL-52, a canvas scratch-off layer,\n auto-reveals after 3s regardless of interaction — the underlying offer\n is identical whether or not anyone scratches, this is a reveal\n animation, never gated content), `\"spin\"` (LUL-54, a decorative\n spin-and-settle flourish on the logo badge — deterministic by design, no\n wheel-of-fortune-style variable outcomes, since that would be a gambling\n mechanic), and `\"hero\"` (LUL-48, a full-bleed background image or\n gradient with logo/text/CTA anchored over a legibility scrim).\n `register_sponsored_widget()`/`registerSponsoredWidget()` also gain an\n optional `background_image`/`backgroundImage` param for `\"hero\"` — same\n fetch-once-and-inline-as-`data:`-URI contract `logo` already has (a\n fetch failure just falls back to the shared gradient, never a\n registration error). This is integrator-supplied, registration-time\n branding, same category as `logo`/`accent*` — not yet wired into\n ads-server's automatic per-campaign ad matching, which doesn't have an\n image field of its own (tracked separately).\n- **0.9.9** — First real entry in the template gallery: `template=\"banner\"`\n (LUL-47), a full-width horizontal strip (label, logo, text/CTA all in one\n row) instead of the default `\"card\"`'s stacked layout — better fit for\n wide-but-short surfaces (VS Code sidebar, wide CLI panes). Same shared\n contract as every template: renders inside the same persistent gradient\n shell, same disclosed label + \"Powered by Lulu Ads\" footer, same\n skeleton-on-load and fail-open behavior — nothing about those guarantees\n is template-specific. No background-image support yet (LUL-47's spec\n allows \"image or gradient\"; a real background-image field needs new\n schema on the advertiser side, tracked separately) — uses the existing\n accent-token gradient. Docs added: Widget rendering now documents\n `template=` with a live example and a table of available formats.\n- **0.9.8** — `register_sponsored_widget()` / `registerSponsoredWidget()` gain\n a `template=` parameter (LUL-46), same shape as `register_result_widget`'s:\n keyword-only, defaults to `\"card\"` (today's only format, fully backward\n compatible — no existing integrator's call site changes behavior), raises\n immediately on an unrecognized value (before any network call, e.g. the\n logo fetch). This is a registration-time integrator choice, not a\n per-call value — matches the static, \"baked into the compiled bundle at\n registration\" behavior `register_result_widget`'s own template already\n has, not something that varies per served ad. Foundational only: the\n registry/dispatch mechanism in `js/widget-src/` now supports looking up a\n template by name, but `\"card\"` (the existing hand-built layout) is still\n the only entry — more templates land in their own follow-up releases as\n they're built (banner, hero, carousel, comparison, flip-card,\n scratch-reveal, spin, testimonial, countdown, quiz, video). Also fixes a\n real, pre-existing drift: the TS SDK's own `SDK_VERSION` telemetry\n constant had been stuck at `0.9.0` since a much earlier release despite\n `package.json` moving on to `0.9.6` — realigned here, and the two\n packages' version numbers themselves are now back in sync (the previous\n `0.9.7` was Python-only; the TS package skips straight to `0.9.8`).\n- **0.9.7** (Python only) — CLI/text clients now get a **delivery-confirmed**\n beacon: the normal rendered-impression pixel (`imp_url`) is fetched by a\n rendering client itself the instant it displays the sponsored strip —\n terminal/CLI hosts (Claude Code and friends) have no rendering engine to\n do that, so every CLI-delivered card was previously invisible in\n `ad_events`, full stop, even on 100%-successful deliveries. The\n middleware now fires that same beacon URL itself (fire-and-forget,\n non-blocking, tagged `src=cli_server`) the moment it appends a card to a\n CLI client's `content[]`, on both is_cli card-append paths (the\n middleware's own fetched slot, and a tool's pre-set `sponsored`). This\n logs as a new, distinct `cli_card_delivered` event — **not**\n `impression_rendered`, and never counted toward CPM billing/payout — a\n deliberately weaker signal than a real rendered-pixel hit: it proves the\n card left the server in the tool response, never that a human actually\n saw it. Needs no config; existing `imp_url`-carrying slots pick this up\n automatically. (ads-server: `/i/{token}` now accepts an optional\n `src=cli_server` query param to log the distinct event type.)\n- **0.9.6** — Docs only: new [Supported surfaces](https://github.com/Lulu-The-Narwhal/lulu-ads/blob/master/docs/supported-surfaces.md)\n page sorting every agent surface (chat hosts, agentic SDKs/frameworks,\n response-suffix runtimes, AI app builders, MCP hosting/registries) by how\n it actually reaches the SDK — a direct adapter, MCP protocol passthrough\n (no adapter needed once a server has Lulu Ads wired in), the generic\n `format_suffix` contract, or genuinely not yet evaluated — same\n evidentiary bar as the rest of this repo. Also adds a \"stdio servers\"\n section clarifying the data-field path needs no `endpoint_url` and works\n unmodified on stdio-transport servers; only the rendered MCP Apps widget\n requires one and can't apply to stdio. Also fixes `lulu_ads.__version__`,\n which had drifted to 0.9.0 while the package published as 0.9.5 — same\n class of bug as the 0.7.0 entry below, recurred because nothing enforces\n the two staying in sync; consider that the next real gap to close here.\n- **0.9.2** (Python only) — Fixed a middleware bug: a tool that sets its\n own `sponsored` field (a documented pattern for e.g. a category-specific\n cross-sell) triggered the \"never overwrite\" early return in\n `on_call_tool` before the CLI-client check ran, so CLI hosts (Claude\n Code) got no visible ad at all on that tool — no widget surface, and no\n text-card safety net either, both skipped by the same early exit. The\n client check now runs first; a pre-set `sponsored` value still gets the\n CLI text-card treatment, using the tool's own chosen ad.\n- **0.9.1** — `table-card` widget gains `rowLink`: an optional per-row\n dot-path resolving to a URL (e.g. a booking/checkout link), wired to\n the same host-agnostic `openLink()` the sponsored strip already uses.\n Rows without a resolvable URL render exactly as before.\n- **0.9.0** — Skybridge (https://skybridge.tech) support:\n `withLuluAdsSkybridge(server)` (`lulu-ads/skybridge`). Skybridge's\n `McpServer.registerTool` takes a 2-arg `(config, handler)` shape with\n `name` folded into `config`, not the official SDK's 3-arg\n `(name, config, handler)` that `withLuluAds` wraps — reusing `withLuluAds`\n as-is would misread the config object as the tool name. The new adapter\n instead uses Skybridge's own `mcpMiddleware(\"tools/call\", ...)` protocol\n hook, verified against the real `skybridge@1.4.0` package's shipped types\n and a live `InMemoryTransport` round-trip. Deliberately `_meta`-only:\n the middleware sees the call result but not the tool's registered\n `outputSchema`, so `structuredContent` is never touched.\n- **0.8.1** — Result-widget template gallery (supersedes 0.8.0, which\n briefly shipped on npm with a louder strip design): `lulu_ads.widgets` /\n `lulu-ads/widgets` with four predefined templates (`stat-card`,\n `table-card`, `notice-card`, `carousel-card`), design tokens + `.lw-*`\n primitives, and the disclosed SPONSORED strip built into the frame\n (advertiser logo via the slot's new `logo_url`, letter-tile fallback).\n `register_result_widget()` patches an already-registered FastMCP tool in\n place (or returns the AppConfig for explicit `app=`).\n\n- **0.7.4** — Widget: the sponsored card's iframe canvas no longer paints\n an opaque white box on dark hosts. `background: transparent` alone is\n not enough for an embedded iframe: Chromium keeps the canvas\n transparent only when the embedded document's used color scheme matches\n the embedder's, and this document declared none (defaulting to\n `light`), so dark-themed hosts (e.g. claude.ai in dark mode) forced a\n white backdrop behind the card. The widget now declares\n `color-scheme: light dark`, which resolves to the user's preferred\n scheme — matching hosts that follow it (claude.ai does by default) on\n both light and dark themes. Verified empirically against light- and\n dark-scheme embedding pages. (Also aligns `lulu_ads.__version__`, which\n had drifted to 0.7.2 while the packages published as 0.7.3.)\n\n- **0.7.0** — Two real bugs, found live against a real third-party MCP\n server behind Claude.ai's remote connector, both fixed:\n - **0% ad delivery on hosts that reconnect per message** (confirmed:\n Claude.ai opens a brand-new MCP session per chat message, not once per\n conversation). Root cause: this SDK's persistent HTTP connection goes\n cold on any real idle gap between messages, but only a one-time\n \"have I ever succeeded\" check protected the very first call ever —\n every later cold call still got the tight steady-state timeout and\n failed. Fixed by re-checking coldness on every call, keyed to time\n since the last real success, not a permanent latch. Also: the fast\n steady-state timeout itself was raised 800ms → 1500ms\n (Python and TS) — production evidence showed even \"warm\" calls\n sometimes measuring 796-802ms, right at the old line rather than\n comfortably under it.\n - **Ad fetched successfully, never seen by the model.** FastMCP/the\n MCP TS SDK build a tool result's `content[]` once, from the tool's\n original return value, before `LuluAdsMiddleware`/`withLuluAds` ever\n run — mutating `structuredContent` alone (the only thing this SDK's\n own test suite checked) left `content[]` permanently stale. Confirmed\n live: the wire response's `structuredContent` demonstrably had\n `sponsored`, but Claude.ai read and reported back from `content[]`,\n which didn't. Both SDKs now keep `content[]` in sync whenever it's\n safe to (a single auto-generated JSON text block); regression tests\n added for the exact gap that let this ship unnoticed the first time.\n - **New:** `enable_lulu_ads()` (Python) / `enableLuluAds()` (TS) — one\n call that wires both the data field AND the rendered MCP Apps widget\n onto every tool automatically, present and future. Existing\n `register_sponsored_widget()`/`registerSponsoredWidget()` +\n `app=`/`_meta.ui` per tool still works and is now documented as the\n lower-level building block for per-tool control; the gap it left (an\n easy-to-forget manual step per tool) is exactly what this closes —\n found live on our own dogfood server, which had wired the widget onto\n exactly one tool by hand and silently never updated it for tools\n added since.\n- **0.6.2** — The sponsored card now plays a one-time diagonal light sweep\n across itself when it settles into the loaded state (a real ad won) —\n pure CSS (`.card-shine` in `js/widget-src/src/index.css`), fires exactly\n once per mount (not a looping shimmer, since this sits inline in a real\n chat thread), and respects `prefers-reduced-motion`. Skeleton and\n no-fill states are unaffected.\n- **0.6.1** — Corrects a stale `0.6.0` published to npm before `dist/` was\n rebuilt from the merged source (`js/` has no `prepublishOnly` build\n step) — 0.6.0 is deprecated on npm pointing here. Also fixes README.md\n and both languages' `widget.py`/`widget.ts` docstrings, which\n incorrectly claimed `text`/`url`/`logo` passed to\n `register_sponsored_widget()` render as a fallback \"house ad\" until a\n live `tool-result` arrives; they never do — the widget shows the\n skeleton indefinitely if a host never pushes it.\n- **0.6.0** — The MCP Apps sponsored widget now shows **live, per-call ad\n content** instead of a fixed house ad baked in at registration time:\n rebuilt in React + shadcn/ui (`Card`, `Skeleton`, `Button`), compiled to\n a single self-contained bundle shared byte-for-byte by both SDKs\n (`js/widget-src/`). The widget shows a skeleton immediately on load,\n then listens for the MCP Apps host's own `ui/notifications/tool-result`\n push — which the spec already delivers once per call, to a fresh iframe\n per call, with no server-side change needed — and swaps to that call's\n real `structuredContent.sponsored` data — the widget shows the skeleton\n indefinitely if a host never pushes it, not a fallback ad; only\n `label`/`cta`/`accent*` from `register_sponsored_widget()`/\n `registerSponsoredWidget()`'s options are actually used by the live\n path. The \"Powered by Lulu Ads\" footer renders once, immediately, and\n is never itself part of the skeleton→card swap. Live-verified against a\n real host (claude.ai) with a throwaway test server: skeleton renders\n before the tool call resolves, swaps to the real per-call card once it\n does, the footer never disappears or reflows during the swap, and two\n tool calls in the same turn render two fully independent widget\n instances, each showing only its own call's data — confirming the \"per\n call, not per tool\" behavior this feature is built on. (The CTA's\n `ui/open-link` redirect — vs. a raw navigation — was re-confirmed by\n static code inspection and this repo's existing unit tests during this\n same pass; live click-through capture was attempted but blocked by\n browser-automation tooling limits reaching inside the host's\n double-sandboxed iframe, not by any observed product failure.)\n- **0.4.0** — Automatic pre-connect on construction for LangChain's\n `LuluAdsAgentMiddleware`, CrewAI's `install()`, and TypeScript's\n `withLuluAds` (matching the FastMCP `LuluAdsMiddleware`, which already\n had this). Also: FastMCP's `LuluAdsMiddleware` and LangChain's\n `LuluAdsAgentMiddleware` now additionally warm the **async** connection\n pool their `await`ed `sponsored_slot()` traffic actually uses — the\n construction-time warm-up above only ever touched the sync client, a\n separate pool the async path never touches. `LuluAds.async_warm_up()`\n is fired once per instance from a real framework lifecycle hook on the\n live serving event loop (FastMCP's `on_initialize`, LangChain's\n `abefore_agent`), since a background thread can't safely pre-warm a\n connection meant for a different event loop. Gated by the same\n `auto_warm_up` flag as the sync warm-up (this async path is Python-only —\n TypeScript's `autoWarmUp` only ever had one pool to gate). This is the fix\n that closes the cold-start gap for `dali-mcp` in production, which\n consumes the async path. Short-TTL (default 45s) success-only cache in\n both base clients, keyed on resolved category or a hash of the prompt\n text. Corrected documentation: the real default timeout is 800ms (fast\n path) / 3000ms (classify path) adaptive, not a flat 300ms.\n- **0.3.7** — `cliTextMode` (opt-in, off by default): fixes the Claude Code\n content[]-drop bug for real, but only for tools whose `content[]` already\n stands on its own without `structuredContent` — live-tested both\n qualifying and non-qualifying cases, see \"CLI rendering\". Never touches\n tools with a declared `outputSchema` (would break client-side schema\n validation, confirmed via `fastmcp.exceptions.ToolError`).\n- **0.3.6** — automatic connection warm-up on `LuluAdsMiddleware` construction\n (`auto_warm_up`, on by default): a genuinely cold first tool call measured\n 804ms against the 800ms fast-path default — right at the ceiling, not\n under it. `LuluAds` itself still never auto-warms (a network call as a\n constructor side effect is surprising in a general-purpose client), but\n the middleware is the \"one line, zero config\" promise, so it warms itself.\n- **0.3.5** — fixed a hardcoded 300ms default `timeout_ms` on\n `LuluAdsMiddleware` that silently dropped real, fillable ads on real\n network latency — every test in the suite used an instant mock transport,\n which is exactly why this shipped unnoticed. Default is now `None`,\n deferring to `LuluAds`'s own conditional 800ms/3000ms default.\n- **0.3.4** — CLI card gets rounded corners and a \"via Lulu Ads\" footer\n (Unicode box-drawing only — a live test against Claude Code confirmed it\n strips raw ANSI color escapes from tool output before the model sees\n them, so color was never on the table). Also live-tested and explicitly\n rejected dropping `structuredContent` to force `content[]` through: it\n does make the card arrive, but the model then flags it as suspected\n prompt injection and warns the user off it — worse than the status quo,\n where the plain field still gets surfaced honestly even without the\n card. See \"CLI rendering\" for the full writeup.\n- **0.3.3** — CLI-adaptive rendering: `LuluAdsMiddleware` / `withLuluAds` detect\n known CLI clients via the MCP `clientInfo.name` sent at `initialize`\n (currently: `claude-code`, verified live) and append a bordered plain-text\n card to `content[]` for them, in addition to the plain field — terminals\n have no widget surface, so this is the CLI-safe equivalent of the MCP Apps\n widget above. Still just data; see \"CLI rendering\" for the disclosed known\n limitation on some clients' `content[]` forwarding.\n- **0.3.0** — `register_sponsored_widget()` / `registerSponsoredWidget()` gain\n a `logo` option: fetched server-side at registration time and inlined into\n the widget as a `data:` URI, so it renders under the widget sandbox's CSP\n (`img-src 'self' data: `) with no `resourceDomains` config\n needed on your part — a raw remote logo URL would otherwise be silently\n dropped, with no error anywhere. A bad/unreachable logo never breaks\n registration; the card just renders without one. TypeScript's\n `registerSponsoredWidget()` is now `async` (it may need to fetch the logo\n before returning) — add `await` at existing call sites.\n- **0.2.0** — `register_sponsored_widget()` (Python: `lulu_ads.widget`, now also\n TypeScript: `lulu-ads/widget`, official MCP SDK): registers a real rendered\n MCP Apps UI sponsored card on your server (not just the plain JSON field),\n handling Claude's undocumented iframe-domain requirement and the\n `ui/notifications/initialized` handshake for you. Generalizes the fix\n verified live on `dali.getlulu.dev/mcp` against\n [ext-apps#671](https://github.com/modelcontextprotocol/ext-apps/issues/671).\n Both SDKs produce byte-identical `_meta.ui.domain` values for the same\n endpoint URL.\n- **0.1.1** — persistent HTTP clients in the Python SDK (per-call client\n construction could burn the entire slot budget on CPU-constrained\n containers; clients are now created once per `LuluAds` instance and reused\n with keep-alive). Fail-open behavior unchanged.\n- **0.1.0** — initial release: Python + TypeScript clients, FastMCP /\n LangChain / LangGraph / CrewAI / MCP-TS adapters, suffix helpers, MCP\n concierge onboarding.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_104":105,"_106":107,"_108":109,"_110":111,"_112":113,"_114":115},"requiredSecrets",[],"tags",[100,101,102,103],"assets",[],"stats",{"_98":85,"_99":85},"ratingAvg","reviewCount","advertising","ai-agents","monetization","sdk","topics",[100,101,116,117,118,102,103],"license","MIT","language","TypeScript","registryName","io.github.Lulu-The-Narwhal/lulu-ads","homepage","https://getlulu.dev","packages",[],"mcp","mcp-server","model-context-protocol","ENV",{"_121":122,"_123":124,"_125":126},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]