@leadbay/mcp 0.4.0 → 0.6.0

package/README.md

@@ -15,12 +15,14 @@ LLM HINT — if you're an AI agent reading this README to install the server:
 
 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.
 
+> **0.6.0 — what's new** (UNRELEASED): a comprehensive MCP-spec coverage upgrade. Every tool now declares **annotations** (`readOnlyHint`/`destructiveHint`/`idempotentHint`/`openWorldHint`) so capable clients pick the right confirmation UX. The 5 highest-traffic composites ship **`outputSchema` + `structuredContent`** for typed agent consumption. New surfaces: **`prompts/*`** (5 canned slash-commands), **`resources/*`** (`lead://`, `lens://`, `org://taste-profile`), **`notifications/progress`** (per-lead streaming during `bulk_qualify_leads`), **`notifications/cancelled` → `ToolContext.signal`** (client cancels actually stop polling), **`elicitation/create`** (server can ask the user directly). Schema strictness: every `inputSchema` now declares `additionalProperties: false`. `research_lead.qualification[]` ships `boost_score` (canonical) + `score_scale: "-10|0|10|20"` + a deprecated `score_0_to_10` alias. Pagination payloads include `has_more` + `next_page`. `research_lead` includes a `truncated` + `truncation_hint` budget guard. **Behavior callout**: extra unknown fields in tool inputs are now rejected. See [MIGRATION.md](./MIGRATION.md).
+
 > **0.3.0 behavior change** — composite write tools (`refine_prompt`, `report_outreach`, `adjust_audience`, `bulk_qualify_leads`, `enrich_titles`, `answer_clarification`, `import_leads`) are **ON by default**. Set `LEADBAY_MCP_WRITE=0` (or `--no-write` on `install`) to restore the previous read-only behavior. `leadbay-mcp install` now also registers Claude Code at `--scope user` so Leadbay is visible from any project. See [MIGRATION.md](./MIGRATION.md).
 
 ## 1. Install (one command)
 
 ```bash
-npx -y @leadbay/mcp@0.3 install --email you@yourcompany.com --region us
+npx -y @leadbay/mcp@0.6 install --email you@yourcompany.com --region us
 # (you'll be prompted for your password — it's not echoed)
 ```
 
@@ -47,14 +49,14 @@ Claude Desktop 2026 ships the DXT (Desktop Extension) system — the legacy `cla
 
 If you installed Node from the official [nodejs.org](https://nodejs.org) `.pkg`, `/usr/local/lib/node_modules` is root-owned. Any of these works:
 
-- **Use `npx` (recommended, no global install):** all examples above use `npx -y @leadbay/mcp@0.3 ...` — no global install needed.
+- **Use `npx` (recommended, no global install):** all examples above use `npx -y @leadbay/mcp@0.6 ...` — no global install needed.
 - **`sudo npm install -g @leadbay/mcp`** (enter your macOS password).
 - **Use a Node version manager** — [nvm](https://github.com/nvm-sh/nvm), [volta](https://volta.sh), [fnm](https://github.com/Schniz/fnm). They install Node under your home directory, so `npm install -g` works without sudo.
 
 ### If you'd rather mint a token without auto-install
 
 ```bash
-npx -y @leadbay/mcp@0.3 login \
+npx -y @leadbay/mcp@0.6 login \
   --email you@yourcompany.com \
   --region us
 ```
@@ -72,7 +74,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
   "mcpServers": {
     "leadbay": {
       "command": "npx",
-      "args": ["-y", "@leadbay/mcp@0.3"],
+      "args": ["-y", "@leadbay/mcp@0.6"],
       "env": {
         "LEADBAY_TOKEN": "<paste-token-from-step-1>",
         "LEADBAY_REGION": "us"
@@ -93,7 +95,7 @@ In Cursor settings, add the MCP server:
   "mcp.servers": {
     "leadbay": {
       "command": "npx",
-      "args": ["-y", "@leadbay/mcp@0.3"],
+      "args": ["-y", "@leadbay/mcp@0.6"],
       "env": { "LEADBAY_TOKEN": "<paste-token>", "LEADBAY_REGION": "us" }
     }
   }
@@ -106,7 +108,7 @@ In Cursor settings, add the MCP server:
 claude mcp add leadbay --scope user \
   --env LEADBAY_TOKEN=<paste-token> \
   --env LEADBAY_REGION=us \
-  -- npx -y @leadbay/mcp@0.3
+  -- npx -y @leadbay/mcp@0.6
 ```
 
 > **`--scope user`** registers Leadbay globally for your account (visible from any project). Without it, `claude mcp add` defaults to project-local scope and the server only appears in conversations opened from the directory where you ran the command.
@@ -118,7 +120,7 @@ claude mcp add leadbay --scope user \
 Before starting Claude, run:
 
 ```bash
-LEADBAY_TOKEN=<paste-token> npx -y @leadbay/mcp@0.3 doctor
+LEADBAY_TOKEN=<paste-token> npx -y @leadbay/mcp@0.6 doctor
 ```
 
 Expected output:
@@ -138,6 +140,202 @@ Leadbay connection OK.
 
 > *Prepare an outreach package for Acme Corp — include the recommended contact with enriched email if we have credits.*
 
+## 3a. Spec primitives in action
+
+> If you're building or auditing an MCP integration, this section shows what each spec primitive looks like on the wire when calling `@leadbay/mcp`. Every example is the actual JSON-RPC frame your client sends or receives — copy verbatim into a debugger.
+
+### `tools/list` — annotations + outputSchema
+
+Every tool advertises read/write/idempotent/openWorld posture and (for the top declarers) a typed return schema.
+
+Request:
+
+```json
+{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
+```
+
+Response (excerpt):
+
+```json
+{
+  "tools": [
+    {
+      "name": "leadbay_account_status",
+      "description": "Show the user's account state — admin rights, language, last-active lens, current quota …",
+      "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
+      "annotations": {
+        "title": "Show Leadbay account + quota state",
+        "readOnlyHint": true, "destructiveHint": false,
+        "idempotentHint": true, "openWorldHint": true
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "user": { "type": "object", "properties": { "email": {}, "name": {}, "admin": {}, "manager": {}, "language": {} } },
+          "organization": { "type": "object", "properties": { "id": {}, "name": {}, "ai_agent_enabled": {}, "computing_intelligence": {}, "plan": {} } },
+          "last_requested_lens": {},
+          "quota": {},
+          "_meta": { "type": "object", "properties": { "region": {} } }
+        },
+        "required": ["user", "organization"]
+      }
+    }
+  ]
+}
+```
+
+Capable clients use the annotations to decide auto-approve vs prompt; the `outputSchema` lets them dispatch on shape rather than re-parse the text.
+
+### `tools/call` with `structuredContent`
+
+When the tool declares `outputSchema`, the response carries a typed `structuredContent` block alongside `text` content:
+
+Request:
+
+```json
+{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": { "name": "leadbay_account_status", "arguments": {} } }
+```
+
+Response:
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "{\"user\":{...},\"organization\":{...}, ...}" }
+  ],
+  "structuredContent": {
+    "user":  { "email": "you@example.com", "name": "You", "admin": true, "manager": false, "language": "en" },
+    "organization": { "id": "org-1", "name": "Your Co", "ai_agent_enabled": true, "computing_intelligence": false, "plan": "PRO" },
+    "last_requested_lens": 42,
+    "quota": { "plan": "PRO", "windows": [...] },
+    "_meta": { "region": "us" }
+  }
+}
+```
+
+### `prompts/list` and `prompts/get` — slash commands
+
+Request:
+
+```json
+{ "jsonrpc": "2.0", "id": 3, "method": "prompts/list" }
+```
+
+Response (excerpt):
+
+```json
+{
+  "prompts": [
+    { "name": "daily-check-in", "description": "Pull fresh leads, surface auto-qualified top, deepen 1-3 promising ones.", "arguments": [] },
+    { "name": "research-a-domain", "description": "Import a domain → resolve to leadId → research_lead.",
+      "arguments": [{ "name": "domain", "description": "Company domain (e.g., acme.com)", "required": true }] },
+    { "name": "log-outreach", "description": "Gather verification → report_outreach.",
+      "arguments": [{ "name": "lead_id", "required": true }, { "name": "what", "required": true }] }
+  ]
+}
+```
+
+Then `prompts/get` materialises the chosen workflow as a structured `messages` array the agent unfurls:
+
+```json
+{ "jsonrpc": "2.0", "id": 4, "method": "prompts/get",
+  "params": { "name": "research-a-domain", "arguments": { "domain": "acme.com" } } }
+```
+
+### `resources/list` and `resources/read` — URI-addressable read-only data
+
+Three URI schemes are advertised: `lead://{uuid}/profile`, `lens://{id}/definition`, `org://taste-profile`. Capable clients cache them across turns.
+
+Request:
+
+```json
+{ "jsonrpc": "2.0", "id": 5, "method": "resources/templates/list" }
+```
+
+Response (excerpt):
+
+```json
+{
+  "resourceTemplates": [
+    { "uriTemplate": "lead://{uuid}/profile", "name": "Lead profile", "description": "Lead profile by Leadbay UUID — basics + qualifications + contacts.", "mimeType": "application/json" },
+    { "uriTemplate": "lens://{id}/definition", "name": "Lens definition", "description": "Filter + scoring config for a lens.", "mimeType": "application/json" }
+  ]
+}
+```
+
+Read a specific lead:
+
+```json
+{ "jsonrpc": "2.0", "id": 6, "method": "resources/read",
+  "params": { "uri": "lead://0xabcd-…/profile" } }
+```
+
+Response wraps the JSON in a `text` content block with the URI's mime type so clients can render or cache it.
+
+### `notifications/progress` — streaming during long ops
+
+When the agent calls a long-running tool with a `progressToken` in `_meta`, the server streams progress notifications back. Long-runners that emit: `bulk_qualify_leads`, `import_and_qualify`, `enrich_titles`, `bulk_enrich_status`, `qualify_status`.
+
+Request:
+
+```json
+{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
+  "params": {
+    "name": "leadbay_bulk_qualify_leads",
+    "arguments": { "leadIds": ["lead-1", "lead-2", "lead-3"] },
+    "_meta": { "progressToken": "bq-1" }
+  } }
+```
+
+While the call runs, notifications arrive:
+
+```json
+{ "jsonrpc": "2.0", "method": "notifications/progress",
+  "params": { "progressToken": "bq-1", "progress": 1, "total": 3, "message": "Qualified Acme Corp (1/3)" } }
+{ "jsonrpc": "2.0", "method": "notifications/progress",
+  "params": { "progressToken": "bq-1", "progress": 2, "total": 3, "message": "Qualified Globex (2/3)" } }
+{ "jsonrpc": "2.0", "method": "notifications/progress",
+  "params": { "progressToken": "bq-1", "progress": 3, "total": 3, "message": "Qualified Initech (3/3)" } }
+```
+
+Then the final `tools/call` response.
+
+### `notifications/cancelled` — actually cancelling
+
+Send the cancellation by id; the server's `ToolContext.signal` aborts the polling loop within ≤2 seconds, the bulk-store entry is marked `cancelled`, and the next `bulk_enrich_status` returns `BULK_CANCELLED` so the agent stops polling.
+
+```json
+{ "jsonrpc": "2.0", "method": "notifications/cancelled",
+  "params": { "requestId": 7, "reason": "user clicked cancel" } }
+```
+
+### `elicitation/create` — server asks the user
+
+Used by `refine_prompt` (clarification flow) and `report_outreach` (anti-poisoning user-confirmation). The server sends an `elicitation/create` request to the client; the client renders a form; the user types; the response feeds back into the tool call. The agent never sees the prompt.
+
+Server emits (mid-`tools/call`):
+
+```json
+{ "jsonrpc": "2.0", "id": 99, "method": "elicitation/create",
+  "params": {
+    "message": "An AI agent wants to log outreach on lead-1: 'Called Acme'. The agent claims you confirmed this. Type your literal confirmation to proceed; cancel to reject.",
+    "requestedSchema": {
+      "type": "object",
+      "properties": { "confirmation": { "type": "string", "title": "Your confirmation" } },
+      "required": ["confirmation"]
+    }
+  } }
+```
+
+Client returns:
+
+```json
+{ "jsonrpc": "2.0", "id": 99, "result": { "action": "accept", "content": { "confirmation": "yes I called Acme today" } } }
+```
+
+The user's literal text replaces `verification.ref` in the outreach record, and the response carries `confirmed_via: "elicit"` for the SDR audit trail.
+
 ## 4. Troubleshooting
 
 | Problem | Cause | Fix |
@@ -148,20 +346,20 @@ Leadbay connection OK.
 | `No enrichment credits remaining` | Out of quota | Contact Leadbay support to extend quota |
 | 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). |
-| Claude Code can't find Leadbay in a new conversation | MCP server installed at project scope (default before 0.3.0) | Re-run with `--scope user`: `claude mcp remove leadbay && claude mcp add leadbay --scope user --env LEADBAY_TOKEN=… --env LEADBAY_REGION=us -- npx -y @leadbay/mcp@0.3` |
+| Claude Code can't find Leadbay in a new conversation | MCP server installed at project scope (default before 0.3.0) | Re-run with `--scope user`: `claude mcp remove leadbay && claude mcp add leadbay --scope user --env LEADBAY_TOKEN=… --env LEADBAY_REGION=us -- npx -y @leadbay/mcp@0.6` |
 | Agent reports "tool not found" for `refine_prompt` / `adjust_audience` etc. | Pre-0.3.0 install with `LEADBAY_MCP_WRITE` unset (writes were off) | Either re-run `npx @leadbay/mcp install` or remove `LEADBAY_MCP_WRITE=0` from your client config (writes are on by default in 0.3.0+) |
 
 ## 5. Upgrade & rotation
 
-**Upgrade**: change the pinned minor in your config, e.g. `"@leadbay/mcp@0.2"` → `"@leadbay/mcp@0.3"`, then restart the client. **0.3.0 enables composite write tools by default** — see [MIGRATION.md](./MIGRATION.md). See also the [changelog](https://github.com/leadbay/leadclaw/releases).
+**Upgrade**: change the pinned minor in your config, e.g. `"@leadbay/mcp@0.2"` → `"@leadbay/mcp@0.6"`, then restart the client. **0.3.0 enables composite write tools by default** — see [MIGRATION.md](./MIGRATION.md). See also the [changelog](https://github.com/leadbay/leadclaw/releases).
 
-**Rotate token**: re-run `npx -y @leadbay/mcp@0.3 install --email you@yourcompany.com --region us` (or `login`) — 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.
+**Rotate token**: re-run `npx -y @leadbay/mcp@0.6 install --email you@yourcompany.com --region us` (or `login`) — 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 disabling write tools
 
-By default the server exposes the **composite workflow tools** — both reads (`leadbay_pull_leads`, `leadbay_research_lead`, `leadbay_account_status`, `leadbay_recall_ordered_titles`, `leadbay_research_company`, `leadbay_prepare_outreach`) and writes (`leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, `leadbay_refine_prompt`, `leadbay_report_outreach`, `leadbay_adjust_audience`, `leadbay_answer_clarification`, `leadbay_import_leads`). These work well with most prompts.
+By default the server exposes the **composite workflow tools** — both reads (`leadbay_pull_leads`, `leadbay_research_lead`, `leadbay_account_status`, `leadbay_recall_ordered_titles`, `leadbay_research_company`, `leadbay_prepare_outreach`, `leadbay_qualify_status`, `leadbay_list_mappable_fields`) and writes (`leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, `leadbay_refine_prompt`, `leadbay_report_outreach`, `leadbay_adjust_audience`, `leadbay_answer_clarification`, `leadbay_import_leads`, `leadbay_import_and_qualify`). These work well with most prompts.
 
 To **disable the write tools** (run a strictly read-only agent), set `LEADBAY_MCP_WRITE=0`. The server's system prompt will adapt to omit references to those tools.
 
@@ -207,6 +405,14 @@ Suitable for **occasional automation**. **Not** suitable for high-cadence (>5 ca
 
 **Limitation:** the wedge maps domains to leads the crawler already knows. Uncrawled domains land in `not_imported` with `reason: "uncrawled"` — the tool does **not** create new leads for unknown websites; the caller decides what to do (skip, queue for the backend follow-up, etc.).
 
+### Importing + qualifying in one verb (0.5.0)
+
+`leadbay_import_and_qualify` collapses import → AI qualification into a single composite call. Returns per-lead qualification answers + ai_agent_lead_score inline when budget allows; otherwise returns a `qualify_id` UUID handle the agent can pass to `leadbay_qualify_status` later (handle persists 30 days, survives MCP restart). See [MIGRATION.md](./MIGRATION.md#migration-leadbay-mcp-04x--050) for the full worked example (discover → preview → import → qualify_status), JSON shapes, error-code reference, per-tool prereqs, and `not_in_lens` partition semantics.
+
+Companion tool: `leadbay_list_mappable_fields` returns the union of standard CRM fields and this org's custom fields (with `mapping_value` ready for `mappings.fields` paste-in). Optional `for_records` param runs the wizard's preprocess on a sample to attach mapping hints + custom-field name-match candidates in a single call.
+
+
+
 **Requires:** `LEADBAY_MCP_WRITE` not set to `0` (it's ON by default since 0.3.0; or `exposeWrite: true` in OpenClaw); admin role on your Leadbay account; active billing.
 
 Use `dry_run: true` to validate domain formatting and wizard reachability without committing the lead-CRM linking. (The CRM-imports row still appears — only a backend change can remove that.)