fix(mcp,core): #3504 silent npx exit, dead URL hints, misleading score contracts (#15)

Three failure modes a user hits before they get any work done, fixed in one pass.

1. #3504 — `npx -y @leadbay/mcp` silently exits 0 on Node 25. The `isEntrypoint`
   check compared `process.argv[1]` (the npx shim symlink) to `import.meta.url`
   (the resolved `dist/bin.js`); they never match, so `main()` never runs and
   the MCP host sees a dead connection with no diagnostic. Both sides now go
   through `realpathSync` so the symlink collapses. Reproduce-then-fix verified
   with a new `test/smoke/npx-entrypoint.test.ts` regression guard.

2. Dead `app.leadbay.ai` URLs in error strings and READMEs replaced with the
   real recovery commands (`leadbay-mcp install`, `leadbay-mcp login`). Hints
   now include `--region <us|fr>` because the CLI refuses without it (anti-
   cross-region credential-leak guard) — earlier draft would have dead-ended
   the user a second time.

3. `avg_score_0_to_10` on `pull_leads` / `bulk_qualify_leads` was lying: per-
   question AI agent scores are discrete boosts (-10/0/10/20), not 0-10
   averages. Renamed to `avg_qualification_boost` with JSDoc on the underlying
   `AiAgentResponse.score` interface explaining the real contract. Documented
   `score` (ICP similarity) vs `ai_agent_lead_score` (deep-AI qualification
   boost) — they're combined and normalized server-side to 0-100.

Live smoke harness extended with composite-level checks + optional thinking-
model judge that writes a redacted report to `.context/`. Token-first via
`LEADBAY_TEST_TOKEN`; macOS Keychain fallback (refuses plaintext password env
var, on purpose). Versions: core 0.2.0→0.2.1 (private), leadclaw + mcp
0.2.1→0.2.2 (openclaw plugin manifest synced).

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: milstan

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "description": "Leadbay shared core: HTTP client and protocol-agnostic tool definitions. Consumed by @leadbay/leadclaw and @leadbay/mcp.",
   "type": "module",

packages/core/src/client.ts

@@ -352,7 +352,7 @@ export class LeadbayClient {
       throw this.makeError(
         "NOT_AUTHENTICATED",
         "Not logged in to Leadbay",
-        "Set LEADBAY_TOKEN env var (obtain token at https://app.leadbay.ai/settings/api-tokens), or use the OpenClaw leadbay_login tool",
+        "Set LEADBAY_TOKEN in your MCP client config, or run: npx -y @leadbay/mcp install --email <you> --region <us|fr>",
         path
       );
     }
@@ -403,7 +403,7 @@ export class LeadbayClient {
       throw this.makeError(
         "NOT_AUTHENTICATED",
         "Not logged in to Leadbay",
-        "Set LEADBAY_TOKEN env var (obtain token at https://app.leadbay.ai/settings/api-tokens), or use the OpenClaw leadbay_login tool",
+        "Set LEADBAY_TOKEN in your MCP client config, or run: npx -y @leadbay/mcp install --email <you> --region <us|fr>",
         path
       );
     }
@@ -487,7 +487,7 @@ export class LeadbayClient {
       return this.makeError(
         "AUTH_EXPIRED",
         "Authentication token expired or invalid",
-        "Your LEADBAY_TOKEN is no longer valid. Regenerate at https://app.leadbay.ai/settings/api-tokens and restart.",
+        "Your LEADBAY_TOKEN is no longer valid. Regenerate it: npx -y @leadbay/mcp login --email <you> --region <us|fr>, then restart your MCP client.",
         endpoint
       );
     }
@@ -519,14 +519,14 @@ export class LeadbayClient {
         return this.makeError(
           "BILLING_SUSPENDED",
           "Account billing is suspended",
-          "Your Leadbay account billing is suspended. Update at https://app.leadbay.ai",
+          "Your Leadbay account billing is suspended. Contact Leadbay support.",
           endpoint
         );
       }
       return this.makeError(
         "FORBIDDEN",
         "Insufficient permissions",
-        "Your token does not have access to this resource. Check account permissions at https://app.leadbay.ai",
+        "Your token does not have access to this resource. Contact Leadbay support to verify account permissions.",
         endpoint
       );
     }

packages/core/src/composite/bulk-qualify-leads.ts

@@ -26,7 +26,11 @@ interface QualResult {
   qualification_summary: {
     answered: number;
     total: number;
-    avg_score_0_to_10: number | null;
+    /**
+     * Average of per-question AI agent boost scores (each -10/0/10/20).
+     * NOT a 0-10 average. Negative = net negative signal across questions.
+     */
+    avg_qualification_boost: number | null;
   } | null;
   signals_count: number | null;
 }
@@ -220,7 +224,7 @@ export const bulkQualifyLeads: Tool<BulkQualifyLeadsParams> = {
               ? {
                   answered: responses.filter((r) => r.score != null).length,
                   total: responses.length,
-                  avg_score_0_to_10: avg,
+                  avg_qualification_boost: avg,
                 }
               : null,
           signals_count: lastWf?.content

packages/core/src/composite/pull-leads.ts

@@ -17,7 +17,11 @@ interface PullLeadsParams {
 interface QualificationSummary {
   answered: number;
   total: number;
-  avg_score_0_to_10: number | null;
+  /**
+   * Average of per-question AI agent boost scores (each -10/0/10/20).
+   * NOT a 0-10 average. Negative = net negative signal across questions.
+   */
+  avg_qualification_boost: number | null;
   best_response_excerpt: string | null;
 }
 
@@ -44,7 +48,7 @@ function summarise(responses: AiAgentResponse[]): QualificationSummary {
     excerpt = excerpt.slice(0, 197) + "...";
   }
 
-  return { answered, total, avg_score_0_to_10: avg, best_response_excerpt: excerpt };
+  return { answered, total, avg_qualification_boost: avg, best_response_excerpt: excerpt };
 }
 
 export const pullLeads: Tool<PullLeadsParams> = {
@@ -114,7 +118,7 @@ export const pullLeads: Tool<PullLeadsParams> = {
             summary: {
               answered: 0,
               total: 0,
-              avg_score_0_to_10: null,
+              avg_qualification_boost: null,
               best_response_excerpt: null,
             },
           };

packages/core/src/tools/enrich-contacts.ts

@@ -60,7 +60,7 @@ export const enrichContacts: Tool<EnrichContactsParams> = {
         throw client.makeError(
           "QUOTA_EXCEEDED",
           "No enrichment credits remaining",
-          "Purchase more credits at app.leadbay.ai"
+          "Contact Leadbay support to extend your credit quota"
         );
       }
     } catch (e: any) {

packages/core/src/tools/get-taste-profile.ts

@@ -41,7 +41,7 @@ export const getTasteProfile: Tool<Record<string, never>> = {
       })),
       ...(isEmpty
         ? {
-            hint: "No taste profile configured yet. Set it up at app.leadbay.ai for better lead matching.",
+            hint: "No taste profile configured yet. Use leadbay_refine_prompt or contact Leadbay support to set one up for better lead matching.",
           }
         : {}),
     };

packages/core/src/types.ts

@@ -85,7 +85,17 @@ export interface SocialPresence {
 export interface LeadPayload {
   id: string;
   name: string;
+  /**
+   * Similarity score: how closely this lead matches the user's ideal-customer
+   * profile (the active lens). Combined with `ai_agent_lead_score` and
+   * normalized server-side to a 0-100 scale before display.
+   */
   score: number | null;
+  /**
+   * Deep AI qualification adjustment, computed after running web searches and
+   * lead intelligence lookups. Acts as a boost/penalty on top of `score`;
+   * the two are combined and normalized server-side to a 0-100 scale.
+   */
   ai_agent_lead_score: number | null;
   location: LocationPayload | null;
   description: string | null;
@@ -133,11 +143,16 @@ export interface WishlistResponse {
 }
 
 // AI-rescore answers — the highest-signal payload Leadbay produces per lead.
-// Score is 0-10 PER QUESTION (different from the 0-100 lead-level scores).
+// Per-question qualification boost from the AI agent. Discrete values:
+// -10 (negative signal), 0 (neutral / no signal), 10 (positive signal),
+// 20 (strong positive signal). These boosts are summed and combined with
+// the lead's similarity `score`, then normalized server-side to the 0-100
+// lead-level scale before display. NOT a 0-10 scale despite legacy naming.
 export interface AiAgentResponse {
   question: string;
   question_created_at: string;
   lead_id: string;
+  /** Discrete boost: -10, 0, 10, or 20. See interface comment above. */
   score: number | null;
   response: string | null;
   computed_at: string | null;

packages/leadclaw/CHANGELOG.md

@@ -2,11 +2,14 @@
 
 ## 0.2.2 — 2026-04-21
 
-Docs-only release. Shares the `@leadbay/mcp@0.2.2` mental-model copy updates since both packages consume the same `@leadbay/core` tool descriptions.
+Bug fix + contract correction + mental-model docs release. Picks up `@leadbay/core@0.2.1` underneath.
 
+- Renamed misleading `avg_score_0_to_10` field on the `pull_leads` / `bulk_qualify_leads` qualification summaries to `avg_qualification_boost`. Per-question AI agent scores are discrete boosts (-10/0/10/20), not a 0-10 average — interface JSDoc now reflects the real contract.
+- Replaced stale `app.leadbay.ai` URLs in client-side error strings with runnable recovery commands. Recovery hints now include `--region <us|fr>` because the CLI refuses without it (anti-cross-region credential-leak guard).
+- README: stale `app.leadbay.ai` references swept.
 - Plugin manifest description rewritten from "Leadbay lead discovery, qualification, and contact enrichment for AI agents" to a framing that names the inbox model, the two scoring layers, and on-demand deepening.
 - Composite tool descriptions (`pull_leads`, `research_lead`, `bulk_qualify_leads`, `enrich_titles`, `account_status`) now teach the agent that Leadbay delivers a fresh batch per user login, paced by recent consumption; that roughly the top 10 are pre-AI-qualified while the rest are resource-saved (not worse); and that contacts are enriched on demand when the agent is ready to reach out.
-- No new tools, no schema changes. Version kept in sync with `@leadbay/mcp@0.2.2`.
+- Version kept in sync with `@leadbay/mcp@0.2.2`.
 
 ## 0.2.1 — 2026-04-21
 

packages/leadclaw/README.md

@@ -78,8 +78,8 @@ The canonical tool list + schemas live in [`openclaw.plugin.json`](./openclaw.pl
 | Problem | Cause | Fix |
 |---------|-------|-----|
 | Plugin loads but agent sees no Leadbay tools | `token` missing and no login step taken | Have the agent call `leadbay_login`, or pre-set `token` in the plugin config |
-| `Authentication token expired or invalid` | Token revoked or wrong region | Mint a new token at [app.leadbay.ai](https://app.leadbay.ai); verify `region` matches your account |
-| `No enrichment credits remaining` | Out of quota | Buy credits at [app.leadbay.ai](https://app.leadbay.ai) |
+| `Authentication token expired or invalid` | Token revoked or wrong region | Have the agent call `leadbay_login` to mint a fresh token; verify `region` matches your account |
+| `No enrichment credits remaining` | Out of quota | Contact Leadbay support to extend quota |
 | Agent keeps picking granular tools over composites | `exposeGranular: true` set | Flip to `false`; the composites are usually what you want |
 | Write tool "not found" | `exposeWrite: false` (default) | Set `exposeWrite: true` after explicitly opting in |
 

packages/mcp/CHANGELOG.md

@@ -2,12 +2,15 @@
 
 ## 0.2.2 — 2026-04-21
 
-Docs-only release. Teach the agent the Leadbay mental model — agents were calling `pull_leads` like a generic query rather than as a daily inbox, missing that leads past the top ~10 still exist and can be deepened on demand.
+Bug fix + contract correction + mental-model docs release.
 
+- **Fix [product#3504](https://github.com/leadbay/product/issues/3504)**: `npx -y @leadbay/mcp` no longer exits silently on Node 25. The `isEntrypoint` check now resolves both sides through `realpathSync`, so the npx shim symlink path matches the real `dist/bin.js`. Previously `main()` never ran under npx and the MCP host saw a dead connection with no diagnostic.
+- Replaced stale `app.leadbay.ai` URLs in error strings (NOT_AUTHENTICATED, AUTH_INVALID, BILLING_SUSPENDED, PERMISSION_DENIED) and CLI help text with runnable commands (`leadbay-mcp install`, `leadbay-mcp login`) or "contact support". Recovery hints include `--region <us|fr>` because the CLI refuses without it (anti-cross-region credential-leak guard).
+- Renamed misleading `avg_score_0_to_10` field on `pull_leads` / `bulk_qualify_leads` qualification summaries to `avg_qualification_boost`. Per-question AI agent scores are discrete boosts (-10/0/10/20), not 0-10 averages — interface JSDoc now reflects the real contract.
 - `SERVER_INSTRUCTIONS` gains three new paragraphs: "How Leadbay works" (inbox + consumption-based pacing), "Two scoring layers" (basic `score` vs AI-qualified top ~10 with `ai_agent_lead_score`), and "Suggested rhythm" (daily check-in + host-agnostic scheduling hint).
 - `leadbay_pull_leads`, `leadbay_research_lead`, `leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, and `leadbay_account_status` descriptions updated to reinforce the same model so the agent sees it at both top level and per-tool.
-- New non-regression test asserts the inbox/pace/scoring/daily language stays in `SERVER_INSTRUCTIONS`.
-- No schema changes, no tool-shape changes — wire-compatible with 0.2.1.
+- New regression test `test/smoke/npx-entrypoint.test.ts` guards the symlink invocation path. New non-regression test asserts the inbox/pace/scoring/daily language stays in `SERVER_INSTRUCTIONS`.
+- Live smoke harness extended with composite-level checks + (optional) thinking-model judge that writes a redacted report to `.context/`.
 
 ## 0.2.1 — 2026-04-21