@leadbay/mcp 0.35.1 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog — @leadbay/mcp
 
+## 0.36.0 — 2026-09-08
+
+The OpenAI submission form flags every tool without an `outputSchema`
+("Recommended: Add an outputSchema so models can better understand this tool's
+results"). 43 of the 58 tools on `/chatgpt/mcp` already had one. This adds four
+of the remaining 15:
+
+- `leadbay_account_history`, `leadbay_team_activity` — rich nested payloads the
+  model previously had to infer from prose.
+- `leadbay_getting_started`, `leadbay_artifact_kit` — static manifests; cheap to
+  declare, and both are consumed programmatically.
+
+Each gets a real entry in `output-schema-conformance.test.ts` CASES, not an
+OPT_OUT: a mocked happy-path round-trip whose structuredContent is asserted
+against the schema. Mutation-checked — renaming `trend` in the team_activity
+schema fails with `$.trend: return contains key not declared in
+outputSchema.properties (drift)`.
+
+A local Codex review of this branch found three real defects in the first pass,
+all fixed here:
+
+- `account_history` declared `signals` as an object. `research_lead_by_id`,
+  whose payload it passes straight through, declares it an **array**. The
+  conformance walk checks required keys and undeclared keys, not types, so it
+  did not catch this.
+- The `account_history` conformance case under-mocked the fan-out. It never
+  mocked `/leads/{id}/contacts?IncludeEnriched=true`, and gave one generic
+  `/activities` script for the two reads that happen (research's `count=20`,
+  then the tool's own `count=<n>`). The harness consumes a script once, so the
+  second read rejected, `.catch()`ed to empty, and the case asserted a degraded
+  timeline while staying schema-conformant. Proven: with the old mocks the new
+  `account-history-full-fanout.test.ts` fails `expected [] to have a length of
+  1`.
+- `artifact_kit`'s schema omitted `_meta`. `buildServer` injects
+  `_meta.update_available` / `_meta.notifications` into successful object
+  results before setting `structuredContent`, so it is a real top-level key at
+  runtime. The other three declared it.
+
+Two deliberate limits:
+
+- **`leadbay_list_sectors` is excluded.** It returns a bare array, and
+  `server.ts` only emits `structuredContent` for plain objects, so a schema
+  there would promise a payload the server never sends. Making it honest means
+  changing the return to an object, which breaks existing callers.
+- On `account_history`, the blobs passed through verbatim from
+  `research_lead_by_id` (`signals`, `firmographics`, `contacts`, `engagement`)
+  are declared as bare objects with no `properties`. The conformance walk only
+  recurses into declared object-properties that carry their own `properties`,
+  so research can grow a field without breaking this tool.
+
+The remaining 10 tools without a schema are write acknowledgements
+(`pin_contact`, `like_lead`, `set_telemetry`, …). A schema for `{ok:true}`
+teaches the model nothing; left alone on purpose.
+
+## 0.35.2 — 2026-09-08
+
+A backend `bad_request` 400 is now `BAD_INPUT` (product#4085).
+
+**What happened.** On 8 Sep an unattended routine on the hosted server called
+`leadbay_research_lead_by_id` twenty times in 39 seconds with the first block
+of each lead UUID (`/lenses/48110/leads/5585c198`, …). The backend rejected
+every call in ~30 ms with `400 {"error":{"code":"bad_request","message":"bad
+'leadId' parameter"}}`. `client.ts` `mapErrorResponse` filed that under the
+`API_ERROR` catch-all, whose hint reads "Try again or check the Leadbay API
+status". The agent did what it was told. The same pattern ran on 31 Aug.
+
+**Change.** A 400 whose body carries the backend's `bad_request` code (a path
+or query parameter that failed to parse, a body that failed to deserialize) is
+`BAD_INPUT`, with the backend message verbatim and a hint that the call fails
+identically on retry and that ids are the full values Leadbay returned. Other
+400 codes (`duplicate`, `unpaid_invoice`, `not_allowed`, …) are domain answers
+and stay `API_ERROR`. `leadbay_research_lead_by_id`'s `leadId` schema
+description now says the id is the full 36-character UUID from
+`leadbay_pull_leads` `items[].id`, never shortened. No template change.
+
 ## 0.35.1 — 2026-09-08
 
 Release-pipeline only. No source change, no behaviour change: `packages/core`

package/dist/bin.js

@@ -661,6 +661,9 @@ var init_client = __esm({
         if (status === 404) {
           return this.makeError("NOT_FOUND", parsed?.message || parsed?.error?.message || "Resource not found", "Verify the ID is correct", endpoint, null, status);
         }
+        if (status === 400 && parsed?.error?.code === "bad_request") {
+          return this.makeError("BAD_INPUT", parsed?.error?.message || parsed?.message || "Leadbay rejected the request as malformed", "Leadbay's input validation rejected this call, so the same call will fail the same way \u2014 do not retry it unchanged. Fix the parameter named in the message first; if it is an id, pass it exactly as Leadbay returned it, never shortened or reconstructed.", endpoint, null, status);
+        }
         return this.makeError("API_ERROR", parsed?.message || parsed?.error?.message || `API error (${status})`, "Try again or check the Leadbay API status", endpoint, null, status);
       }
       // /me cache (60s TTL). Separate from resolveOrgId() which still works for
@@ -14817,7 +14820,10 @@ var init_research_lead_by_id = __esm({
       inputSchema: {
         type: "object",
         properties: {
-          leadId: { type: "string", description: "Lead UUID (required)" },
+          leadId: {
+            type: "string",
+            description: "Full 36-character lead UUID exactly as returned in leadbay_pull_leads items[].id (never shortened)"
+          },
           lensId: {
             type: "number",
             description: "Lens id (escape hatch \u2014 normally omit; auto-resolves to the active lens)"
@@ -15734,6 +15740,32 @@ var init_getting_started = __esm({
         openWorldHint: false
       },
       description: leadbay_getting_started,
+      outputSchema: {
+        type: "object",
+        properties: {
+          version: { type: "number", description: "Manifest version; bump means the script changed." },
+          intro: { type: "string", description: "What to say before gate 1." },
+          one_option_rule: {
+            type: "string",
+            description: "The invariant every gate obeys: one way forward plus one way out, never three."
+          },
+          docs_url: { type: "string", description: "The canonical setup guide." },
+          docs_note: { type: "string", description: "The only two moments that link may appear." },
+          calendly_url: { type: "string", description: "1:1 setup session, offered on exit only." },
+          exit_offer: { type: "string", description: "How and when to make that offer." },
+          steps: {
+            type: "array",
+            description: "The gates, in order. Each carries n, gate_label, gate_description, explain, next_steps (the widget payload), calls, args, and optional forbidden_args / spend / quota_note / pin / branches. Render next_steps VERBATIM."
+          },
+          keep_going: {
+            type: "array",
+            description: "The hand-off cards: what the user should TYPE to get each thing back once the buttons are gone. Every phrase is lifted from a tool's own routing triggers."
+          },
+          stop: { type: "string", description: "How to close the tour." },
+          _meta: { type: "object", description: "Server-injected notices, when present." }
+        },
+        required: ["version", "intro", "steps", "keep_going", "stop"]
+      },
       write: false,
       inputSchema: {
         type: "object",
@@ -16012,6 +16044,63 @@ var init_account_history = __esm({
         openWorldHint: true
       },
       description: leadbay_account_history,
+      outputSchema: {
+        type: "object",
+        properties: {
+          lead: {
+            type: "object",
+            description: "Which account this history is about.",
+            properties: {
+              id: { type: "string" },
+              name: { type: ["string", "null"] }
+            },
+            required: ["id"]
+          },
+          signals: {
+            // An ARRAY of priority-ordered sections, matching what
+            // research_lead_by_id's own outputSchema declares — this is its payload
+            // passed straight through. Null when the research call has no web-fetch
+            // content to reshape.
+            type: ["array", "null"],
+            description: "Live signals, verbatim from leadbay_research_lead_by_id \u2014 why this account is hot NOW."
+          },
+          firmographics: { type: ["object", "null"], description: "Company facts, verbatim from research." },
+          qualification: { type: "array", description: "Per-question qualification answers, verbatim from research." },
+          contacts: { type: ["object", "null"], description: "Reachable contacts + candidates, verbatim from research." },
+          engagement: { type: ["object", "null"], description: "Engagement counters, verbatim from research." },
+          notes: {
+            type: "array",
+            description: "FULL note bodies \u2014 the part research only counts. Oldest first."
+          },
+          activities: {
+            type: "object",
+            description: "The interaction timeline research only summarizes.",
+            properties: {
+              activities: {
+                type: "array",
+                description: "One entry per logged interaction.",
+                items: {
+                  type: "object",
+                  properties: {
+                    type: { type: "string" },
+                    date: { type: "string" }
+                  }
+                }
+              },
+              total: {
+                type: "number",
+                description: "Total on the server, which can exceed the number returned."
+              }
+            },
+            required: ["activities", "total"]
+          },
+          _meta: {
+            type: "object",
+            description: "Research's pass-through metadata (lens_id, web_fetch_in_progress, has_reachable_contact, \u2026) plus region and this call's counts."
+          }
+        },
+        required: ["lead", "notes", "activities"]
+      },
       inputSchema: {
         type: "object",
         properties: {
@@ -21356,6 +21445,62 @@ var init_team_activity = __esm({
         openWorldHint: true
       },
       description: leadbay_team_activity,
+      outputSchema: {
+        type: "object",
+        properties: {
+          range: {
+            type: "object",
+            description: "The window actually queried, after `weeks` was resolved to dates.",
+            properties: {
+              from: { type: "string", description: "ISO date (YYYY-MM-DD), inclusive." },
+              to: { type: "string", description: "ISO date (YYYY-MM-DD), inclusive." },
+              periodicity: { type: "string", description: "DAILY or WEEKLY \u2014 the trend bucket size." }
+            },
+            required: ["from", "to", "periodicity"]
+          },
+          reps: {
+            type: "array",
+            description: "One row per rep, already renamed from the backend's KPI vocabulary. Non-admins get only themselves; the backend does that scoping.",
+            items: {
+              type: "object",
+              properties: {
+                user_id: { type: "string" },
+                name: { type: ["string", "null"] },
+                email: { type: ["string", "null"] },
+                total_activities: { type: "number" },
+                likes: { type: "number" },
+                saves: { type: "number" },
+                website_clicks: { type: "number" },
+                exported: { type: "number" },
+                profile_views: { type: "number" },
+                contacts_added: { type: "number" },
+                contacts_purchased: { type: "number" },
+                notes: { type: "number" },
+                meetings_or_interest: {
+                  type: "number",
+                  description: "Epilogue outcomes logged in the window \u2014 the 'deals' signal."
+                },
+                could_not_reach: { type: "number" },
+                lost: { type: "number" },
+                still_chasing: { type: "number" }
+              }
+            }
+          },
+          trend: {
+            type: "array",
+            description: "Activity over time, one point per period.",
+            items: {
+              type: "object",
+              properties: {
+                date: { type: "string" },
+                count: { type: "number" }
+              }
+            }
+          },
+          _meta: { type: "object", description: "Region + any server-injected notices." }
+        },
+        required: ["range", "reps", "trend"]
+      },
       write: false,
       inputSchema: {
         type: "object",
@@ -21506,6 +21651,19 @@ var init_artifact_kit = __esm({
         openWorldHint: false
       },
       description: leadbay_artifact_kit,
+      outputSchema: {
+        type: "object",
+        properties: {
+          version: { type: "string", description: "Kit version; bump means the runtime changed." },
+          runtime: { type: "string", description: "The self-contained JS the artifact inlines." },
+          usage_guide: { type: "string", description: "Markdown guide for building the artifact." },
+          // buildServer injects _meta.update_available / _meta.notifications into
+          // successful object results before emitting structuredContent, so it is a
+          // real top-level key at runtime even though execute() never writes it.
+          _meta: { type: "object", description: "Server-injected notices, when present." }
+        },
+        required: ["version", "runtime", "usage_guide"]
+      },
       write: false,
       inputSchema: {
         type: "object",
@@ -28045,7 +28203,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.35.1";
+var VERSION = "0.36.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -3649,6 +3649,9 @@ var LeadbayClient = class _LeadbayClient {
     if (status === 404) {
       return this.makeError("NOT_FOUND", parsed?.message || parsed?.error?.message || "Resource not found", "Verify the ID is correct", endpoint, null, status);
     }
+    if (status === 400 && parsed?.error?.code === "bad_request") {
+      return this.makeError("BAD_INPUT", parsed?.error?.message || parsed?.message || "Leadbay rejected the request as malformed", "Leadbay's input validation rejected this call, so the same call will fail the same way \u2014 do not retry it unchanged. Fix the parameter named in the message first; if it is an id, pass it exactly as Leadbay returned it, never shortened or reconstructed.", endpoint, null, status);
+    }
     return this.makeError("API_ERROR", parsed?.message || parsed?.error?.message || `API error (${status})`, "Try again or check the Leadbay API status", endpoint, null, status);
   }
   // /me cache (60s TTL). Separate from resolveOrgId() which still works for
@@ -16962,7 +16965,10 @@ var researchLeadById = {
   inputSchema: {
     type: "object",
     properties: {
-      leadId: { type: "string", description: "Lead UUID (required)" },
+      leadId: {
+        type: "string",
+        description: "Full 36-character lead UUID exactly as returned in leadbay_pull_leads items[].id (never shortened)"
+      },
       lensId: {
         type: "number",
         description: "Lens id (escape hatch \u2014 normally omit; auto-resolves to the active lens)"
@@ -17856,6 +17862,32 @@ var gettingStarted = {
     openWorldHint: false
   },
   description: leadbay_getting_started2,
+  outputSchema: {
+    type: "object",
+    properties: {
+      version: { type: "number", description: "Manifest version; bump means the script changed." },
+      intro: { type: "string", description: "What to say before gate 1." },
+      one_option_rule: {
+        type: "string",
+        description: "The invariant every gate obeys: one way forward plus one way out, never three."
+      },
+      docs_url: { type: "string", description: "The canonical setup guide." },
+      docs_note: { type: "string", description: "The only two moments that link may appear." },
+      calendly_url: { type: "string", description: "1:1 setup session, offered on exit only." },
+      exit_offer: { type: "string", description: "How and when to make that offer." },
+      steps: {
+        type: "array",
+        description: "The gates, in order. Each carries n, gate_label, gate_description, explain, next_steps (the widget payload), calls, args, and optional forbidden_args / spend / quota_note / pin / branches. Render next_steps VERBATIM."
+      },
+      keep_going: {
+        type: "array",
+        description: "The hand-off cards: what the user should TYPE to get each thing back once the buttons are gone. Every phrase is lifted from a tool's own routing triggers."
+      },
+      stop: { type: "string", description: "How to close the tour." },
+      _meta: { type: "object", description: "Server-injected notices, when present." }
+    },
+    required: ["version", "intro", "steps", "keep_going", "stop"]
+  },
   write: false,
   inputSchema: {
     type: "object",
@@ -18112,6 +18144,63 @@ var accountHistory = {
     openWorldHint: true
   },
   description: leadbay_account_history,
+  outputSchema: {
+    type: "object",
+    properties: {
+      lead: {
+        type: "object",
+        description: "Which account this history is about.",
+        properties: {
+          id: { type: "string" },
+          name: { type: ["string", "null"] }
+        },
+        required: ["id"]
+      },
+      signals: {
+        // An ARRAY of priority-ordered sections, matching what
+        // research_lead_by_id's own outputSchema declares — this is its payload
+        // passed straight through. Null when the research call has no web-fetch
+        // content to reshape.
+        type: ["array", "null"],
+        description: "Live signals, verbatim from leadbay_research_lead_by_id \u2014 why this account is hot NOW."
+      },
+      firmographics: { type: ["object", "null"], description: "Company facts, verbatim from research." },
+      qualification: { type: "array", description: "Per-question qualification answers, verbatim from research." },
+      contacts: { type: ["object", "null"], description: "Reachable contacts + candidates, verbatim from research." },
+      engagement: { type: ["object", "null"], description: "Engagement counters, verbatim from research." },
+      notes: {
+        type: "array",
+        description: "FULL note bodies \u2014 the part research only counts. Oldest first."
+      },
+      activities: {
+        type: "object",
+        description: "The interaction timeline research only summarizes.",
+        properties: {
+          activities: {
+            type: "array",
+            description: "One entry per logged interaction.",
+            items: {
+              type: "object",
+              properties: {
+                type: { type: "string" },
+                date: { type: "string" }
+              }
+            }
+          },
+          total: {
+            type: "number",
+            description: "Total on the server, which can exceed the number returned."
+          }
+        },
+        required: ["activities", "total"]
+      },
+      _meta: {
+        type: "object",
+        description: "Research's pass-through metadata (lens_id, web_fetch_in_progress, has_reachable_contact, \u2026) plus region and this call's counts."
+      }
+    },
+    required: ["lead", "notes", "activities"]
+  },
   inputSchema: {
     type: "object",
     properties: {
@@ -23282,6 +23371,62 @@ var teamActivity = {
     openWorldHint: true
   },
   description: leadbay_team_activity,
+  outputSchema: {
+    type: "object",
+    properties: {
+      range: {
+        type: "object",
+        description: "The window actually queried, after `weeks` was resolved to dates.",
+        properties: {
+          from: { type: "string", description: "ISO date (YYYY-MM-DD), inclusive." },
+          to: { type: "string", description: "ISO date (YYYY-MM-DD), inclusive." },
+          periodicity: { type: "string", description: "DAILY or WEEKLY \u2014 the trend bucket size." }
+        },
+        required: ["from", "to", "periodicity"]
+      },
+      reps: {
+        type: "array",
+        description: "One row per rep, already renamed from the backend's KPI vocabulary. Non-admins get only themselves; the backend does that scoping.",
+        items: {
+          type: "object",
+          properties: {
+            user_id: { type: "string" },
+            name: { type: ["string", "null"] },
+            email: { type: ["string", "null"] },
+            total_activities: { type: "number" },
+            likes: { type: "number" },
+            saves: { type: "number" },
+            website_clicks: { type: "number" },
+            exported: { type: "number" },
+            profile_views: { type: "number" },
+            contacts_added: { type: "number" },
+            contacts_purchased: { type: "number" },
+            notes: { type: "number" },
+            meetings_or_interest: {
+              type: "number",
+              description: "Epilogue outcomes logged in the window \u2014 the 'deals' signal."
+            },
+            could_not_reach: { type: "number" },
+            lost: { type: "number" },
+            still_chasing: { type: "number" }
+          }
+        }
+      },
+      trend: {
+        type: "array",
+        description: "Activity over time, one point per period.",
+        items: {
+          type: "object",
+          properties: {
+            date: { type: "string" },
+            count: { type: "number" }
+          }
+        }
+      },
+      _meta: { type: "object", description: "Region + any server-injected notices." }
+    },
+    required: ["range", "reps", "trend"]
+  },
   write: false,
   inputSchema: {
     type: "object",
@@ -23411,6 +23556,19 @@ var artifactKit = {
     openWorldHint: false
   },
   description: leadbay_artifact_kit,
+  outputSchema: {
+    type: "object",
+    properties: {
+      version: { type: "string", description: "Kit version; bump means the runtime changed." },
+      runtime: { type: "string", description: "The self-contained JS the artifact inlines." },
+      usage_guide: { type: "string", description: "Markdown guide for building the artifact." },
+      // buildServer injects _meta.update_available / _meta.notifications into
+      // successful object results before emitting structuredContent, so it is a
+      // real top-level key at runtime even though execute() never writes it.
+      _meta: { type: "object", description: "Server-injected notices, when present." }
+    },
+    required: ["version", "runtime", "usage_guide"]
+  },
   write: false,
   inputSchema: {
     type: "object",
@@ -25410,7 +25568,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.35.1" : "0.0.0-dev";
+var VERSION = true ? "0.36.0" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var logger = {

package/dist/installer-electron.js

@@ -1805,7 +1805,7 @@ var init_installer_gui = __esm({
     init_install_dxt();
     init_install_shared();
     init_oauth();
-    VERSION = true ? "0.35.1" : "0.0.0-dev";
+    VERSION = true ? "0.36.0" : "0.0.0-dev";
     MESSAGES = {
       en: {
         installer: {

package/dist/installer-gui.js

@@ -1068,7 +1068,7 @@ async function oauthLogin(opts) {
 }
 
 // installer/installer-gui.ts
-var VERSION = true ? "0.35.1" : "0.0.0-dev";
+var VERSION = true ? "0.36.0" : "0.0.0-dev";
 var MESSAGES = {
   en: {
     installer: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",