@leadbay/mcp 0.2.1 → 0.3.0

package/dist/bin.js

@@ -3,12 +3,16 @@ import {
   compositeReadTools,
   compositeWriteTools,
   createClient,
+  createDefaultBulkStore,
+  formatLoginError,
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-BGJ6JWIO.js";
+} from "./chunk-NED7ATJI.js";
 
 // src/bin.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
@@ -17,7 +21,44 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-var SERVER_INSTRUCTIONS = "After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.\n\nStart with leadbay_account_status to see the user's state, then leadbay_pull_leads to surface fresh leads. Use leadbay_research_lead to dig into one lead deeply (qualification answers, signals, contacts). When the user wants more leads, narrower audience, refined criteria, or contact enrichment, use the matching composite tool (bulk_qualify_leads / adjust_audience / refine_prompt / enrich_titles) \u2014 they hide lens permissions, region routing, polling, and selection state from you.";
+var VERIFICATION_MANDATE = "After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.";
+var MENTAL_MODEL_PARAGRAPH = "How Leadbay works (mental model): Leadbay is a sales inbox, not a queryable database. Each day the user logs back in, a fresh batch of leads is delivered. Batch size is paced by how many leads the user has actually acted on recently \u2014 some workflows produce a big stream of smaller prospects, others a narrow stream of bigger ones. Pulling more won't produce more; the user acting on leads (outreach, skips, saves) does.";
+function buildScoringParagraph(has) {
+  const base = "Two scoring layers: every lead has a basic `score` (firmographic \u2014 already decent, usually correlates with AI). Roughly the top 10 of each batch are also AI-qualified (targeted web research + qualification questions \u2192 `ai_agent_lead_score`, surfaced as `qualification_summary` on leadbay_pull_leads). Leads past the top ~10 are not worse \u2014 the system is saving resources.";
+  const deepenTools = [];
+  if (has("leadbay_bulk_qualify_leads")) deepenTools.push("leadbay_bulk_qualify_leads for deeper qualification");
+  if (has("leadbay_enrich_titles")) deepenTools.push("leadbay_enrich_titles for contacts");
+  if (deepenTools.length > 0) {
+    return base + ` Call ${deepenTools.join(" or ")} on any lead that looks worth it.`;
+  }
+  return base;
+}
+function buildStartHereParagraph(has) {
+  const base = "Start with leadbay_account_status to see the user's state, then leadbay_pull_leads to surface fresh leads. Use leadbay_research_lead to dig into one lead deeply (qualification answers, signals, contacts).";
+  const compositeNames = ["bulk_qualify_leads", "adjust_audience", "refine_prompt", "enrich_titles"].filter((n) => has(`leadbay_${n}`));
+  if (compositeNames.length > 0) {
+    return base + ` When the user wants more leads, narrower audience, refined criteria, or contact enrichment, use the matching composite tool (${compositeNames.join(" / ")}) \u2014 they hide lens permissions, region routing, polling, and selection state from you.`;
+  }
+  return base + " When the user asks for refinement, contact enrichment, audience changes, or outreach reporting, tell them: those actions require write tools, currently disabled. Re-enable by removing `LEADBAY_MCP_WRITE=0` from your MCP client config and restarting the client. Also: do not promise to log outreach \u2014 the report_outreach tool is not available in this configuration.";
+}
+function buildRhythmParagraph(has) {
+  if (has("leadbay_report_outreach")) {
+    return "Suggested rhythm: a healthy agent pattern is a daily check-in \u2014 pull fresh leads, skim the auto-qualified top, deepen 1-3 promising ones, propose outreach to the user, then leadbay_report_outreach on what actually got sent. If your host supports scheduling, offer to set up a daily run.";
+  }
+  return "Suggested rhythm: a healthy agent pattern is a daily check-in \u2014 pull fresh leads, skim the auto-qualified top, deepen 1-3 promising ones, propose outreach to the user. If your host supports scheduling, offer to set up a daily run.";
+}
+function buildServerInstructions(exposed) {
+  const has = (name) => exposed.has(name);
+  const parts = [];
+  if (has("leadbay_report_outreach")) {
+    parts.push(VERIFICATION_MANDATE);
+  }
+  parts.push(MENTAL_MODEL_PARAGRAPH);
+  parts.push(buildScoringParagraph(has));
+  parts.push(buildStartHereParagraph(has));
+  parts.push(buildRhythmParagraph(has));
+  return parts.join("\n\n");
+}
 function formatErrorForLLM(err) {
   if (err && typeof err === "object" && err.error === true) {
     const parts = [`${err.message}.`, err.hint];
@@ -42,13 +83,6 @@ function toolsListPayload(tools) {
   }));
 }
 function buildServer(client, opts = {}) {
-  const server = new Server(
-    { name: "leadbay", version: "0.2.0" },
-    {
-      capabilities: { tools: {} },
-      instructions: SERVER_INSTRUCTIONS
-    }
-  );
   const exposedTools = [];
   exposedTools.push(...compositeReadTools);
   if (opts.includeWrite) {
@@ -66,6 +100,14 @@ function buildServer(client, opts = {}) {
       toolByName.set(t.name, t);
     }
   }
+  const exposedNames = new Set(toolByName.keys());
+  const server = new Server(
+    { name: "leadbay", version: "0.3.0" },
+    {
+      capabilities: { tools: {} },
+      instructions: buildServerInstructions(exposedNames)
+    }
+  );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: toolsListPayload([...toolByName.values()])
   }));
@@ -85,7 +127,10 @@ function buildServer(client, opts = {}) {
     }
     const args = req.params.arguments ?? {};
     try {
-      const result = await tool.execute(client, args, { logger: opts.logger });
+      const result = await tool.execute(client, args, {
+        logger: opts.logger,
+        bulkTracker: opts.bulkTracker
+      });
       if (result && typeof result === "object" && result.error === true) {
         return {
           content: [
@@ -113,7 +158,7 @@ function buildServer(client, opts = {}) {
 
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -132,15 +177,17 @@ USAGE
   leadbay-mcp --help     Print this help
 
 ENV VARS
-  LEADBAY_TOKEN          (required) Bearer token from https://app.leadbay.ai/settings/api-tokens
+  LEADBAY_TOKEN          (required) Bearer token (run \`leadbay-mcp install\` to mint one).
   LEADBAY_REGION         (optional) "us" or "fr". Auto-detected from /users/me if unset.
   LEADBAY_BASE_URL       (optional) Override API base URL (for staging/dev).
   LEADBAY_MCP_ADVANCED   (optional) Set to "1" to expose granular API tools alongside
                          the composite workflow tools. Most users don't need this.
-  LEADBAY_MCP_WRITE      (optional) Set to "1" to expose write composites (refine_prompt,
-                         report_outreach, adjust_audience, etc.) and write granulars.
-                         Defaults off \u2014 read composites are exposed by default; mutations
-                         require explicit opt-in.
+  LEADBAY_MCP_WRITE      (optional) Default "1" (ON) since 0.3.0: exposes write composites
+                         (refine_prompt, report_outreach, adjust_audience, bulk_qualify_leads,
+                         enrich_titles, answer_clarification, import_leads). Set to "0" /
+                         "false" / "no" / "off" for read-only mode. Note: in 0.2.x, only
+                         "1" turned writes ON; "true" / "yes" / "on" were treated as OFF.
+                         The 0.3.0 parser accepts all those values as truthy. See MIGRATION.md.
   LEADBAY_MOCK           (optional) Set to "1" to serve all responses from on-disk fixtures
                          (no network, no real auth). Useful for agent-author dry-running.
                          GETs are matched against fixture JSON files; POSTs/DELETEs are
@@ -153,7 +200,7 @@ EXAMPLE Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
     "mcpServers": {
       "leadbay": {
         "command": "npx",
-        "args": ["-y", "@leadbay/mcp@0.1"],
+        "args": ["-y", "@leadbay/mcp@0.3"],
         "env": {
           "LEADBAY_TOKEN": "lb_...",
           "LEADBAY_REGION": "us"
@@ -187,9 +234,21 @@ function parseLogLevel(raw) {
   if (raw === "debug" || raw === "info") return raw;
   return "error";
 }
+function parseWriteEnv() {
+  const raw = process.env.LEADBAY_MCP_WRITE;
+  if (raw === void 0 || raw === "") return true;
+  const v = raw.trim().toLowerCase();
+  if (v === "0" || v === "false" || v === "no" || v === "off") return false;
+  if (v === "1" || v === "true" || v === "yes" || v === "on") return true;
+  process.stderr.write(
+    `[leadbay-mcp warn] LEADBAY_MCP_WRITE='${raw}' not recognized; defaulting to ON. Use 1/0.
+`
+  );
+  return true;
+}
 function exitWithTokenError() {
   process.stderr.write(
-    "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Create a token at https://app.leadbay.ai/settings/api-tokens\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
+    "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Run: npx -y @leadbay/mcp install --email <you> --region <us|fr>\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
   );
   process.exit(1);
 }
@@ -293,11 +352,73 @@ function parseFlag(args, name) {
 function hasFlag(args, name) {
   return args.some((a) => a === `--${name}`);
 }
+function resolveDefaultCredentialsPath() {
+  const fs = require_("node:fs");
+  const path = require_("node:path");
+  const legacyPath = path.join(require_("node:os").homedir(), ".leadbay-mcp.json");
+  if (fs.existsSync(legacyPath)) {
+    return { path: legacyPath, legacy: true };
+  }
+  return { path: computeFreshDefaultPath(), legacy: false };
+}
+function checkLoginCollision(existingConfig, email, region) {
+  if (!existingConfig || typeof existingConfig !== "object") {
+    return "existing file is not valid JSON";
+  }
+  const cfg = existingConfig;
+  const existingEmail = typeof cfg.email === "string" && cfg.email.length > 0 ? cfg.email : void 0;
+  const existingRegion = typeof cfg.mcpServers?.leadbay?.env?.LEADBAY_REGION === "string" ? cfg.mcpServers.leadbay.env.LEADBAY_REGION : void 0;
+  if (existingEmail !== void 0 && existingEmail !== email) {
+    return `existing email=${existingEmail} (this login is email=${email})`;
+  }
+  if (existingRegion !== void 0 && existingRegion !== region) {
+    return `existing region=${existingRegion} (this login is region=${region})`;
+  }
+  return null;
+}
+function computeFreshDefaultPath() {
+  const os = require_("node:os");
+  const path = require_("node:path");
+  const home = os.homedir();
+  const xdg = process.env.XDG_CONFIG_HOME;
+  if (xdg && xdg.length > 0) {
+    return path.join(xdg, "leadbay", "credentials.json");
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "leadbay", "credentials.json");
+  }
+  if (process.platform === "win32") {
+    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    return path.join(appdata, "leadbay", "credentials.json");
+  }
+  return path.join(home, ".config", "leadbay", "credentials.json");
+}
 async function runLogin(args) {
   const email = parseFlag(args, "email");
+  const defaultPathPreview = (() => {
+    try {
+      return resolveDefaultCredentialsPath().path;
+    } catch {
+      return "<HOME>/.config/leadbay/credentials.json";
+    }
+  })();
   if (!email) {
     process.stderr.write(
-      "Usage: leadbay-mcp login --email you@example.com [--region us|fr] [--allow-region-fallback] [--write-config PATH] [--quiet]\n  Then enter your password (hidden), or pipe it via stdin / set $LEADBAY_PASSWORD.\n  --region            Pin the backend (us|fr); avoids sending your password to a backend you don't use.\n                      Defaults to $LEADBAY_REGION if set; otherwise asks you to pass --allow-region-fallback.\n  --allow-region-fallback   Try us, then fr (or fr, then us). Your password hits BOTH backends if the\n                            first 401s. Only do this if you're OK with that.\n  --write-config PATH       Write the resulting MCP-client JSON to PATH with 0600 permissions instead\n                            of stdout. Recommended \u2014 keeps the token out of terminal scrollback / CI logs.\n  --quiet             With --write-config, suppress the printed Claude-Code one-liner that includes the token.\n"
+      `Usage: leadbay-mcp login --email you@example.com [--region us|fr] [--allow-region-fallback]
+                        [--write-config PATH] [--unsafe-print-token] [--force] [--quiet]
+  Then enter your password (hidden), or pipe it via stdin / set $LEADBAY_PASSWORD.
+  --region            Pin the backend (us|fr); avoids sending your password to a backend you don't use.
+                      Defaults to $LEADBAY_REGION if set; otherwise asks you to pass --allow-region-fallback.
+  --allow-region-fallback   Try us, then fr (or fr, then us). Your password hits BOTH backends if the
+                            first 401s. Only do this if you're OK with that.
+  Default behavior (0.3.0+): writes the MCP-client JSON to the platform-correct credentials path:
+                            ${defaultPathPreview} (mode 0600).
+  --write-config PATH       Override the default path with PATH (mode 0600).
+  --unsafe-print-token      Print the token to stdout (legacy 0.2.x behavior). Use only for CI flows that
+                            scrape stdout. The token will end up in scrollback / logs.
+  --force                   Overwrite the credentials file even if it already contains a different token/region.
+  --quiet                   With --write-config / default file-write, suppress the printed Claude-Code one-liner.
+`
     );
     return 2;
   }
@@ -326,7 +447,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-PIXZN6N4.js");
+      const { REGIONS } = await import("./dist-YMZYFHZK.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -341,10 +462,11 @@ async function runLogin(args) {
     return 1;
   }
   const config = {
+    email,
     mcpServers: {
       leadbay: {
         command: "npx",
-        args: ["-y", "@leadbay/mcp@0.2"],
+        args: ["-y", "@leadbay/mcp@0.3"],
         env: {
           LEADBAY_TOKEN: result.token,
           LEADBAY_REGION: result.region
@@ -354,61 +476,150 @@ async function runLogin(args) {
   };
   const writeConfigPath = parseFlag(args, "write-config");
   const quiet = hasFlag(args, "quiet");
+  const force = hasFlag(args, "force");
+  const unsafePrint = hasFlag(args, "unsafe-print-token");
+  const printTokenLegacy = hasFlag(args, "print-token");
+  if (printTokenLegacy && !unsafePrint) {
+    process.stderr.write(
+      "[leadbay-mcp warn] --print-token is deprecated since 0.3.0; renaming to --unsafe-print-token. The flag still works for one release.\n"
+    );
+  }
+  const printToStdout = unsafePrint || printTokenLegacy;
+  if (printToStdout) {
+    process.stderr.write(
+      `
+Logged in to ${result.region.toUpperCase()} backend (${result.verified ? "verified" : "UNVERIFIED \u2014 check your email"}).
+
+\u26A0\uFE0F  About to print your bearer token to STDOUT.
+   Treat it like a password. Do NOT paste this into chat, screen-share, or commit it.
+   For safer handling, re-run without --unsafe-print-token (default writes a 0600 file).
+
+Add this to your MCP client config:
+
+`
+    );
+    process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+    process.stderr.write(
+      `
+Or for Claude Code (token included \u2014 same warning applies):
+
+  claude mcp add leadbay --scope user \\
+    --env LEADBAY_TOKEN=${result.token} \\
+    --env LEADBAY_REGION=${result.region} \\
+    -- npx -y @leadbay/mcp@0.3
+
+Restart your MCP client to pick up the new server.
+`
+    );
+    return 0;
+  }
+  let targetPath;
+  let usingLegacyPath = false;
   if (writeConfigPath) {
-    const { writeFileSync, chmodSync } = await import("fs");
-    writeFileSync(writeConfigPath, JSON.stringify(config, null, 2) + "\n", {
+    targetPath = writeConfigPath;
+  } else {
+    const resolved = resolveDefaultCredentialsPath();
+    targetPath = resolved.path;
+    usingLegacyPath = resolved.legacy;
+  }
+  try {
+    const { existsSync, readFileSync } = await import("fs");
+    if (existsSync(targetPath) && !force) {
+      let existing;
+      try {
+        existing = JSON.parse(readFileSync(targetPath, "utf8"));
+      } catch {
+        process.stderr.write(
+          `leadbay-mcp login: ${targetPath} exists but is not valid JSON. Pass --force to overwrite.
+`
+        );
+        return 1;
+      }
+      const collision = checkLoginCollision(existing, email, result.region);
+      if (collision) {
+        process.stderr.write(
+          `leadbay-mcp login: refusing to overwrite ${targetPath} \u2014 ${collision}.
+  Pass --force to overwrite, or --write-config /some/other/path.json to keep both.
+`
+        );
+        return 1;
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`leadbay-mcp login: ${err?.message ?? String(err)}
+`);
+    return 1;
+  }
+  let actualMode;
+  try {
+    const { writeFileSync, chmodSync, mkdirSync, renameSync, statSync, unlinkSync } = await import("fs");
+    const { dirname } = await import("path");
+    mkdirSync(dirname(targetPath), { recursive: true });
+    const tmp = targetPath + ".tmp." + process.pid;
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", {
       encoding: "utf8",
       mode: 384
     });
     try {
-      chmodSync(writeConfigPath, 384);
+      chmodSync(tmp, 384);
     } catch {
     }
-    process.stderr.write(
-      `
-Logged in to ${result.region.toUpperCase()} backend (${result.verified ? "verified" : "UNVERIFIED \u2014 check your email"}).
-Wrote MCP config to ${writeConfigPath} (mode 0600). Token NOT printed to terminal.
-`
-    );
-    if (!quiet) {
+    renameSync(tmp, targetPath);
+    try {
+      actualMode = statSync(targetPath).mode & 511;
+    } catch {
+    }
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+  } catch (err) {
+    const code = err?.code;
+    if (code === "EACCES" || code === "EROFS" || code === "ENOENT") {
       process.stderr.write(
-        `
-For Claude Code, run:
-  claude mcp add leadbay --env LEADBAY_TOKEN=$(jq -r .mcpServers.leadbay.env.LEADBAY_TOKEN ${writeConfigPath}) --env LEADBAY_REGION=${result.region} -- npx -y @leadbay/mcp@0.2
+        `leadbay-mcp login: cannot write ${targetPath} (${code}).
+  Use --write-config /tmp/leadbay-mcp.json (or another writable path),
+  or --unsafe-print-token (last resort \u2014 token in stdout).
 `
       );
+      return 1;
     }
-    process.stderr.write(
-      `
-TREAT THE TOKEN AS A SECRET. It grants full access to your Leadbay account.
-Delete the config file once your MCP client has it loaded, or keep it 0600.
-`
-    );
-    return 0;
+    process.stderr.write(`leadbay-mcp login: ${err?.message ?? String(err)}
+`);
+    return 1;
   }
+  const modeNote = actualMode === 384 ? "(mode 0600)" : actualMode !== void 0 ? `(mode 0${actualMode.toString(8)} \u2014 chmod 0600 failed; treat the file as sensitive)` : "(mode unknown)";
   process.stderr.write(
     `
 Logged in to ${result.region.toUpperCase()} backend (${result.verified ? "verified" : "UNVERIFIED \u2014 check your email"}).
-
-\u26A0\uFE0F  About to print your bearer token to STDOUT.
-   Treat it like a password. Do NOT paste this into chat, screen-share, or commit it.
-   For safer handling, re-run with --write-config /path/to/config.json (writes 0600).
-
-Add this to your MCP client config:
-
+Wrote MCP config to ${targetPath} ${modeNote}. Token NOT printed to terminal.
 `
   );
-  process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+  if (usingLegacyPath) {
+    const newPath = computeFreshDefaultPath();
+    process.stderr.write(
+      `
+[leadbay-mcp note] Used the legacy 0.2.x path ${targetPath}. The 0.3.0 default is ${newPath}.
+  Move the file there at your convenience (no code change required \u2014 both paths are read).
+`
+    );
+  }
+  if (!quiet) {
+    const quotedPath = `'${targetPath.replace(/'/g, `'\\''`)}'`;
+    process.stderr.write(
+      `
+For Claude Code, run:
+  claude mcp add leadbay --scope user \\
+    --env LEADBAY_TOKEN=$(jq -r .mcpServers.leadbay.env.LEADBAY_TOKEN ${quotedPath}) \\
+    --env LEADBAY_REGION=${result.region} \\
+    -- npx -y @leadbay/mcp@0.3
+`
+    );
+  }
   process.stderr.write(
     `
-Or for Claude Code (token included \u2014 same warning applies):
-
-  claude mcp add leadbay \\
-    --env LEADBAY_TOKEN=${result.token} \\
-    --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.2
-
-Restart your MCP client to pick up the new server.
+TREAT THE TOKEN AS A SECRET. It grants full access to your Leadbay account.
+Delete the config file once your MCP client has it loaded, or keep it 0600.
 `
   );
   return 0;
@@ -444,9 +655,7 @@ async function loginAt(baseUrl, email, password) {
             }
           }
           reject(
-            new Error(
-              `login failed (${res.statusCode}) at ${baseUrl}: ${raw.slice(0, 200)}`
-            )
+            new Error(formatLoginError(res.statusCode ?? 0, raw, baseUrl))
           );
         });
       }
@@ -456,6 +665,31 @@ async function loginAt(baseUrl, email, password) {
     r.end();
   });
 }
+function detectClaudeDesktopMode(claudeSupportDir) {
+  const { existsSync, readFileSync } = require_("node:fs");
+  const { join } = require_("node:path");
+  const markers = [];
+  const legacy = existsSync(join(claudeSupportDir, "claude_desktop_config.json"));
+  if (existsSync(join(claudeSupportDir, "Claude Extensions"))) {
+    markers.push("Claude Extensions/");
+  }
+  if (existsSync(join(claudeSupportDir, "extensions-installations.json"))) {
+    markers.push("extensions-installations.json");
+  }
+  const cfgPath = join(claudeSupportDir, "config.json");
+  if (existsSync(cfgPath)) {
+    try {
+      const raw = readFileSync(cfgPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") {
+        const hasDxtKey = Object.keys(parsed).some((k) => k.startsWith("dxt:"));
+        if (hasDxtKey) markers.push("config.json (dxt:* keys)");
+      }
+    } catch {
+    }
+  }
+  return { legacy, dxt: markers.length > 0, markers };
+}
 async function detectClients() {
   const out = [];
   const { existsSync } = await import("fs");
@@ -476,9 +710,16 @@ async function detectClients() {
     out.push({ id: "claude-code", label: "Claude Code", detail: `${claudeBin} mcp add ...` });
   }
   const home = os.homedir();
-  const cdPath = process.platform === "win32" ? `${process.env.APPDATA ?? `${home}\\AppData\\Roaming`}\\Claude\\claude_desktop_config.json` : process.platform === "darwin" ? `${home}/Library/Application Support/Claude/claude_desktop_config.json` : `${home}/.config/Claude/claude_desktop_config.json`;
-  if (existsSync(cdPath)) {
-    out.push({ id: "claude-desktop", label: "Claude Desktop", detail: cdPath });
+  const claudeSupportDir = process.platform === "win32" ? `${process.env.APPDATA ?? `${home}\\AppData\\Roaming`}\\Claude` : process.platform === "darwin" ? `${home}/Library/Application Support/Claude` : `${home}/.config/Claude`;
+  const cdPath = process.platform === "win32" ? `${claudeSupportDir}\\claude_desktop_config.json` : `${claudeSupportDir}/claude_desktop_config.json`;
+  const mode = detectClaudeDesktopMode(claudeSupportDir);
+  if (mode.legacy || mode.dxt) {
+    out.push({
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      detail: cdPath,
+      mode
+    });
   }
   const cursorPath = process.platform === "win32" ? `${home}\\.cursor\\mcp.json` : `${home}/.cursor/mcp.json`;
   if (existsSync(cursorPath)) {
@@ -533,19 +774,25 @@ async function readChoice(prompt, def = true) {
     process.stdin.on("data", onData);
   });
 }
-async function installInClaudeCode(token, region, includeWrite) {
-  const cp = await import("child_process");
+function buildClaudeCodeAddArgs(token, region, includeWrite) {
   const args = [
     "mcp",
     "add",
     "leadbay",
+    "--scope",
+    "user",
     "--env",
     `LEADBAY_TOKEN=${token}`,
     "--env",
     `LEADBAY_REGION=${region}`
   ];
-  if (includeWrite) args.push("--env", `LEADBAY_MCP_WRITE=1`);
-  args.push("--", "npx", "-y", "@leadbay/mcp@0.2");
+  if (!includeWrite) args.push("--env", `LEADBAY_MCP_WRITE=0`);
+  args.push("--", "npx", "-y", "@leadbay/mcp@0.3");
+  return args;
+}
+async function installInClaudeCode(token, region, includeWrite) {
+  const cp = await import("child_process");
+  const args = buildClaudeCodeAddArgs(token, region, includeWrite);
   return await new Promise((resolve) => {
     const child = cp.spawn("claude", args, { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
@@ -585,10 +832,10 @@ async function installInJsonConfig(configPath, token, region, includeWrite) {
       LEADBAY_TOKEN: token,
       LEADBAY_REGION: region
     };
-    if (includeWrite) env.LEADBAY_MCP_WRITE = "1";
+    if (!includeWrite) env.LEADBAY_MCP_WRITE = "0";
     parsed.mcpServers.leadbay = {
       command: "npx",
-      args: ["-y", "@leadbay/mcp@0.2"],
+      args: ["-y", "@leadbay/mcp@0.3"],
       env
     };
     const tmp = configPath + ".tmp";
@@ -611,10 +858,15 @@ async function runInstall(args) {
   const email = parseFlag(args, "email");
   if (!email) {
     process.stderr.write(
-      "Usage: leadbay-mcp install --email you@example.com [--region us|fr]\n                          [--allow-region-fallback] [--include-write]\n                          [--target claude-code,claude-desktop,cursor] [--yes]\n  Mints a token AND registers the MCP server with your installed clients.\n  --target            Comma-separated subset; default = all detected.\n  --include-write     Enable LEADBAY_MCP_WRITE=1 (composite write tools \u2014 refine_prompt,\n                      report_outreach, adjust_audience). Off by default; off means the\n                      agent can read your Leadbay account but not mutate it.\n  --yes               Don't ask before installing into each detected client.\n"
+      "Usage: leadbay-mcp install --email you@example.com [--region us|fr]\n                          [--allow-region-fallback] [--no-write]\n                          [--target claude-code,claude-desktop,cursor]\n                          [--yes] [--force-legacy]\n  Mints a token AND registers the MCP server with your installed clients (at user scope).\n  --target            Comma-separated subset; default = all detected.\n  --no-write          Disable composite write tools (refine_prompt, report_outreach,\n                      adjust_audience, etc.). They are ON by default since 0.3.0;\n                      pass --no-write for read-only agents.\n  --include-write     (deprecated since 0.3.0; now a no-op \u2014 writes are on by default).\n  --yes               Don't ask before installing into each detected client.\n  --force-legacy      Write to claude_desktop_config.json even when Claude Desktop 2026\n                      DXT is detected. Not recommended \u2014 the app overwrites that file.\n                      Use the .dxt bundle instead: https://github.com/leadbay/leadclaw/releases\n"
     );
     return 2;
   }
+  if (hasFlag(args, "include-write")) {
+    process.stderr.write(
+      "[leadbay-mcp warn] --include-write is the default since 0.3.0; the flag is now a no-op.\n  Composite write tools (refine_prompt, report_outreach, adjust_audience, etc.) are ON by default.\n  Pass --no-write to install in read-only mode.\n\n"
+    );
+  }
   const regionArg = parseFlag(args, "region");
   const regionEnv = process.env.LEADBAY_REGION;
   const allowFallback = hasFlag(args, "allow-region-fallback");
@@ -657,9 +909,27 @@ async function runInstall(args) {
 leadbay-mcp install \u2014 detected MCP clients on this machine:
 `
   );
-  for (const c of chosen) process.stderr.write(`  \u2022 ${c.label.padEnd(16)} ${c.detail}
+  for (const c of chosen) {
+    const dxtSuffix = c.mode?.dxt ? "  [DXT \u2014 legacy write will be skipped]" : "";
+    process.stderr.write(`  \u2022 ${c.label.padEnd(16)} ${c.detail}${dxtSuffix}
 `);
+  }
   process.stderr.write("\n");
+  const forceLegacy = hasFlag(args, "force-legacy");
+  const hasDxtClient = chosen.some((c) => c.id === "claude-desktop" && c.mode?.dxt);
+  if (hasDxtClient && !forceLegacy) {
+    const dxtClient = chosen.find((c) => c.id === "claude-desktop" && c.mode?.dxt);
+    process.stderr.write(
+      `\u26A0\uFE0F  Claude Desktop 2026 DXT detected (markers: ${dxtClient.mode.markers.join(", ")}).
+    The legacy claude_desktop_config.json is UI-prefs-only in this version \u2014
+    Claude Desktop will overwrite any \`mcpServers\` block written there.
+    Install the Leadbay .dxt instead (drag-drop into Settings \u2192 Extensions):
+      https://github.com/leadbay/leadclaw/releases/latest
+    Override with --force-legacy to write the legacy file anyway (not recommended).
+
+`
+    );
+  }
   const password = await readPassword();
   if (!password) {
     process.stderr.write("leadbay-mcp install: empty password\n");
@@ -669,7 +939,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-PIXZN6N4.js");
+      const { REGIONS } = await import("./dist-YMZYFHZK.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;
@@ -686,15 +956,28 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   process.stderr.write(`Logged in to ${region.toUpperCase()} backend.
 
 `);
-  const includeWrite = hasFlag(args, "include-write");
-  if (!includeWrite) {
+  const includeWrite = !hasFlag(args, "no-write");
+  if (includeWrite) {
+    process.stderr.write(
+      "Composite write tools ENABLED (bulk_qualify_leads, enrich_titles, refine_prompt,\n  report_outreach, adjust_audience, answer_clarification, import_leads).\n  To disable: set LEADBAY_MCP_WRITE=0 in the env block, or re-run install with --no-write.\n\n"
+    );
+  } else {
     process.stderr.write(
-      "Note: write tools (refine_prompt, report_outreach, adjust_audience, etc.) are NOT enabled.\n      Re-run with --include-write to enable them.\n\n"
+      "Composite write tools DISABLED (read-only agent). Re-run without --no-write to enable.\n\n"
     );
   }
   const skipPrompts = hasFlag(args, "yes");
   const results = [];
   for (const c of chosen) {
+    if (c.id === "claude-desktop" && c.mode?.dxt && !forceLegacy) {
+      results.push({
+        id: c.id,
+        label: c.label,
+        ok: false,
+        message: "skipped (DXT detected \u2014 install the .dxt bundle instead)"
+      });
+      continue;
+    }
     const ok = skipPrompts || await readChoice(`Install into ${c.label} (${c.detail})?`, true);
     if (!ok) {
       results.push({ id: c.id, label: c.label, ok: false, message: "skipped by user" });
@@ -719,9 +1002,9 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   process.stderr.write(
     `
 The token was written into client config files but never printed to your terminal.
-Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.2 doctor
+Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.3 doctor
 Restart your MCP client(s) to pick up the new server.
-If you ever leak the token, log in to app.leadbay.ai again to invalidate the prior session.
+If you ever leak the token, run \`leadbay-mcp login --email <you> --region <us|fr>\` to mint a fresh one (which invalidates the prior session).
 `
   );
   return anyOk ? 0 : 1;
@@ -794,11 +1077,17 @@ async function main() {
   const logger = makeStderrLogger(parseLogLevel(process.env.LEADBAY_LOG_LEVEL));
   const client = await resolveClientFromEnv(logger);
   const includeAdvanced = process.env.LEADBAY_MCP_ADVANCED === "1";
-  const includeWrite = process.env.LEADBAY_MCP_WRITE === "1";
-  const server = buildServer(client, { includeAdvanced, includeWrite, logger });
+  const includeWrite = parseWriteEnv();
+  const bulkTracker = await createDefaultBulkStore({ logger });
+  const server = buildServer(client, {
+    includeAdvanced,
+    includeWrite,
+    logger,
+    bulkTracker
+  });
   const transport = new StdioServerTransport();
   logger.info?.(
-    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl})`
+    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability})`
   );
   await server.connect(transport);
 }
@@ -806,8 +1095,8 @@ var isEntrypoint = (() => {
   try {
     const entry = process.argv[1];
     if (!entry) return false;
-    const url = new URL(import.meta.url);
-    return url.pathname === entry || url.pathname.endsWith(entry);
+    const self = fileURLToPath(import.meta.url);
+    return realpathSync(self) === realpathSync(entry);
   } catch {
     return false;
   }
@@ -820,5 +1109,11 @@ if (isEntrypoint) {
   });
 }
 export {
-  resolveClientFromEnv
+  buildClaudeCodeAddArgs,
+  checkLoginCollision,
+  computeFreshDefaultPath,
+  detectClaudeDesktopMode,
+  parseWriteEnv,
+  resolveClientFromEnv,
+  resolveDefaultCredentialsPath
 };