@leadbay/mcp 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — @leadbay/mcp
 
+## 0.6.1 — UNRELEASED
+
+**Distribution**: listed in the official MCP Registry as `io.github.leadbay/leadbay-mcp` (auto-published from CI via GitHub OIDC); installable as a Claude Code plugin via `/plugin marketplace add leadbay/leadclaw` then `/plugin install leadbay@leadbay-leadclaw`; submission packets prepared for the Claude.ai connector directory and Anthropic's curated MCPB extension directory.
+
+**Registry verification**: adds `mcpName` to the npm package metadata so the MCP Registry can verify ownership of `io.github.leadbay/leadbay-mcp` against the published `@leadbay/mcp` package.
+
+## 0.6.0 — 2026-05-08
+
+Massive spec-coverage upgrade. Each tool declares **annotations** (`readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`); 17 composites + 12 highest-leverage granulars declare typed `outputSchema` + emit `structuredContent`. New surfaces: `prompts/*` (5 canned slash-commands), `resources/*` (`lead://`, `lens://`, `org://taste-profile`), `notifications/progress` (per-lead streaming on every long-running composite), `notifications/cancelled` → `ToolContext.signal` (bulk-store entries marked `cancelled` so subsequent status polls return `BULK_CANCELLED`), `elicitation/create` (refine_prompt clarification + report_outreach user_confirmed anti-poisoning).
+
+**Hardening**: every `inputSchema` declares `additionalProperties: false`. Runtime conformance test pins `structuredContent` against `outputSchema` for every declarer (drift-catcher). Static-scan audit of every error-hint string asserts each names a recovery action. `report_outreach.verification` rejects extra keys at runtime (closes the SDK's nested-additionalProperties limitation). `score_0_to_10` deprecated alias of `boost_score` removed in 0.7.0.
+
+**Token economy**: pagination payloads carry `has_more` + `next_page`. `research_lead` truncates large payloads with a `truncation_hint`. Per-tool opt-in `response_format: "json" | "markdown"` lets chat-rendering agents pick the cheaper render (research_lead first; pattern reusable). `LEADBAY_DEBUG=1` enables a per-tools/call observability line on stderr.
+
+**DXT → MCPB**: bundle now publishes both `leadbay-X.Y.Z.dxt` (legacy) and `leadbay-X.Y.Z.mcpb` (new Claude Desktop format) for one cycle. Manifest `dxt_version` field stays for backwards-compat with current installers; field rename will follow Anthropic's spec when finalised. The two filenames have identical content; downstream installers can match either glob.
+
+**Versioning + docs**: 0.4.0 / 0.6.0 bumps; README §3a "Spec primitives in action" adds wire-level JSON-RPC transcripts for every primitive; MIGRATION.md 0.5 → 0.6 walkthrough.
+
 ## 0.5.0 — 2026-05-04
 
 ### `leadbay_import_and_qualify` — new composite

package/MIGRATION.md

@@ -1,3 +1,99 @@
+# Migration: leadbay-mcp 0.5.x → 0.6.0 (UNRELEASED)
+
+The "MCP best-practice" upgrade. Five behaviour additions and ONE
+softer-than-it-looks behavior callout. All changes are MCP-spec
+aligned (2025-11-25).
+
+## 1. Tool annotations on every tool
+
+Every tool now declares `annotations: { readOnlyHint, destructiveHint,
+idempotentHint, openWorldHint, title }` in the `tools/list` payload.
+Capable clients (Claude Desktop, Cursor) use these hints to decide
+whether to auto-approve a call or prompt for confirmation. No agent-
+side change required.
+
+## 2. `additionalProperties: false` on every tool's inputSchema
+
+**Behavior callout**: any client that was passing extra unrecognized
+fields will now get a schema rejection. This was a deliberate
+hardening — extra fields were never documented, and the rejection
+closes a prompt-injection surface (the eval doc explicitly endorsed
+this). To migrate: drop the unknown field. The error message names
+the rejected field.
+
+If you discover an unknown field in your call shape, double-check the
+relevant tool's documented `inputSchema`; if you believe a field
+should exist, file an issue.
+
+## 3. `outputSchema` + `structuredContent` on top-5 composites
+
+`leadbay_pull_leads`, `leadbay_research_lead`, `leadbay_account_status`,
+`leadbay_bulk_qualify_leads`, `leadbay_report_outreach` now declare
+`outputSchema` AND emit `structuredContent` on success alongside the
+existing text content. Clients that read structuredContent get the
+typed payload without re-parsing through the LLM. Backwards-compat:
+text content is unchanged.
+
+## 4. `boost_score` on `research_lead.qualification[]`
+
+The qualification entry was previously labelled `score_0_to_10`. The
+actual scale is the discrete `-10|0|10|20` boost (per
+`AiAgentResponse.score`), NOT a 0-10 average. 0.6.0 introduces:
+
+```json
+{
+  "question": "...",
+  "boost_score": 10,
+  "score_scale": "-10|0|10|20",
+  "score_0_to_10": 10,    // DEPRECATED — same value as boost_score
+  "response": "...",
+  "computed_at": "..."
+}
+```
+
+`score_0_to_10` is kept as a deprecated alias for one minor version
+and removed in 0.7.0. Switch to `boost_score` now.
+
+## 5. New spec primitives
+
+The server now advertises and serves:
+
+- **`prompts/*`** — 5 canned slash-commands (`leadbay_daily_check_in`,
+  `leadbay_research_a_domain`, `leadbay_refine_audience`,
+  `leadbay_log_outreach`, `leadbay_qualify_top_n`). Use these from
+  the client UI; agents that read prompts compose workflows
+  automatically.
+- **`resources/*`** — three URI schemes addressable by client:
+  `lead://{uuid}/profile`, `lens://{id}/definition`,
+  `org://taste-profile`. Cache-friendly for capable clients.
+- **`notifications/progress`** — long-running composites (today:
+  `leadbay_bulk_qualify_leads`) stream per-lead progress updates
+  when the client opts in via `_meta.progressToken`.
+- **`notifications/cancelled`** → `ToolContext.signal` — clients
+  that send cancellation now actually stop in-flight work in
+  composites that observe `ctx.signal` (`leadbay_import_and_qualify`,
+  `leadbay_import_leads`, etc.).
+
+Clients without these capabilities negotiate away — backwards-compat
+is preserved.
+
+## 6. Pagination metadata: `has_more` + `next_page`
+
+`leadbay_pull_leads` and `leadbay_discover_leads` payloads now
+include `has_more: boolean` and `next_page: number | null` next to
+the existing `pagination` object. Spec-aligned; agents no longer
+need to compute `page < pages - 1`.
+
+## 7. Truncation steering on `research_lead`
+
+When the response would exceed ~25k characters, the composite now
+emits `truncated: true` plus `truncation_hint: "Pass concise:true to
+filter to hot signals only."`. Load-bearing fields (qualification,
+firmographics, contacts) are never trimmed; only signals.entries get
+trimmed first.
+
+---
+
 # Migration: leadbay-mcp 0.2.x → 0.3.0
 
 This release fixes [product#3504](https://github.com/leadbay/product/issues/3504): the default-installed MCP server's system prompt told the agent to call tools that the server didn't actually expose. Three behavior changes you need to know about.

package/README.md

@@ -1,5 +1,7 @@
 # @leadbay/mcp — Leadbay MCP server
 
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.leadbay%2Fleadbay--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers/io.github.leadbay/leadbay-mcp)
+
 <!--
 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.
@@ -15,12 +17,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.x — what's new**: 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)
 ```
 
@@ -39,6 +43,15 @@ The token is **session-scoped** (full account access, password-equivalent). Trea
 
 **Don't have a Leadbay account?** [Register here](https://wow.leadbay.ai/?register=true).
 
+### Install via the Claude Code plugin marketplace
+
+```text
+/plugin marketplace add leadbay/leadclaw
+/plugin install leadbay@leadbay-leadclaw
+```
+
+Claude Code prompts for your token and region through the plugin's `userConfig`. This is equivalent to the npm/CLI install above; users who already ran `leadbay-mcp login` can reuse that token.
+
 ### Claude Desktop 2026 (DXT)
 
 Claude Desktop 2026 ships the DXT (Desktop Extension) system — the legacy `claude_desktop_config.json` is UI-prefs-only there and gets overwritten by the app. If you're on 2026, **install the `.dxt` bundle** from [Releases](https://github.com/leadbay/leadclaw/releases/latest) (drag-drop into Settings → Extensions). `leadbay-mcp install` detects this and skips the legacy write automatically.
@@ -47,14 +60,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 +85,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 +106,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 +119,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 +131,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 +151,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,14 +357,14 @@ 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