hermoso 0.1.43 → 0.1.57

package/README.md

@@ -5,9 +5,16 @@ scripts. Research the ads already winning in a market, generate finished image &
 composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad
 campaigns behind them — all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
 
-**262 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**316 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
 catalog with exact per-render credit costs plus the full capability map.
 
+**It is not all-or-nothing.** Research, creation, publishing/scheduling and ads management are four *independent*
+areas — no tool requires that you used another one first. Publish or schedule creative you already have and
+generate nothing here (`upload_file` turns any local or external file into a URL every publish, schedule and
+ad-build tool accepts); build and read campaigns on your own ad accounts with your own creative; research
+competitors with no brand drafted and no channel connected; or generate a file with nothing connected at all and
+just download it. Use the one piece you need, or all of it together.
+
 ## Instant: the hosted Claude.ai connector
 
 Paste **`https://app.hermoso.ai/mcp`** into Claude → Settings → Connectors → *Add custom connector*, approve with
@@ -46,7 +53,7 @@ Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-### What the 262 tools cover
+### What the 316 tools cover
 
 **Ad spy / research** — `find_competitors`, `competitor_teardown`, `pull_competitor_ads`, `research_ads`; the
 Meta / Google / LinkedIn ad libraries (`search_meta_ads`, `search_google_ads`, `search_linkedin_ads`); organic
@@ -78,8 +85,8 @@ publish). `schedule_post` / `list_scheduled` / `cancel_scheduled` give you one c
 *X posting bills credits per API call (X charges per request); a post containing a link costs 13× one without.*
 
 **Run the ads** — full campaign trees, built paused and read back before anything is reported, with every spend
-change confirm-gated, on **Meta**, **Google Ads**, **LinkedIn Ads**, **Pinterest Ads**, **Microsoft Advertising**
-and **ChatGPT Ads** (OpenAI's Advertiser API). Each has list + report + create + budget/status tools
+change confirm-gated, on **Meta**, **Google Ads**, **LinkedIn Ads**, **Reddit Ads**, **Pinterest Ads**,
+**Microsoft Advertising** and **ChatGPT Ads** (OpenAI's Advertiser API). Each has list + report + create + budget/status tools
 (e.g. `list_google_ads_campaigns`, `google_ads_report`, `create_google_ads_campaign`, `set_google_ads_budget`,
 `set_google_ads_status`). *X Ads are not supported — X posting only.*
 

package/mcp/client.mjs

@@ -32,6 +32,13 @@ export const OWNER = process.env.HERMOSO_OWNER || '';
 // hardcode either name when it tells a user which variables to set — it asks its own client.
 export const ENV_PREFIX = 'HERMOSO';
 
+// WHICH TOOL IS RUNNING. The error ledger groups on the OP, and a path alone cannot name the tool: `plan_ad`,
+// `render_ad` and `make_template_ad` all fail through POST /api/create, so without this every MCP defect would be
+// filed under one row called "POST /api/create" and be unfixable. wrap() sets it around each tool call; headers()
+// stamps it on every /api request that call makes, so route() records the tool NAME and nothing has to be reported
+// twice. Deliberately a per-call AsyncLocalStorage and not a module variable — concurrent tool calls interleave.
+export const toolCtx = new AsyncLocalStorage();
+
 function headers(extra = {}) {
   const ctx = mcpCtx.getStore();
   // A HOSTED-CONNECTOR request (mcp/http.mjs) is a DIFFERENT TENANT from the process serving it, so its ctx is the
@@ -41,7 +48,8 @@ function headers(extra = {}) {
   // same person. Presence of the ctx store IS "remote" (see isRemote below).
   const prof = ctx ? (ctx.profile || '') : PROFILE; // omitted when unpinned so the key's saved brand wins server-side
   const own = ctx ? (ctx.owner || '') : OWNER; // the wire name is x-hermoso-owner on BOTH twins — it is the server's header, not a brand
-  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...(own ? { 'x-hermoso-owner': own } : {}), ...extra };
+  const tool = toolCtx.getStore()?.tool || '';
+  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...(own ? { 'x-hermoso-owner': own } : {}), ...(tool ? { 'x-hermoso-tool': tool } : {}), ...extra };
   const tok = ctx?.token || TOKEN;
   if (tok) h.Authorization = `Bearer ${tok}`;
   return h;
@@ -53,11 +61,37 @@ async function unwrap(res) {
   try { body = await res.json(); } catch {}
   if (!res.ok) {
     const msg = (body && (body.error || body.message)) || `HTTP ${res.status}`;
-    throw Object.assign(new Error(msg), { status: res.status });
+    // `_viaApi` MARKS AN ERROR THAT ALREADY REACHED THE SERVER, so route() has already recorded it in the error
+    // ledger with the tool name off x-hermoso-tool. wrap() reports ONLY the errors that lack this marker — a local
+    // throw, a schema rejection, a socket reset — which is what stops the twins double-counting every 4xx.
+    throw Object.assign(new Error(msg), { status: res.status, _viaApi: true, ...(body?.connector ? { connector: body.connector } : {}) });
   }
   return body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body;
 }
 
+/**
+ * Report an error that never reached our API. Fire-and-forget, bounded, and it can NEVER throw or recurse: it uses
+ * plain fetch (not apiPost, whose own failure would report itself forever) and swallows everything.
+ */
+let _reportedThisProcess = 0;
+export function reportToolError(tool, err) {
+  try {
+    if (_reportedThisProcess++ > 200) return; // a client stuck in a retry loop must not become the traffic
+    const e = err && typeof err === 'object' ? err : {};
+    fetch(`${API_BASE}/api/errors/report`, {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify({
+        op: String(tool || 'unknown').slice(0, 60),
+        errorClass: String(e.name || 'Error').slice(0, 40),
+        status: Number(e.status) || 0,
+        message: String(e.message || e).slice(0, 300),
+        ...(e.connector ? { connector: String(e.connector).slice(0, 32) } : {}),
+      }),
+    }).catch(() => {});
+  } catch { /* an instrument never breaks the thing it measures */ }
+}
+
 export async function apiGet(p, query) {
   // URLSearchParams stringifies undefined/null as the LITERAL "undefined"/"null" — so an omitted optional param
   // arrives as a truthy string and silently changes server behaviour. Live 2026-07-27: list_google_ads_campaigns

package/mcp/hermoso-mcp.mjs

@@ -8,7 +8,7 @@
 // stdout is the JSON-RPC channel — NEVER print to it. All logging goes to stderr (console.error).
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { registerTools, MCP_INSTRUCTIONS } from './tools.mjs';
+import { registerTools, MCP_INSTRUCTIONS, parseToolScope } from './tools.mjs';
 import { API_BASE } from './client.mjs';
 
 // instructions = the full capability map (ad spy · create · raw model playground · account) — one source of truth
@@ -17,7 +17,13 @@ const server = new McpServer({ name: 'hermoso-mcp', version: '1.0.0' }, {
   instructions: MCP_INSTRUCTIONS,
 });
 
-registerTools(server);
+// Optional roster scoping, same groups as the hosted connector's ?tools= (see registerTools). A client that
+// loads every tool definition eagerly spends ~154k tokens on the full roster; HERMOSO_TOOLS=channels,ads narrows it.
+// An unknown group EXITS rather than silently serving all of them — a scoped connection you did not get is
+// worse than one you were told you could not have.
+const _scope = parseToolScope(process.env.HERMOSO_TOOLS);
+if (_scope.error) { console.error(`[hermoso-mcp] ${_scope.error}`); process.exit(1); }
+registerTools(server, { only: _scope.groups });
 
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/mcp/http.mjs

@@ -16,7 +16,7 @@
 import { randomUUID } from 'node:crypto';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { registerTools, MCP_INSTRUCTIONS } from './tools.mjs';
+import { registerTools, MCP_INSTRUCTIONS, parseToolScope } from './tools.mjs';
 import { mcpCtx } from './client.mjs';
 
 // Mount the remote connector onto the Express app. No-op unless explicitly enabled + auth-backed.
@@ -107,9 +107,19 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
     const methods = arr.map((m) => m && m.method).filter((v) => typeof v === 'string');
     return methods.length > 0 && methods.every((m) => PREAUTH_METHODS.has(m)); // a batch mixing in tools/call is NOT pre-auth
   };
-  async function serveAnonDiscovery(req, res) {
+  // `?tools=research,create` narrows the roster this connection advertises (see registerTools). Read here rather
+  // than inside registerTools so BOTH the anonymous discovery handshake and a real session honour the same query,
+  // and so an unknown group is refused at the door with the valid list instead of silently serving all 301.
+  // The scope is fixed at initialize and stored on the session: tools/list must not change under a live client.
+  function scopeFor(req, res) {
+    const { groups, error } = parseToolScope(req.query?.tools ?? req.headers['x-hermoso-tools']);
+    if (error) { res.status(400).json({ jsonrpc: '2.0', error: { code: -32602, message: error }, id: null }); return false; }
+    return { groups };
+  }
+
+  async function serveAnonDiscovery(req, res, scope) {
     const server = new McpServer({ name: 'hermoso', version: '1.0.0' }, { instructions: MCP_INSTRUCTIONS });
-    registerTools(server); // metadata only — tools/list never invokes a handler, and tools/call can't reach here
+    registerTools(server, { only: scope?.groups }); // 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);
@@ -122,7 +132,11 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
     const user = token ? await verifyBearer(token).catch(() => null) : null;
     if (!user) {
       // No valid bearer: allow ONLY the read-only discovery handshake (POST), fail CLOSED for everything else.
-      if (req.method === 'POST' && isAllPreauth(req.body)) return serveAnonDiscovery(req, res).catch(() => { try { challenge(res); } catch {} });
+      if (req.method === 'POST' && isAllPreauth(req.body)) {
+        const scope = scopeFor(req, res);
+        if (scope === false) return; // unknown group — already answered 400
+        return serveAnonDiscovery(req, res, scope).catch(() => { try { challenge(res); } catch {} });
+      }
       return challenge(res);
     }
 
@@ -140,9 +154,11 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
       // Only an `initialize` may mint a session. Anything else naming no session at all is the SDK's own 400 —
       // answered here so we never pay 36 MB to build a server whose only job would be to reject the request.
       if (!init) return needSession(res);
+      const scope = scopeFor(req, res);
+      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); // the SAME tools as stdio — but here every /api call they make carries this user's token
+      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
       const transport = new StreamableHTTPServerTransport({
         // CSPRNG, per the spec's SHOULD for session ids (Math.random() is not one).
         sessionIdGenerator: () => 'sess_' + randomUUID().replace(/-/g, ''),