@leadbay/mcp 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — @leadbay/mcp
+
+## 0.2.0 — 2026-04-20
+
+First public npm release.
+
+- Agent-optimized composite tool surface (pull_leads, research_lead, bulk_qualify_leads, enrich_titles, adjust_audience, refine_prompt, recall_ordered_titles, account_status, report_outreach).
+- `leadbay-mcp install` one-shot setup: mints a token and registers the server with Claude Code, Claude Desktop, and Cursor.
+- `leadbay-mcp login` lower-level token mint (`--write-config` drops a 0600 JSON).
+- `leadbay-mcp doctor` validates token + region + quota.
+- Gating: `LEADBAY_MCP_WRITE=1` for mutations, `LEADBAY_MCP_ADVANCED=1` for the granular API surface (both off by default).
+- `report_outreach` requires a verification field (`gmail_message_id | calendar_event_id | user_confirmed`) to prevent pipeline poisoning.
+- Mock mode via `LEADBAY_MOCK=1` for agent-author dry-running against `.context/leadbay-live-shapes/` fixtures.
+- Tag-driven CI publish via `.github/workflows/release.yml` (push `mcp-v<version>` or `v<version>`).
+- `--version` output now sourced from `package.json` at build time — no more drift between the tarball version and the binary's self-reported version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leadbay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,140 @@
+# Migration: leadclaw / leadbay-mcp 0.1.x → 0.2.0
+
+This release is the autoplan-reviewed agent-experience overhaul. The OpenClaw
+plugin and MCP server gain a coherent composite-tool surface so an AI agent
+can drive Leadbay end-to-end with a handful of calls. The old granular tools
+remain available behind config flags.
+
+## Headline changes
+
+- **`leadbay_find_prospects` removed** → replaced by **`leadbay_pull_leads`**
+  (richer return: each lead carries a `qualification_summary` digest from
+  `ai_agent_responses`, plus all the engagement-state flags).
+- **New composite agent surface** (the agent's default toolbox):
+  - `leadbay_pull_leads` — paginated wishlist with qualification digest
+  - `leadbay_research_lead` — full lead detail (qualification → signals → firmographics → contacts → engagement)
+  - `leadbay_recall_ordered_titles` — show titles previously enriched
+  - `leadbay_account_status` — admin / language / quota / intelligence state
+  - `leadbay_bulk_qualify_leads` — paginate past already-qualified, fan-out + poll
+  - `leadbay_enrich_titles` — selection-lifecycle-managed bulk enrichment
+  - `leadbay_adjust_audience` — sector / size filter mutation with permission auto-routing
+  - `leadbay_refine_prompt` — set the org intelligence-refinement prompt
+  - `leadbay_answer_clarification` — answer the question Leadbay raised
+  - `leadbay_report_outreach` — log outreach **with mandatory verification**
+- **New gating model** (both MCP and OpenClaw):
+  - **Composite reads**: always exposed.
+  - **Composite writes**: gated by `LEADBAY_MCP_WRITE=1` (MCP) or
+    `exposeWrite: true` plugin config (OpenClaw).
+  - **Granular reads**: gated by `LEADBAY_MCP_ADVANCED=1` (MCP) or
+    `exposeGranular: true` (OpenClaw).
+  - **Granular writes**: gated by BOTH advanced AND write flags.
+- **`leadbay_login` auto-detects region** (us → fr fallback). The user no
+  longer needs to know which backend their account is in.
+- **`leadbay_get_quota` switched to the live `/quota_status` endpoint** —
+  returns daily/weekly/monthly windows for `llm_completion`, `ai_rescore`,
+  `web_fetch` resources. Use this AFTER a 429 to explain which window was hit.
+- **Error mapping changed: `429 → QUOTA_EXCEEDED`** (production behavior).
+  Legacy 402 still maps to QUOTA_EXCEEDED for back-compat.
+- **HTTP-response headers are now captured** and propagated through the error
+  envelope's `_meta: {region, endpoint, latency_ms, retry_after}`. There is
+  no `X-Request-Id` header on the Leadbay backend — we don't pretend there is.
+- **`LEADBAY_MOCK=1`** mode: serve responses from on-disk fixtures
+  (`.context/leadbay-live-shapes/`) for agent-author dry-running. Writes are
+  journaled in-process and return `{mocked: true, would_call: {...}}`.
+- **`dry_run: true`** param on every state-changing composite (`report_outreach`,
+  `set_user_prompt`, `update_lens_filter`, `launch_bulk_enrichment`, etc.) —
+  returns the would-call envelope without contacting the backend.
+
+## report_outreach: verification REQUIRED
+
+The autoplan review (CEO + Eng + DX voices) flagged that allowing the agent
+to self-report outreach without proof would poison the SDR pipeline. The user
+chose the strictest mitigation: every `report_outreach` call MUST include a
+`verification` field:
+
+```json
+{
+  "lead_id": "abc-123",
+  "note": "Sent intro email to CTO citing Hornsea 3 contract",
+  "epilogue_status": "STILL_CHASING",
+  "verification": {
+    "source": "gmail_message_id",
+    "ref": "<the message id from Gmail>"
+  }
+}
+```
+
+Valid `source` values:
+- `gmail_message_id` — message id returned by `mcp__claude_ai_Gmail__send_email`
+- `calendar_event_id` — event id from a calendar booking tool
+- `user_confirmed` — `ref` is the user's literal confirmation in chat
+
+The verification is appended to the note body so humans in the Leadbay UI can
+see the proof. Calls without verification return `VERIFICATION_REQUIRED`.
+
+## Side-by-side: old flow → new flow
+
+| Old (v0.1) | New (v0.2) | Notes |
+|---|---|---|
+| `leadbay_find_prospects` | `leadbay_pull_leads` | Same intent; richer return; remove name |
+| `leadbay_get_lead_profile` | `leadbay_research_lead` | New ordering (qualification first); reshapes `web_fetch.content` from emoji-keyed dict to ordered array. Granular still available behind exposeGranular. |
+| `leadbay_research_company` | unchanged | Kept for back-compat; prefer `research_lead` when you have the id. |
+| `leadbay_qualify_lead` (single) | `leadbay_bulk_qualify_leads` | Composite paginates past already-qualified, fan-outs, polls, bails on 429. Granular still available. |
+| `leadbay_enrich_contacts` (single) | `leadbay_enrich_titles` | Composite manages selection lifecycle. Granular still available. |
+| `leadbay_get_quota` (legacy billing fields) | `leadbay_get_quota` (live /quota_status) | Same name, new shape. Old `freemium.daily_quota` / `ai_credits` are defunct. |
+| Add a free-form note via `leadbay_add_note` | Log outreach via `leadbay_report_outreach` | Note tool still exists for free-form context; `report_outreach` is the right call after an actual action. |
+
+## How to upgrade
+
+### Claude Desktop / Cursor (MCP)
+
+```json
+{
+  "mcpServers": {
+    "leadbay": {
+      "command": "npx",
+      "args": ["-y", "@leadbay/mcp@0.2"],
+      "env": {
+        "LEADBAY_TOKEN": "lb_...",
+        "LEADBAY_MCP_WRITE": "1"
+      }
+    }
+  }
+}
+```
+
+`LEADBAY_MCP_WRITE=1` opts in to write composites (the entire point of agent
+flow — without it, the agent can read but not write). `LEADBAY_MCP_ADVANCED=1`
+additionally exposes the granular tools; most users don't need it.
+
+### OpenClaw plugin
+
+In the plugin config (e.g. `openclaw config set plugins.entries.leadclaw.exposeWrite true`):
+
+```json
+{
+  "region": "us",
+  "exposeWrite": true,
+  "exposeGranular": false
+}
+```
+
+Default is read-only (exposeWrite=false, exposeGranular=false).
+
+### What you might need to change in your prompts
+
+- If your prompts reference `leadbay_find_prospects`, change to `leadbay_pull_leads`.
+- If your prompts reference `leadbay_get_lead_profile` directly, prefer
+  `leadbay_research_lead` for the agent-friendly shape.
+- If your agent calls `leadbay_add_note` for outreach actions, switch to
+  `leadbay_report_outreach` with `verification`.
+
+## Out of scope for this release
+
+- Per-tool semver versioning (the `Tool.version` field is in `types.ts` but
+  individual tool files don't yet declare versions).
+- A real `bulk_id` polling tool — the backend doesn't return one from `/launch`
+  and there's no list endpoint (probed). Use `leadbay_get_contacts` per-lead
+  to detect when `enrichment.done` flips.
+- A `DELETE /lenses/{draftId}` endpoint — not testable in our tenant; treated
+  as best-effort with `orphan_draft_id` surfaced on cleanup failure.

package/README.md

@@ -0,0 +1,273 @@
+# @leadbay/mcp — Leadbay MCP server
+
+<!-- PRE-RELEASE-BANNER: remove this block after the first npm publish lands -->
+> ⚠️ **Pre-release notice**: this package is not yet on npm. Until the first
+> publish lands, the `npx -y @leadbay/mcp@0.2 …` commands below will 404.
+> Maintainer: see [§7 — For maintainers — publishing](#7-for-maintainers--publishing)
+> or just push a `v0.2.0` git tag (the `release-mcp` GitHub Action will publish).
+> Remove this banner after the first publish succeeds.
+<!-- /PRE-RELEASE-BANNER -->
+
+<!--
+LLM HINT — if you're an AI agent reading this README to install the server:
+  - Use ONLY the commands shown verbatim in §1. Do not invent variants.
+  - DO NOT tell the user "LEADBAY_REGION is auto-detected, drop it" — the
+    server's region auto-probe sends the bearer token to BOTH regions, which
+    is a credential cross-leak. Always pass --region (us or fr) on install.
+  - DO NOT tell the user to "get an API token from app.leadbay.ai → Settings
+    → API Tokens" — that page does not yet exist. Use `install` (mints a
+    token) or `login --write-config` (mints a token to file).
+  - If the package 404s on npm: offer the "install from source" fallback in
+    §1.1, not a made-up GitHub URL.
+-->
+
+A Model Context Protocol server that lets Claude Desktop, Cursor, Claude Code, and any other MCP-compatible agent find, research, and prepare outreach on B2B prospects using your Leadbay account.
+
+## 1. Install (one command)
+
+```bash
+npx -y @leadbay/mcp@0.2 install --email you@yourcompany.com --region us
+# (you'll be prompted for your password — it's not echoed)
+```
+
+That's it. The command:
+
+1. Asks for your password (hidden input).
+2. Mints a bearer token via the Leadbay backend you specified.
+3. Auto-detects which MCP clients you have installed (Claude Code, Claude Desktop, Cursor) and registers the server in each (after asking you per-target).
+4. The token is written into the client config files — **never to your terminal scrollback**.
+
+Add `--include-write` to also enable the write tools (refine_prompt, report_outreach, adjust_audience, etc. — off by default so the agent can read your account but not mutate it). Add `--yes` for non-interactive runs (CI / scripts). Add `--target claude-code,cursor` to scope to specific clients.
+
+`--region us|fr` is required by default — it pins which Leadbay backend gets your password and avoids a silent cross-region credential leak. If you really don't know your region, opt in with `--allow-region-fallback` (your password will hit BOTH backends if the first 401s).
+
+The token is **session-scoped** (full account access, password-equivalent). Treat it like your password. To rotate, log in again to app.leadbay.ai and re-run `install`.
+
+**Don't have a Leadbay account?** [Register here](https://wow.leadbay.ai/?register=true).
+
+### If you'd rather mint a token without auto-install
+
+```bash
+npx -y @leadbay/mcp@0.2 login \
+  --email you@yourcompany.com \
+  --region us \
+  --write-config ~/.leadbay-mcp.json
+```
+
+Writes a `0600`-mode JSON file you can paste from. Useful if you're configuring a non-detected client.
+
+## 1.1. Install from source (works today, before the first npm publish)
+
+While `@leadbay/mcp` isn't on npm yet, install from a local git checkout:
+
+```bash
+# 1. Clone, build
+git clone https://github.com/leadbay/leadclaw.git
+cd leadclaw
+pnpm install
+pnpm -r build
+
+# 2. Mint a token + register with your installed clients (auto-detects Claude Code,
+#    Claude Desktop, Cursor) — same install subcommand, run from local dist:
+node packages/mcp/dist/bin.js install --email you@yourcompany.com --region us
+```
+
+Or skip the `install` helper and register manually with the local dist path:
+
+```bash
+# Mint a token to a 0600 JSON file:
+node packages/mcp/dist/bin.js login \
+  --email you@yourcompany.com --region us \
+  --write-config ~/.leadbay-mcp.json
+TOKEN=$(jq -r .mcpServers.leadbay.env.LEADBAY_TOKEN ~/.leadbay-mcp.json)
+
+# Register with Claude Code (point at the absolute path of the local bin.js):
+claude mcp add leadbay \
+  --env LEADBAY_TOKEN=$TOKEN \
+  --env LEADBAY_REGION=us \
+  -- node $(pwd)/packages/mcp/dist/bin.js
+```
+
+For Claude Desktop / Cursor, the JSON config block from `--write-config` works directly — just change the `command` from `npx` to `node` and the `args` to `["/abs/path/to/leadclaw/packages/mcp/dist/bin.js"]`.
+
+**B) From the web app (when available):** log in at [app.leadbay.ai](https://app.leadbay.ai), go to **Settings → API Tokens**, create a token, copy it.
+
+Don't have a Leadbay account yet? [Register here](https://wow.leadbay.ai/?register=true).
+
+## 2. Quickstart
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "leadbay": {
+      "command": "npx",
+      "args": ["-y", "@leadbay/mcp@0.2"],
+      "env": {
+        "LEADBAY_TOKEN": "<paste-token-from-step-1>",
+        "LEADBAY_REGION": "us"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+### Cursor
+
+In Cursor settings, add the MCP server:
+
+```json
+{
+  "mcp.servers": {
+    "leadbay": {
+      "command": "npx",
+      "args": ["-y", "@leadbay/mcp@0.2"],
+      "env": { "LEADBAY_TOKEN": "<paste-token>", "LEADBAY_REGION": "us" }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add leadbay \
+  --env LEADBAY_TOKEN=<paste-token> \
+  --env LEADBAY_REGION=us \
+  -- npx -y @leadbay/mcp@0.2
+```
+
+> Want write tools (refine prompt, log outreach, adjust audience, etc.)? Add `--env LEADBAY_MCP_WRITE=1`. They're hidden by default so an LLM can't mutate state without your explicit opt-in.
+
+### Verify it works
+
+Before starting Claude, run:
+
+```bash
+LEADBAY_TOKEN=<paste-token> npx -y @leadbay/mcp@0.2 doctor
+```
+
+Expected output:
+
+```
+Leadbay connection OK.
+  Organization:  Your Org
+  Billing:       active
+  AI credits:    420 / 1000
+```
+
+## 3. Example prompts that work
+
+> *Find me 20 SaaS companies in Berlin that match my Ideal Buyer Profile.*
+
+> *Research the top prospect from that list — give me the AI summary, recent activity, and who I should reach out to.*
+
+> *Prepare an outreach package for Acme Corp — include the recommended contact with enriched email if we have credits.*
+
+## 4. Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `LEADBAY_TOKEN environment variable is required` | Token missing from config env | Add `LEADBAY_TOKEN` to the `env` block, restart client |
+| `Authentication token expired or invalid` | Token revoked or wrong region | Re-generate token at [app.leadbay.ai/settings/api-tokens](https://app.leadbay.ai/settings/api-tokens); verify `LEADBAY_REGION` |
+| `Leadbay doctor: could not reach any Leadbay region` | Wrong region OR network blocked | Run `doctor` with `LEADBAY_REGION=fr` to auto-probe. Check `https://api-us.leadbay.app` reachable. |
+| `No enrichment credits remaining` | Out of quota | Buy credits at [app.leadbay.ai](https://app.leadbay.ai) |
+| Claude Desktop "loading forever" on first use | `npx` cold-start fetching the package | First run takes ~10s. Prefer `npm install -g @leadbay/mcp` for faster startup. |
+| Claude Desktop doesn't show Leadbay tools | Server crashed at startup | Check `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\logs\mcp*.log` (Windows). |
+
+## 5. Upgrade & rotation
+
+**Upgrade**: change the pinned minor in your config, e.g. `"@leadbay/mcp@0.1"` → `"@leadbay/mcp@0.2"`, then restart the client. See the [changelog](https://github.com/leadbay/leadclaw/releases) and [MIGRATION.md](./MIGRATION.md).
+
+**Rotate token**: re-run `npx -y @leadbay/mcp@0.2 install --email you@yourcompany.com --region us` (or `login --write-config …`) — the new session token replaces the old one in your MCP client config, and logging in again invalidates the prior session on most session backends.
+
+## 6. Advanced
+
+### Exposing the granular tools and write tools
+
+By default the server exposes the **composite workflow tools** (`leadbay_pull_leads`, `leadbay_research_lead`, `leadbay_account_status`, `leadbay_recall_ordered_titles`, plus existing `leadbay_research_company`, `leadbay_prepare_outreach`). These work well with most prompts.
+
+To unlock the **granular API tools** (`leadbay_list_lenses`, `leadbay_discover_leads`, `leadbay_get_lead_profile`, `leadbay_get_contacts`, `leadbay_get_quota`, `leadbay_get_taste_profile`, `leadbay_get_lens_filter`, `leadbay_list_sectors`, …), set `LEADBAY_MCP_ADVANCED=1`.
+
+To unlock the **write tools** (`leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, `leadbay_adjust_audience`, `leadbay_refine_prompt`, `leadbay_report_outreach`, etc.), set `LEADBAY_MCP_WRITE=1`. Both flags are independent; combine to expose everything.
+
+```json
+"env": {
+  "LEADBAY_TOKEN": "<token>",
+  "LEADBAY_MCP_ADVANCED": "1",
+  "LEADBAY_MCP_WRITE": "1"
+}
+```
+
+`leadbay_report_outreach` requires a `verification` field on every call (Gmail message id, Calendar event id, or `user_confirmed` with the user's literal text) so the agent can't poison your SDR pipeline with hallucinated outreach.
+
+**Note**: `leadbay_login` is intentionally not exposed over MCP — see [Security](#security) below.
+
+### Environment variables
+
+| Var | Required | Default | Purpose |
+|-----|----------|---------|---------|
+| `LEADBAY_TOKEN` | **yes** | — | Bearer token (mint via `install` or `login`, or set manually) |
+| `LEADBAY_REGION` | **strongly recommended** | (auto-probe — see warning below) | `us` or `fr` |
+| `LEADBAY_BASE_URL` | no | derived from region | Override for staging/dev |
+| `LEADBAY_MCP_ADVANCED` | no | unset | `"1"` exposes the granular API tools |
+| `LEADBAY_MCP_WRITE` | no | unset | `"1"` exposes write composite + granular tools |
+| `LEADBAY_MOCK` | no | unset | `"1"` serves all reads from on-disk fixtures (dev only) |
+| `LEADBAY_MOCK_DIR` | no | `./.context/leadbay-live-shapes/` | Fixture dir for mock mode |
+| `LEADBAY_LOG_LEVEL` | no | `error` | `debug` \| `info` \| `error`, logs to stderr |
+
+> ⚠️ **Set `LEADBAY_REGION` explicitly.** If you don't, the server probes BOTH `api-us.leadbay.app` and `api-fr.leadbay.app` in parallel with your bearer token attached, sending the token to a backend that doesn't own your account. The `install` and `login` subcommands enforce `--region` for exactly this reason; the runtime auto-probe is a backwards-compat fallback, not a recommended setting.
+| `LEADBAY_TIMEOUT_MS` | no | (client default) | Per-request timeout override |
+
+### Security
+
+- Tokens live only in your MCP client's config file — they never traverse the network except to `api-{region}.leadbay.app`.
+- The `leadbay_login` tool from the OpenClaw adapter is **not** registered on MCP: exposing a credential-taking tool to an LLM is a prompt-injection risk. Use the token path above.
+- The `leadbay_add_note` and `leadbay_enrich_contacts` tools are write actions flagged `optional: true`. If your client supports per-tool opt-in, leave them disabled until you need them.
+
+### Privacy
+
+Contact data fetched through this server stays local to your MCP client session. No analytics or telemetry is sent by `@leadbay/mcp`. Requests to Leadbay are subject to the [Leadbay privacy policy](https://leadbay.ai/privacy).
+
+## 7. For maintainers — publishing
+
+This package is published to npm under `@leadbay/mcp`. **Until the first publish lands, `npx -y @leadbay/mcp@0.2 install …` will fail with a 404 — the install instructions in §1 assume the package is on the registry.**
+
+### Recommended: tag → CI auto-publish
+
+The `release-mcp` GitHub Action (`.github/workflows/release.yml`) publishes to npm whenever a tag matching `v*.*.*` is pushed:
+
+```bash
+# (one-time) generate an npm Automation token at npmjs.com → tokens
+# and add it as the GitHub Actions secret NPM_TOKEN.
+
+# Each release:
+git checkout main && git pull
+# bump packages/mcp/package.json version, commit, push
+git tag v0.2.0 && git push --tags
+# CI runs build + tests + npm publish --access public --provenance
+```
+
+The workflow verifies that the tag matches `packages/mcp/package.json` `version`, so a stale tag won't ship the wrong build.
+
+### Manual fallback
+
+If you'd rather publish from your laptop:
+
+```bash
+cd packages/mcp
+pnpm install                    # ensure workspace deps are linked
+pnpm build                      # tsup bundles @leadbay/core into dist/bin.js
+npm publish --access public     # @leadbay/* is a scoped package
+```
+
+`prepublishOnly` re-runs `tsup` automatically so the published tarball always matches `src/`. The first publish must use `--access public` (already pinned in `publishConfig`). Once the first publish succeeds, remove the pre-release banner at the top of this README.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).