@leadbay/mcp 0.32.4 → 0.32.5

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog — @leadbay/mcp
 
+## 0.32.5 — 2026-09-01
+
+`leadbay_update_contact` returned `NOT_FOUND` / 404 on 100% of the calls ever
+made to it (product#3997). Not a missing route and not a backend bug.
+
+Leadbay holds contacts in two id namespaces — `org_contacts` (the org's own
+directory) and `paid_contacts` (enrichment results) — with separate models,
+separate DAOs and separate ids. `POST /contacts/{id}/update` resolves
+`orgContacts.findById` only, so a paid id can only ever 404.
+
+`research_lead_by_id` merges `/leads/{id}/enrich/contacts` and
+`/leads/{id}/contacts` into `contacts.reachable` / `contacts.candidates`, split
+by **whether the person is messagable right now, not by which endpoint they came
+from**. That split is right for outreach and wrong for identity: an enriched
+paid contact sits in the same list as an org contact, and the agent had nothing
+to distinguish them by. Roughly half the ids we handed out were unusable by a
+tool the server instructions tell the agent to call after every outreach.
+
+- The `source` field (`"org"` / `"paid"`) was already on the wire but undeclared
+  and unexplained. It is now documented in `research_lead_by_id`'s output schema
+  as the thing that decides whether an id can be passed to
+  `leadbay_update_contact`.
+- `leadbay_update_contact`'s description states which namespace it accepts,
+  what a 404 means, and routes a correction to a paid contact through
+  `leadbay_add_contact` instead — the enrichment row is a provider's answer and
+  is not ours to edit.
+- New: `research-contact-source-provenance.test.ts`, covering the case the
+  reachability split hides — an enriched paid contact and an org contact in the
+  SAME `reachable` list, distinguished only by `source`.
 ## 0.32.4 — 2026-09-01
 
 `leadbay_account_status.notifications` was permanently `[]` on the hosted server
@@ -27,7 +56,6 @@ answer, and the ledger is not called.
   responses.** Reviving it would mean a `GET /notifications` per tool call to
   decorate every response. The cost lands on the check-in entry point only,
   which is where the daily-rhythm channel is actually read.
-
 ## 0.32.0 — 2026-09-01
 
 A poll-budget timeout stops being an error (product#4007). The import wizard's

package/dist/bin.js

@@ -10289,9 +10289,9 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
-Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`.
+Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on an EXISTING contact \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -10311,7 +10311,18 @@ One-line confirmation naming the contact and what changed. No table.
 
 Edit an existing contact in place \u2014 change their \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\`, or name.
 
-Pass the contact's **own** \`contact_id\` (the \`id\` field from \`leadbay_research_lead_by_id\` or a contacts list) \u2014 **not** the parent lead id.
+Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
+
+**Only your organization's own directory contacts can be edited.** Leadbay holds contacts in two separate id namespaces and this endpoint resolves one of them:
+
+| \`source\` on the contact | What it is | Editable here |
+|---|---|---|
+| \`"org"\` | A row in your organization's contact directory \u2014 added by you or your team, or promoted from an import | **yes** |
+| \`"paid"\` | An enrichment result bought from a data provider | **no** \u2014 returns \`NOT_FOUND\` / 404 |
+
+\`leadbay_research_lead_by_id\` returns both, merged into \`contacts.reachable\` / \`contacts.candidates\` and split by whether the person is messagable right now \u2014 **not** by which namespace they came from. So read \`source\` on the contact before calling this. If it is \`"paid"\` and the user wants different details on record, add the corrected person with \`leadbay_add_contact\` instead; the enrichment row is a provider's answer and is not ours to edit.
+
+A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
 **\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
 
@@ -19141,7 +19152,7 @@ var init_research_lead_by_id = __esm({
           },
           contacts: {
             type: "object",
-            description: "Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend's paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable.",
+            description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact \u2014 a `"paid"` id returns NOT_FOUND there.',
             properties: {
               reachable: { type: "array", items: { type: "object" } },
               candidates: { type: "array", items: { type: "object" } }
@@ -32961,7 +32972,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.32.4";
+var VERSION = "0.32.5";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 

package/dist/http-server.js

@@ -12682,9 +12682,9 @@ Trigger phrases: "update this contact", "fix this contact's title", "change thei
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
-Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`.
+Do NOT use for: "add a new contact to this company" \u2192 \`leadbay_add_contact\`; "remove / delete this contact" \u2192 \`leadbay_remove_contact\`; "get email/phone for a contact (enrichment)" \u2192 \`leadbay_enrich_titles\`; "fix an enriched contact's details" \u2192 \`leadbay_add_contact\`.
 
-Prefer when: user wants to change details on an EXISTING contact \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
+Prefer when: user wants to change details on a contact that is in their own directory (\`source: "org"\`) \u2014 pass that contact's own \`contact_id\` plus first_name + last_name (required) and the fields to change
 
 Examples that SHOULD invoke this tool:
 - "Update Jane's title to SVP Engineering."
@@ -12704,7 +12704,18 @@ One-line confirmation naming the contact and what changed. No table.
 
 Edit an existing contact in place \u2014 change their \`job_title\`, \`linkedin_page\`, \`email\`, \`phone_number\`, or name.
 
-Pass the contact's **own** \`contact_id\` (the \`id\` field from \`leadbay_research_lead_by_id\` or a contacts list) \u2014 **not** the parent lead id.
+Pass the contact's **own** \`contact_id\` \u2014 **not** the parent lead id.
+
+**Only your organization's own directory contacts can be edited.** Leadbay holds contacts in two separate id namespaces and this endpoint resolves one of them:
+
+| \`source\` on the contact | What it is | Editable here |
+|---|---|---|
+| \`"org"\` | A row in your organization's contact directory \u2014 added by you or your team, or promoted from an import | **yes** |
+| \`"paid"\` | An enrichment result bought from a data provider | **no** \u2014 returns \`NOT_FOUND\` / 404 |
+
+\`leadbay_research_lead_by_id\` returns both, merged into \`contacts.reachable\` / \`contacts.candidates\` and split by whether the person is messagable right now \u2014 **not** by which namespace they came from. So read \`source\` on the contact before calling this. If it is \`"paid"\` and the user wants different details on record, add the corrected person with \`leadbay_add_contact\` instead; the enrichment row is a provider's answer and is not ours to edit.
+
+A 404 from this tool almost always means a \`"paid"\` id was passed. Re-read the contact, check \`source\`, and do not retry the same id.
 
 **\`first_name\` + \`last_name\` are required even on an edit.** The backend validates the full contact identity and rejects a partial body (\`invalid contact\`). So pass the contact's *current* first/last name even when you're only changing the title \u2014 read the current values via \`leadbay_research_lead_by_id\` first if you don't have them.
 
@@ -20921,7 +20932,7 @@ var researchLeadById = {
       },
       contacts: {
         type: "object",
-        description: "Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend's paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable.",
+        description: 'Two-tier contact set, partitioned by reachability \u2014 agent-friendly framing of the backend\'s paid-vs-org split. `reachable`: contacts with an email or phone right now (org-directory entries that ship with channels, PLUS paid contacts whose enrichment has completed). The agent can message these without buying enrichment. `candidates`: paid-contact entries WITHOUT resolved channels yet \u2014 typically LinkedIn URL only, `enrichment_done: false`. The agent must call leadbay_enrich_titles (or leadbay_prepare_outreach with enrich:true) before these become messagable. Every contact in both lists carries `source`: `"org"` means it is a row in your organization\'s own contact directory, `"paid"` means it came from enrichment. The two are separate id namespaces on the backend, so only a `source:"org"` id can be passed to leadbay_update_contact / leadbay_remove_contact \u2014 a `"paid"` id returns NOT_FOUND there.',
         properties: {
           reachable: { type: "array", items: { type: "object" } },
           candidates: { type: "array", items: { type: "object" } }
@@ -29547,7 +29558,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.32.4" : "0.0.0-dev";
+var VERSION = true ? "0.32.5" : "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

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

package/dist/installer-gui.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.32.4",
+  "version": "0.32.5",
   "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",