@leadbay/mcp 0.17.2 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — @leadbay/mcp
 
+## 0.18.0 — 2026-06-08
+
+Backend long-task notifications are now consumed by the MCP. When the user (or agent) initiates a bulk operation — contact enrichment, lead qualification, CSV / CRM import — the MCP listens to the backend WebSocket for the completion event and surfaces it on the agent's next tool call so prior outputs that depended on the now-finished data can be revised.
+
+- **WS listener** — `wss://api-*.leadbay.app/ws/1.0?t=<ticket>` (ticketed via `GET /auth/ws?v=1.0`), reconnects with exponential backoff, REST catch-up via `GET /notifications` on every (re)connect and on cold start. Opt-out: `LEADBAY_NOTIFICATIONS_WS_DISABLED=1`.
+- **`_meta.notifications` on every tool response** — terminal bulk-progress notifications appear on every successful tool call until the agent acknowledges them. Auto-expires after 24h locally to prevent unbounded growth in unattended automation.
+- **`leadbay_account_status.notifications`** — same entries surfaced as a top-level field so the agent's daily-rhythm check-in sees them without reading `_meta`.
+- **`leadbay_acknowledge_notification(notification_id, archive?)`** — new always-exposed tool. Posts `/notifications/{id}/seen` (default) or `/archive`, removes the entry from the local inbox. The agent calls this *after* it has revised prior outputs the just-finished work might have made stale.
+- **Launch endpoints return `notification_id`** — `leadbay_enrich_titles`, `leadbay_bulk_qualify_leads`, `leadbay_import_leads`, and `leadbay_import_and_qualify` now read the canonical `notification_id` from `BulkLaunchResponse` / `BulkWebFetchResponsePayload` and persist it on the bulk tracker record.
+- **`bulk_qualify_leads` now uses the selection-based bulk endpoint** — replaces per-lead fan-out so the backend creates a single progress notification per call. Per-lead error attribution is coarser at launch (leads outside `queued_ids ∪ skipped_ids` are tagged `not_queued`); the polling phase still pulls concrete per-lead state.
+- **`bulk_enrich_status` fast path** — reads `bulk_progress` from the notification in a single REST call instead of fanning out `get_contacts` per lead. Falls back to the legacy per-lead path for records minted before this PR.
+- **`qualify_status` surfaces `bulk_progress`** — bulk counters (success / failure / quota_hit) appear alongside the existing per-lead refresh. `quota_hit_count > 0` triggers an upgrade-or-wait hint.
+- **Vocabulary**: "notifications" everywhere. Not "pending actions", not "tasks", not "async results" — matches the backend ADR (`docs/adr/notifications.md`).
+
+## 0.17.3 — 2026-06-01
+
+- **Lens management on the default surface**: lenses are now fully manageable from chat, no `LEADBAY_MCP_ADVANCED` needed.
+  - `leadbay_my_lenses` (write) — list your lenses, switch the active one, rename / set description, or delete (delete is confirm-gated and refuses the default lens).
+  - `leadbay_new_lens` (write) — create a named lens with sector/size criteria in one call; previews and confirms before creating, and rolls back the created lens if applying its filter fails (no orphan half-built lenses).
+  - `leadbay_adjust_audience` — new `lensName` param edits a lens **by name** without switching your active lens (edit-only).
+  - `leadbay_list_sectors` (read, always-on) — the sector taxonomy lookup, so the agent stops guessing sector names.
+- **Routing**: `leadbay_adjust_audience` and `leadbay_refine_prompt` gained routing blocks so "create a lens" reaches `new_lens` (not `refine_prompt`) and "add X to my Y lens" fills `lensName` instead of editing the active lens.
+- **Backend contract fixes** (were causing `400 JSON deserialization error` on lens create/edit, verified live): `POST /lenses` `base` sent as a string; `POST /lenses/:id/filter` sent as the unwrapped `{items:[…]}` body; `size` criteria carry both `min` and `max`.
+
 ## 0.17.2 — 2026-06-01
 
 - **Linux installer fix**: skip Electron when no display is available (`$DISPLAY`/`$WAYLAND_DISPLAY` unset) and go straight to browser fallback — eliminates the double GUI URL on headless Linux terminals.

package/README.md

@@ -699,7 +699,44 @@ Accepted values: `"true"|"1"|"yes"|"on"` enable; `"false"|"0"|"no"|"off"` disabl
 
 Contact data fetched through this server stays local to your MCP client session — telemetry never carries it. Requests to Leadbay are subject to the [Leadbay privacy policy](https://leadbay.ai/privacy).
 
-## 9. For maintainers — publishing
+## 9. For developers — testing a local build
+
+Use this when you want to test changes to the MCP server in your real MCP clients (Claude Desktop, Claude Code, Cursor, Codex) without publishing to npm.
+
+### 1. Build
+
+```bash
+pnpm install
+pnpm build
+```
+
+### 2. Run the installer with `--local`
+
+```bash
+pnpm --filter @leadbay/mcp installer -- --local
+```
+
+This opens the installer wizard in your browser. Sign in with OAuth, select your clients, and click Install. The wizard writes `node /absolute/path/to/dist/bin.js` into each client's config instead of the usual `npx @leadbay/mcp@latest` invocation.
+
+### 3. Restart your MCP client
+
+Restart Claude Desktop / Claude Code / Cursor / Codex to pick up the new config.
+
+### Revert to the published version
+
+Run the installer again **without** `--local` to switch back to npm:
+
+```bash
+pnpm --filter @leadbay/mcp installer
+```
+
+Or use the published package directly:
+
+```bash
+npx -y -p @leadbay/mcp@latest installer
+```
+
+## 10. For maintainers — publishing
 
 Releases are tag-driven via `.github/workflows/release.yml`. Bump `packages/mcp/package.json#version`, update `packages/mcp/CHANGELOG.md`, land on `main`, then: