@leadbay/mcp 0.23.5 → 0.23.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog — @leadbay/mcp
 
+## 0.23.6 — 2026-06-25
+
+Geographic filter on Discover lenses (product#3759).
+
+- **`leadbay_new_lens` / `leadbay_adjust_audience`** now accept `locations` / `exclude_locations` — a geographic dimension on the Discover lens, mirroring the sector path. Free text (`["Indre-et-Loire"]`, `["Texas"]`) auto-resolves via `/geo/search`, or pass admin-area ids directly. Resolution happens first: ambiguous/unresolved text returns `ambiguous_locations` and the lens is **not** mutated (no half-built lens). Resolved ids merge into the lens filter as a `location_ids` criterion. Unblocks the "scope a territory → net-new accounts there" cockpit workflow — geography was previously settable only on the Monitor side.
+
 ## 0.23.3 — 2026-06-24
 
 - **Release plumbing only** — no functional change. First release on the updated CI that also publishes fixed-name `leadbay-latest.dxt` / `.mcpb` assets, so the docs can link a stable `…/releases/latest/download/leadbay-latest.dxt` that always resolves to the current version.

package/dist/bin.js

@@ -5804,7 +5804,7 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 `;
     leadbay_adjust_audience = `## WHEN TO USE
 
-Trigger phrases: "narrow the audience to <sector>", "add <sector> to my <name> lens", "remove <sector> from this lens", "only show me companies of <size>", "stop including <sector>", "broaden this lens to also include <sector>".
+Trigger phrases: "narrow the audience to <sector>", "add <sector> to my <name> lens", "remove <sector> from this lens", "only show me companies of <size>", "stop including <sector>", "broaden this lens to also include <sector>", "restrict this lens to <city/d\xE9partement/r\xE9gion/state>", "only companies in <place>", "exclude <region> from this lens".
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
@@ -5815,7 +5815,7 @@ Prefer when: user wants to change an EXISTING lens's sectors/sizes. If the user
 Examples that SHOULD invoke this tool:
 - "Add fintech to my Joinery lens."
 - "Narrow my audience to manufacturing companies, 50\u2013500 people."
-- "Stop including retail in this lens."
+- "Restrict my rep's lens to Indre-et-Loire."
 
 Examples that should NOT invoke this tool (sound similar, route elsewhere):
 - "Create a lens called Joinery for fintech."
@@ -5824,9 +5824,10 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 ## RENDER (quick)
 
-On \`applied\`: confirm the lens edited (name) + the sectors/sizes added as
-chips. On \`ambiguous_sectors\` / \`ambiguous_lens\` / \`lens_not_found\`: surface
-the candidates and ask the user to pick, then re-call with the id/exact name.
+On \`applied\`: confirm the lens edited (name) + the sectors/sizes/locations
+added as chips. On \`ambiguous_sectors\` / \`ambiguous_locations\` /
+\`ambiguous_lens\` / \`lens_not_found\`: surface the candidates and ask the user
+to pick, then re-call with the id/exact name.
 
 ---
 
@@ -5834,7 +5835,9 @@ Restrict (or expand) the lens audience by sector / size. Free-text sectors are a
 
 **Targeting a lens \u2014 READ THIS.** By default this edits the user's ACTIVE lens. **If the user names a lens** ("add fintech to my **Joinery** lens", "in my Nordics lens, exclude retail"), you MUST pass \`lensName\` with that name (\`lensName:"Joinery"\`). Do NOT silently edit the active lens when a different one was named \u2014 that corrupts the wrong audience and is a top friction source. The name resolves against the user's lenses (case-insensitive, exact then unique-substring); it is edit-only and does NOT change which lens is active. An unmatched name returns \`status:"lens_not_found"\` with the lens list, and a name matching several returns \`status:"ambiguous_lens"\` with the candidates \u2014 surface them and re-call with the exact \`lensName\` or a \`lensId\`. Use \`leadbay_my_lenses\` if the user first wants to SEE or SWITCH lenses. To CREATE a brand-new lens, use \`leadbay_new_lens\` \u2014 not this tool.
 
-WHEN TO USE: when the user wants to see different kinds of leads (sector / size / etc.).
+**Geography \u2014 scope a sales territory.** Pass \`locations\` (free text like \`["Indre-et-Loire"]\`, \`["Bavaria"]\`, \`["Austin"]\`, or admin-area ids) to restrict the lens to a region, and \`exclude_locations\` to carve one out. Free text auto-resolves via \`/geo/search\` across every admin level \u2014 city, county, *d\xE9partement*, *r\xE9gion*, state, country. Place names go in \`locations\`, **never** in \`sectors\` or \`refine_prompt\`. Unresolved/ambiguous text returns \`status:"ambiguous_locations"\` with candidates \u2014 surface them and re-call the chosen id via the SAME axis it came from: an INCLUDE pick \u2192 \`location_ids\`; an EXCLUDE pick \u2192 \`exclude_locations\` (**NOT** \`location_ids\`, which would include the area the user asked to exclude). The returned \`message\` names the right param per text. This is how a director scopes a rep's territory and then asks for net-new accounts there.
+
+WHEN TO USE: when the user wants to see different kinds of leads (sector / size / geography / etc.).
 
 WHEN NOT TO USE: to refine BEYOND firmographics \u2014 that's leadbay_refine_prompt.
 
@@ -7382,7 +7385,7 @@ invent a tool that doesn't exist.
 `;
     leadbay_new_lens = `## WHEN TO USE
 
-Trigger phrases: "create a lens", "create a new lens called <name>", "create a lens specialized in/into <X>", "make me a new audience for <X>", "set up a lens for <sector>", "new lens named <name>", "I want a lens just for <X>".
+Trigger phrases: "create a lens", "create a new lens called <name>", "create a lens specialized in/into <X>", "make me a new audience for <X>", "set up a lens for <sector>", "new lens named <name>", "I want a lens just for <X>", "create a lens for net-new accounts in <place>", "a lens scoped to <territory>".
 
 **Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
 
@@ -7393,7 +7396,7 @@ Prefer when: user wants a brand-new lens (create/make/set up, often 'specialized
 Examples that SHOULD invoke this tool:
 - "Create a lens called Joinery for the fintech sector."
 - "Make me a new audience for healthcare companies, 30\u2013300 people."
-- "Set up a new lens named Nordics SaaS."
+- "Create a lens for net-new accounts in Indre-et-Loire."
 
 Examples that should NOT invoke this tool (sound similar, route elsewhere):
 - "Add fintech to my Joinery lens."
@@ -7406,7 +7409,8 @@ On \`preview\` (default \u2014 NOTHING created yet): show the lens that WILL be
 created (name + resolved sectors/sizes as chips) and ASK the user to confirm
 via ask_user_input_v0 ("Create this lens?" / "Change something"). Only on
 "yes" re-call with confirm:true. On \`created\`: confirm "Created **<name>**."
-On \`ambiguous_sectors\`: surface the candidate sectors to pick from.
+On \`ambiguous_sectors\` / \`ambiguous_locations\`: surface the candidates to
+pick from.
 
 ---
 
@@ -7416,6 +7420,8 @@ Create a brand-new lens (saved audience) and apply its sector/size criteria. Clo
 
 **Sectors resolve first.** Free-text \`sectors\`/\`exclude_sectors\` are auto-resolved against the taxonomy. If any don't resolve, the tool returns \`status:"ambiguous_sectors"\` with the candidates and **does NOT create the lens** \u2014 so re-calling after picking the right sector won't leave orphan half-built lenses. To discover valid sector labels up front, use \`leadbay_list_sectors\`.
 
+**Geography \u2014 scope a territory.** Pass \`locations\` (free text like \`["Indre-et-Loire"]\`, \`["Bavaria"]\`, or admin-area ids) to scope the lens to a sales territory, and \`exclude_locations\` to carve one out. Free text auto-resolves via \`/geo/search\` across every admin level (city / county / *d\xE9partement* / *r\xE9gion* / state / country). Like sectors, locations resolve BEFORE the lens is created \u2014 unresolved/ambiguous text returns \`status:"ambiguous_locations"\` with candidates and **does NOT create the lens**. Re-call the chosen id via the SAME axis it came from: an INCLUDE pick \u2192 \`locations\`; an EXCLUDE pick \u2192 \`exclude_locations\` (**NOT** \`locations\`, which would include the area the user asked to exclude). This is how a director spins up a lens for a rep's zone to surface net-new accounts there.
+
 **Does not switch the active lens.** The new lens is created but the user stays on their current one. Offer \`leadbay_my_lenses(switchToLensId=<new id>)\` as a next step if they want to start pulling from it.
 
 WHEN TO USE: when the user wants a NEW lens. Canonical phrasings: "create a lens called X", "make a new audience for Y", "set up a lens for <sector>".
@@ -20616,7 +20622,7 @@ async function resolveLensByName(client, name) {
     return { ok: false, reason: "ambiguous", matches: partial };
   return { ok: false, reason: "not_found", lenses: all };
 }
-function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
+function mergeFilter(current, toAddSectors, toExcludeSectors, sizes, toAddLocations = [], toExcludeLocations = []) {
   const items = current?.lens_filter?.items ?? [];
   const item = items[0] ?? { criteria: [] };
   const criteria = item.criteria ? [...item.criteria] : [];
@@ -20648,6 +20654,34 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
       });
     }
   }
+  if (toAddLocations.length > 0) {
+    const idx = criteria.findIndex((c) => c.type === "location_ids" && !c.is_excluded);
+    if (idx >= 0) {
+      const cur = criteria[idx];
+      const merged = Array.from(/* @__PURE__ */ new Set([...cur.locations ?? [], ...toAddLocations]));
+      criteria[idx] = { ...cur, locations: merged };
+    } else {
+      criteria.push({
+        type: "location_ids",
+        is_excluded: false,
+        locations: toAddLocations
+      });
+    }
+  }
+  if (toExcludeLocations.length > 0) {
+    const idx = criteria.findIndex((c) => c.type === "location_ids" && c.is_excluded);
+    if (idx >= 0) {
+      const cur = criteria[idx];
+      const merged = Array.from(/* @__PURE__ */ new Set([...cur.locations ?? [], ...toExcludeLocations]));
+      criteria[idx] = { ...cur, locations: merged };
+    } else {
+      criteria.push({
+        type: "location_ids",
+        is_excluded: true,
+        locations: toExcludeLocations
+      });
+    }
+  }
   if (sizes && sizes.length > 0) {
     const normalizedSizes = sizes.map((s) => ({
       min: s.min ?? 0,
@@ -20672,6 +20706,7 @@ var adjustAudience;
 var init_adjust_audience = __esm({
   "../core/dist/composite/adjust-audience.js"() {
     "use strict";
+    init_geo_helpers();
     init_tool_descriptions_generated();
     adjustAudience = {
       name: "leadbay_adjust_audience",
@@ -20713,6 +20748,21 @@ var init_adjust_audience = __esm({
             },
             description: "Company size buckets, e.g. [{min:30,max:300}]"
           },
+          locations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Geographic scope \u2014 free text (e.g. ['Indre-et-Loire', 'Bavaria', 'Austin']) or admin-area ids. Auto-resolved via /geo/search across all admin levels (city / county / d\xE9partement / r\xE9gion / state / country). Place names go HERE, never in sectors/keywords."
+          },
+          location_ids: {
+            type: "array",
+            items: { type: "string" },
+            description: "Explicit admin-area ids (skips /geo/search resolution)"
+          },
+          exclude_locations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Locations to exclude (free text or ids)"
+          },
           lensId: { type: "number", description: "Lens id (escape hatch)" },
           lensName: {
             type: "string",
@@ -20731,17 +20781,22 @@ var init_adjust_audience = __esm({
       },
       outputSchema: {
         type: "object",
-        description: "Return shapes: 'applied' on success; 'ambiguous_sectors' when free-text sectors matched multiple candidates (re-call with sector_ids); 'lens_not_found' / 'ambiguous_lens' when a lensName didn't resolve to exactly one lens (re-call with lensId or an exact lensName).",
+        description: "Return shapes: 'applied' on success; 'ambiguous_sectors' when free-text sectors matched multiple candidates (re-call with sector_ids); 'ambiguous_locations' when free-text locations didn't resolve to one area \u2014 re-call with the chosen id via the SAME axis it came from (an include pick \u2192 location_ids; an EXCLUDE pick \u2192 exclude_locations, NOT location_ids, which would include it); 'lens_not_found' / 'ambiguous_lens' when a lensName didn't resolve to exactly one lens (re-call with lensId or an exact lensName).",
         properties: {
           status: {
             type: "string",
-            description: "'applied', 'ambiguous_sectors', 'lens_not_found', or 'ambiguous_lens'."
+            description: "'applied', 'ambiguous_sectors', 'ambiguous_locations', 'lens_not_found', or 'ambiguous_lens'."
           },
           sector_ambiguities: {
             type: "array",
             description: "Per ambiguous text: {sector_text, matches:[{id, name, score}]}. Agent picks an id and re-calls.",
             items: { type: "object" }
           },
+          location_ambiguities: {
+            type: "array",
+            description: "On 'ambiguous_locations': per text {location_text, matches:[{id, name, country, level, score}]}. Agent picks an id and re-calls via the SAME axis the text came from \u2014 an include text \u2192 location_ids; a text from exclude_locations \u2192 exclude_locations (NOT location_ids, which would include the area the user asked to exclude). The `message` field names the correct param per text.",
+            items: { type: "object" }
+          },
           lenses: {
             type: "array",
             description: "On 'lens_not_found': the user's lenses [{id, name}] to pick from.",
@@ -20825,9 +20880,45 @@ var init_adjust_audience = __esm({
             message: parts.join(" ")
           };
         }
+        const includeLocTexts = [
+          ...params.locations ?? [],
+          ...params.location_ids ?? []
+        ];
+        const excludeLocTexts = params.exclude_locations ?? [];
+        const includeLocRes = await resolveLocations(client, includeLocTexts);
+        const excludeLocRes = await resolveLocations(client, excludeLocTexts);
+        const locAmbiguities = [
+          ...includeLocRes.ambiguities,
+          ...excludeLocRes.ambiguities
+        ];
+        if (locAmbiguities.length > 0) {
+          const incMatch = includeLocRes.ambiguities.filter((a) => a.matches.length > 0);
+          const incNone = includeLocRes.ambiguities.filter((a) => a.matches.length === 0);
+          const excMatch = excludeLocRes.ambiguities.filter((a) => a.matches.length > 0);
+          const excNone = excludeLocRes.ambiguities.filter((a) => a.matches.length === 0);
+          const quote = (as) => as.map((a) => `"${a.location_text}"`).join(", ");
+          const parts = [];
+          if (incNone.length > 0) {
+            parts.push(`Couldn't find a location matching ${quote(incNone)}. Ask the user to rephrase, then re-call with location_ids=...`);
+          }
+          if (incMatch.length > 0) {
+            parts.push(`${quote(incMatch)} matched multiple areas. Pick from the matches and re-call with location_ids=...`);
+          }
+          if (excNone.length > 0) {
+            parts.push(`Couldn't find a location to exclude matching ${quote(excNone)}. Ask the user to rephrase, then re-call with exclude_locations=... (the chosen id).`);
+          }
+          if (excMatch.length > 0) {
+            parts.push(`${quote(excMatch)} (to exclude) matched multiple areas. Pick from the matches and re-call with exclude_locations=... (the chosen id) \u2014 NOT location_ids, which would include it.`);
+          }
+          return {
+            status: "ambiguous_locations",
+            location_ambiguities: locAmbiguities,
+            message: parts.join(" ")
+          };
+        }
         const lens = await client.request("GET", `/lenses/${startingLensId}`);
         const currentFilter = await client.request("GET", `/lenses/${startingLensId}/filter`);
-        const merged = mergeFilter(currentFilter, includeRes.resolved, excludeRes.resolved, params.sizes);
+        const merged = mergeFilter(currentFilter, includeRes.resolved, excludeRes.resolved, params.sizes, includeLocRes.resolved, excludeLocRes.resolved);
         const mergedBody = filterWriteBody(merged);
         const isDefault = lens.is_default || lens.default;
         const isUserLevel = lens.user_id != null;
@@ -21548,6 +21639,7 @@ var init_new_lens = __esm({
   "../core/dist/composite/new-lens.js"() {
     "use strict";
     init_adjust_audience();
+    init_geo_helpers();
     init_tool_descriptions_generated();
     EMPTY_FILTER = {
       lens_filter: { items: [{ criteria: [] }] },
@@ -21586,6 +21678,16 @@ var init_new_lens = __esm({
             },
             description: "Company size buckets, e.g. [{min:30,max:300}]."
           },
+          locations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Geographic scope \u2014 free text (e.g. ['Indre-et-Loire', 'Bavaria']) or admin-area ids. Auto-resolved via /geo/search across all admin levels (city / county / d\xE9partement / r\xE9gion / state / country). Scopes the lens to a sales territory."
+          },
+          exclude_locations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Locations to exclude \u2014 free text or ids."
+          },
           base: {
             type: "number",
             description: "Lens id to clone from. Defaults to the active/default lens."
@@ -21601,12 +21703,12 @@ var init_new_lens = __esm({
       },
       outputSchema: {
         type: "object",
-        description: "'preview' (default, NOTHING created \u2014 confirm with the user then re-call with confirm:true); 'created' on success; 'ambiguous_sectors' when free-text sectors didn't resolve (re-call with sector ids \u2014 the lens was NOT created).",
+        description: "'preview' (default, NOTHING created \u2014 confirm with the user then re-call with confirm:true); 'created' on success; 'ambiguous_sectors' / 'ambiguous_locations' when free-text sectors / locations didn't resolve (re-call with ids \u2014 the lens was NOT created).",
         properties: {
-          status: { type: "string", description: "'preview', 'created', 'ambiguous_sectors', or 'orphan_created' (filter write failed + cleanup failed)." },
+          status: { type: "string", description: "'preview', 'created', 'ambiguous_sectors', 'ambiguous_locations', or 'orphan_created' (filter write failed + cleanup failed)." },
           will_create: {
             type: "object",
-            description: "On 'preview': what WILL be created \u2014 {name, description, sectors, exclude_sectors, sizes}. Nothing has been written yet."
+            description: "On 'preview': what WILL be created \u2014 {name, description, sectors, exclude_sectors, sizes, locations, exclude_locations}. Nothing has been written yet."
           },
           filter_preview: { type: "object", description: "On 'preview': the FilterPayload that would be applied." },
           lens: {
@@ -21618,6 +21720,11 @@ var init_new_lens = __esm({
             description: "On 'ambiguous_sectors': per text {sector_text, matches:[{id,name,score}]}.",
             items: { type: "object" }
           },
+          location_ambiguities: {
+            type: "array",
+            description: "On 'ambiguous_locations': per text {location_text, matches:[{id,name,country,level,score}]}. Re-call the chosen id via the SAME axis the text came from \u2014 an include text \u2192 locations; a text from exclude_locations \u2192 exclude_locations (NOT locations, which would include the area the user asked to exclude). The `message` field names the correct param per text.",
+            items: { type: "object" }
+          },
           filter_applied: { type: "object", description: "On 'created': the FilterPayload POSTed to the new lens." },
           message: { type: "string" },
           _meta: { type: "object" }
@@ -21644,7 +21751,38 @@ var init_new_lens = __esm({
             message: parts.join(" ")
           };
         }
-        const merged = mergeFilter(EMPTY_FILTER, includeRes.resolved, excludeRes.resolved, params.sizes);
+        const includeLocRes = await resolveLocations(client, params.locations ?? []);
+        const excludeLocRes = await resolveLocations(client, params.exclude_locations ?? []);
+        const locAmbiguities = [
+          ...includeLocRes.ambiguities,
+          ...excludeLocRes.ambiguities
+        ];
+        if (locAmbiguities.length > 0) {
+          const incMatch = includeLocRes.ambiguities.filter((a) => a.matches.length > 0);
+          const incNone = includeLocRes.ambiguities.filter((a) => a.matches.length === 0);
+          const excMatch = excludeLocRes.ambiguities.filter((a) => a.matches.length > 0);
+          const excNone = excludeLocRes.ambiguities.filter((a) => a.matches.length === 0);
+          const quote = (as) => as.map((a) => `"${a.location_text}"`).join(", ");
+          const parts = [];
+          if (incNone.length > 0) {
+            parts.push(`Couldn't find a location matching ${quote(incNone)}. Pick a known area and re-call via locations (lens not yet created).`);
+          }
+          if (incMatch.length > 0) {
+            parts.push(`${quote(incMatch)} matched multiple areas. Pick from the matches and re-call with the chosen id in locations.`);
+          }
+          if (excNone.length > 0) {
+            parts.push(`Couldn't find a location to exclude matching ${quote(excNone)}. Pick a known area and re-call via exclude_locations (lens not yet created).`);
+          }
+          if (excMatch.length > 0) {
+            parts.push(`${quote(excMatch)} (to exclude) matched multiple areas. Pick from the matches and re-call with the chosen id in exclude_locations \u2014 NOT locations, which would include it.`);
+          }
+          return {
+            status: "ambiguous_locations",
+            location_ambiguities: locAmbiguities,
+            message: parts.join(" ")
+          };
+        }
+        const merged = mergeFilter(EMPTY_FILTER, includeRes.resolved, excludeRes.resolved, params.sizes, includeLocRes.resolved, excludeLocRes.resolved);
         if (params.confirm !== true) {
           return {
             status: "preview",
@@ -21653,7 +21791,9 @@ var init_new_lens = __esm({
               description: params.description ?? null,
               sectors: includeRes.resolved,
               exclude_sectors: excludeRes.resolved,
-              sizes: merged.lens_filter.items[0].criteria.find((c) => c.type === "size") ?? null
+              sizes: merged.lens_filter.items[0].criteria.find((c) => c.type === "size") ?? null,
+              locations: includeLocRes.resolved,
+              exclude_locations: excludeLocRes.resolved
             },
             filter_preview: merged,
             message: `About to create "${params.name}". Confirm with the user, then re-call with confirm:true.`,
@@ -27451,7 +27591,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.23.5";
+var VERSION = "0.23.6";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server