hermoso 0.1.139 → 0.1.141

package/README.md

@@ -27,17 +27,32 @@ just download it. Use the one piece you need, or all of it together.
 Paste **`https://app.hermoso.ai/mcp`** into Claude → Settings → Connectors → *Add custom connector*, approve with
 your Hermoso account, done — the full toolset with your saved brand context, billed to your plan.
 
-## Quickstart for Claude Code / Cursor / scripts (2 minutes)
+## Quickstart for Claude Code (one line)
 
 1. **Get an account** at [app.hermoso.ai](https://app.hermoso.ai) — free tier included; plans & credits are the
    same ones the web Studio uses.
-2. **Create an agent key**: app.hermoso.ai → **Settings → Agents & API** → Create API key (`hmk_…`).
-3. **Connect** — no clone needed, `npx` runs the published `hermoso` package (Claude Code shown; any MCP client works):
+2. **Run one line.** Your browser opens once to sign in. Nothing to paste, and no key lands in `.claude.json`:
+
+```bash
+npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp
+```
+
+3. **Ask for what you want**, in your normal prompts. Claude Code reaches for a tool, or runs the `hermoso`
+   command in your terminal, whichever the job needs. You type neither.
+
+Ad campaign and analytics tools stay out of the tool list until you switch them on with `enable_tools`, which
+keeps it small. On a machine with no browser, sign in with `hermoso auth login --token hmk_…` using a key from
+**Settings → Agents & API**, or skip the sign-in and pass the key to the client instead:
 
 ```bash
 claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp
 ```
 
+The hosted URL works in Claude Code too, but it is the worse path there and it is worth knowing why:
+`claude mcp add --transport http hermoso https://app.hermoso.ai/mcp` is accepted, and then `claude mcp list`
+reports `! Needs authentication` because the client will not start the OAuth flow by itself — you have to open a
+session, run `/mcp`, find the server and press Authenticate. Measured against Claude Code 2.1.241 on 2026-08-23.
+
 Your agent now has the full studio **with your workspace's context**: the brand profile, products, logos and
 learned memory you set up in the web app apply automatically (`get_brand` shows what's saved; omit `brand` in
 `plan_ad`/`plan_variations` to use it). Renders bill your Hermoso credits — same prices as the Studio.
@@ -45,13 +60,15 @@ learned memory you set up in the web app apply automatically (`get_brand` shows
 ## 1. MCP server (stdio) — Claude Code / Cursor / Codex
 
 `hermoso mcp` runs a stdio MCP server exposing the full toolset. The published `hermoso` package means no clone —
-`npx -y hermoso mcp` fetches and runs it:
+`npx -y hermoso mcp` fetches and runs it. Sign in once with the CLI and no key goes into any client config,
+because `hermoso mcp` reads the bearer `hermoso auth login` stored:
 
 ```bash
-claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp
+npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp
 ```
 
-Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
+Cursor / Codex — sign in the same way, then add to `mcp.json` (Codex uses the TOML equivalent). Drop the `env`
+block entirely if you signed in above; it is there for CI, where the process cannot read your home directory:
 
 ```json
 { "mcpServers": { "hermoso": { "command": "npx", "args": ["-y", "hermoso", "mcp"],

package/mcp/client.mjs

@@ -130,6 +130,18 @@ export async function apiPut(p, body = {}) {
 // file reads on the hosted connector (it runs on the SERVER host, not the user's machine — an LFI/exfil vector).
 export const isRemote = () => !!mcpCtx.getStore();
 
+// DOES THIS HOST RENDER OUR WIDGETS ITSELF?
+// ChatGPT (the Apps SDK) draws every finished render in `ui://widget/ad-result.html`, hydrated from
+// `structuredContent`. For that host the inline base64 image block in `content` is not just redundant, it is
+// actively harmful: a finished 1:1 render is ~1 MB of base64, and a result that size arrived in ChatGPT with an
+// EMPTY toolOutput — the card drew its "No media in this result yet" empty state while the model narrated success
+// from the text block. Measured 2026-08-23: structuredContent, outputSchema, the tools/list binding and the widget
+// itself were each verified correct in isolation, and the oversized `content` was the only thing left.
+// Claude has no widget, so it KEEPS the inline block — that is the only reason it renders an image in chat at all.
+// Advisory and fail-open: an unrecognised or absent client behaves exactly as before.
+const WIDGET_HOSTS = /openai|chatgpt/i;
+export const hostRendersWidgets = () => WIDGET_HOSTS.test(mcpCtx.getStore()?.client || '');
+
 // ── WHICH WORKSPACE'S STORE KEYS THIS CALL WRITES ──────────────────────────────────────────────────────────────
 // The suffix synced store keys carry (`` = the bare/anchor keys, `<clientSlug>` = a sub-brand). It comes from the
 // SERVER (`GET /api/workspace` → resolveWs), never from this process's environment, because on the hosted twin the

package/mcp/http.mjs

@@ -32,12 +32,37 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
   // RFC 9728 protected-resource metadata — tells Claude.ai where to get a token. (Authorization-server metadata
   // is served by the auth provider itself, e.g. Firebase/your IdP.) Scopes match the AS metadata + minted token
   // (mcp/oauth.mjs): hermoso.research / hermoso.generate.
-  app.get('/.well-known/oauth-protected-resource', (req, res) => res.json({
-    resource: `${BASE}/mcp`,
+  // ── SERVED AT BOTH URL FORMS, FROM ONE HANDLER (2026-08-20) ──────────────────────────────────────────────────
+  // The resource identifier is `${BASE}/mcp`, which HAS a path component — so RFC 9728 §3.1 derives its metadata
+  // URL by INSERTING the well-known suffix before that path ("any terminating slash (/) following the host
+  // component MUST be removed before inserting /.well-known/ and the well-known URI path suffix between the host
+  // component and the path"), i.e. /.well-known/oauth-protected-resource/mcp. We served only the ROOT form, and
+  // that was not a cosmetic gap — it was a DEAD END for any client that does not use our WWW-Authenticate hint,
+  // because RFC 9728 §3.3 applies a DIFFERENT validation rule depending on how the client arrived:
+  //   • via the `resource_metadata` hint → `resource` MUST equal the URL used to reach the resource server
+  //     (`${BASE}/mcp`). Our document satisfies this, which is why Claude connects today.
+  //   • by CONSTRUCTING the well-known URL → `resource` MUST equal the identifier the suffix was inserted into.
+  //     From the ROOT form that identifier is `${BASE}` (no /mcp) while our document says `${BASE}/mcp`, and the
+  //     rule is "the data contained in the response MUST NOT be used". So a hint-less client had nowhere to land:
+  //     the suffixed URL 404'd, and the root URL it fell back to failed validation.
+  // Serving BOTH is explicitly sanctioned — the MCP spec's fallback order is suffixed-then-root ("Serve metadata
+  // at a well-known URI … either: At the path of the server's MCP endpoint … or At the root"). ONE handler, never
+  // a second copy of the document: two copies drift, and a stale one is worse than a 404.
+  //
+  // DELIBERATELY ASYMMETRIC with /.well-known/oauth-authorization-server (mcp/oauth.mjs), which is NOT aliased:
+  // its `issuer` is BASE with NO path component, so RFC 8414 §3.1 puts its metadata at the root URL, and §3.3
+  // would force a client to REJECT the identical document served under a /mcp suffix (it would have constructed
+  // that URL from issuer identifier `${BASE}/mcp`, which is not what the document says). The 404 there is
+  // CORRECT and is what lets a probing client fall through cleanly. Alias it only if `issuer` ever grows a path.
+  const MCP_PATH = '/mcp';                            // the resource's path component — app.all(MCP_PATH) below
+  const protectedResourceMetadata = (req, res) => res.json({
+    resource: `${BASE}${MCP_PATH}`,
     authorization_servers: [process.env.HEIST_OAUTH_ISSUER].filter(Boolean),
     scopes_supported: ['hermoso.research', 'hermoso.generate'],
     bearer_methods_supported: ['header'],
-  }));
+  });
+  app.get('/.well-known/oauth-protected-resource', protectedResourceMetadata);
+  app.get(`/.well-known/oauth-protected-resource${MCP_PATH}`, protectedResourceMetadata);
 
   // Per-session Streamable-HTTP transports. Each authenticated session gets its own McpServer with the same tools.
   //
@@ -88,6 +113,16 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
   // anything: building a 36 MB McpServer purely to have it reject the request is what turned a retry storm into
   // an OOM. Status and message are byte-identical to the SDK's, so no client sees a behaviour change.
   const needSession = (res) => res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Bad Request: Mcp-Session-Id header is required' }, id: null });
+  // The one place the host name is turned into a decision, so the anon and session paths cannot diverge.
+  const isWidgetHost = (name) => /openai|chatgpt/i.test(String(name || ''));
+  // The client's own name, off the initialize params. Never trusted for anything but presentation.
+  const clientInfoOf = (body) => {
+    try {
+      const msgs = Array.isArray(body) ? body : [body];
+      for (const m of msgs) if (m && m.method === 'initialize') return String(m.params?.clientInfo?.name || '').slice(0, 64);
+    } catch {}
+    return '';
+  };
   const hasInitialize = (body) => (Array.isArray(body) ? body : [body]).some((m) => m && m.method === 'initialize');
 
   // ── PRE-AUTH DISCOVERY (registry crawlers + evaluating agents) ────────────────────────────────────────────────
@@ -124,14 +159,17 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
 
   async function serveAnonDiscovery(req, res, scope) {
     const server = new McpServer({ name: 'hermoso', version: '1.0.0' }, { instructions: MCP_INSTRUCTIONS });
-    registerTools(server, { only: scope?.groups }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
+    // `widgetHost` withholds the two commerce tools from ChatGPT (see registerTools). It is passed HERE as well
+    // as on the session path because OpenAI's own tool scanner reads this anonymous discovery roster — gating
+    // only the authenticated path would leave both tools listed in the submission.
+    registerTools(server, { only: scope?.groups, widgetHost: isWidgetHost(clientInfoOf(req.body)) }); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
     res.on('close', () => { try { transport.close(); server.close(); } catch {} });
     await server.connect(transport);
     await transport.handleRequest(req, res, req.body);
   }
 
-  app.all('/mcp', async (req, res) => {
+  app.all(MCP_PATH, async (req, res) => {
     const auth = req.headers.authorization || '';
     const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
     const user = token ? await verifyBearer(token).catch(() => null) : null;
@@ -163,14 +201,21 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
       if (scope === false) return; // unknown group — already answered 400, and nothing was allocated
       sweepSessions(); // make room before allocating, so the cap is a ceiling and not a suggestion
       const server = new McpServer({ name: 'hermoso', version: '1.0.0' }, { instructions: MCP_INSTRUCTIONS });
-      registerTools(server, { only: scope.groups }); // the SAME tools as stdio (minus any the caller scoped out) — and every /api call they make carries this user's token
+      registerTools(server, { only: scope.groups, widgetHost: isWidgetHost(entry?.client || clientInfoOf(req.body)) }); // the SAME tools as stdio (minus any the caller scoped out) — and every /api call they make carries this user's token
       const transport = new StreamableHTTPServerTransport({
         // CSPRNG, per the spec's SHOULD for session ids (Math.random() is not one).
         sessionIdGenerator: () => 'sess_' + randomUUID().replace(/-/g, ''),
         onsessioninitialized: (id) => { entry.lastSeen = Date.now(); sessions.set(id, entry); sweepSessions(); },
       });
       transport.onclose = () => { if (transport.sessionId) dropSession(transport.sessionId, 'transport closed'); };
-      entry = { transport, server, user, lastSeen: Date.now() };
+      // WHO IS CALLING, captured at the ONE moment it is on the wire. `clientInfo` rides the `initialize`
+      // request and nothing afterwards, so it has to be remembered on the session or it is gone by the first
+      // tools/call. It is advisory only: it may not change auth, scope or spend — it decides PRESENTATION.
+      entry = { transport, server, user, lastSeen: Date.now(), client: clientInfoOf(req.body) };
+      // LOG THE NAME. `hostRendersWidgets()` matches it with a regex, and a regex over a string no one has
+      // ever read is a guess. One line per session (not per call) so a new host identifies itself once and
+      // the predicate can be corrected from evidence instead of from a hunch.
+      if (entry.client) console.error(`[mcp-remote] client: ${entry.client}`);
       await server.connect(transport);
       // If the handshake never completes (client drops, initialize rejected), nothing is in the map and both
       // objects are otherwise reachable only from this request's still-open response — close them explicitly
@@ -192,7 +237,7 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
     // forgeable value is exactly the hole resolveWs exists to close. The workspace a hosted connector acts in is
     // pinned SERVER-SIDE on the agent key (use_brand → /api/keys/brand, membership-checked) and re-authorized by
     // resolveWs on every request, so it resolves identically here and over stdio without this transport naming it.
-    await mcpCtx.run({ token, remote: true }, () => entry.transport.handleRequest(req, res, req.body));
+    await mcpCtx.run({ token, remote: true, client: entry.client || '' }, () => entry.transport.handleRequest(req, res, req.body));
   });
 
   console.error(`[mcp-remote] mounted at ${BASE || '(set HEIST_PUBLIC_URL)'}/mcp`);