@urbankitstudio/mcp-atlas 0.2.6 → 0.2.8

package/README.md

@@ -4,11 +4,11 @@
 
 [![mcp-atlas MCP server](https://glama.ai/mcp/servers/LEOyrh/mcp-atlas/badges/card.svg)](https://glama.ai/mcp/servers/LEOyrh/mcp-atlas)
 
-Query the verified parcel ArcGIS REST endpoints of 235 counties across 51 US states (50 states plus DC), 247 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP).
+Query the verified parcel ArcGIS REST endpoints of 246 counties across 51 US states (50 states plus DC), 258 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP).
 
 An [MCP](https://modelcontextprotocol.io) server that gives AI assistants direct access to UrbanKit Studio's atlas of manually verified county parcel GIS services. Ask Claude or Cursor to find the ArcGIS REST endpoint for any covered county, get the exact owner-search query URL, and look up parcel data — without needing to know anything about ArcGIS REST API conventions.
 
-**Coverage:** 235 counties across 51 US states (50 states plus DC), 247 verified endpoints (atlas 0.6.9).
+**Coverage:** 246 counties across 51 US states (50 states plus DC), 258 verified endpoints (atlas 0.6.14).
 
 ---
 
@@ -96,6 +96,16 @@ IL | DuPage               | dupage-county            | owner+APN
 ...
 ```
 
+What each Coverage label promises:
+
+| Label | Meaning |
+|-------|---------|
+| `owner+APN` | `build_owner_query` returns a URL for at least one endpoint |
+| `APN only (county publishes no owner name)` | A reviewed record says the county serves no usable owner name |
+| `location queries only` | No endpoint answers attribute searches; parcels are reached by geometry, which also returns owner fields |
+| `APN only (owner column not searchable)` | An owner column exists but the county marks it unsearchable by name; a parcel-id or location query returns it |
+| `APN only` | No endpoint documents an owner column |
+
 ---
 
 ### `find_county`
@@ -117,8 +127,10 @@ endpoint URLs, searchable field names, owner field, sample query, license.
 ### `get_parcel_endpoint`
 
 The default lookup once the county is known. Returns the full ArcGIS REST URL,
-layer index, searchable fields, owner field, a generic sample `?where=…&f=json`
-query and the UrbanKit deep-link for one county. For a named owner, use
+layer index, searchable fields, owner field (or why no owner query is offered),
+the county's `Scope:` predicate when the layer is shared statewide or
+regionally, a generic sample `?where=…&f=json` query and the UrbanKit deep-link
+for one county. For a named owner, use
 `build_owner_query` rather than editing the sample query by hand.
 
 | Parameter | Type | Required | Description |
@@ -135,8 +147,17 @@ query and the UrbanKit deep-link for one county. For a named owner, use
 The only tool that searches for a named owner. Fills a person or company name
 into the county's verified owner/taxpayer field as
 `UPPER(field) LIKE UPPER('%NAME%')`, a case-insensitive partial match, and
-returns a URL you can fetch or open. A county that publishes no owner name is
-refused here, with the reason, rather than handed a query that finds nothing.
+returns a URL you can fetch or open. On a shared statewide or regional layer
+(Connecticut's regional composites, for example) the county's scope predicate
+is ANDed in front, as
+`(scope) AND UPPER(field) LIKE …`, so only that county's rows come back.
+
+An endpoint is refused, with the reason, rather than handed a query that finds
+nothing or hangs:
+
+- a reviewed record says the county publishes no usable owner name;
+- the layer serves no attribute search at all (query it by location instead);
+- the owner column is not searchable by name (use a parcel-id or location query).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|

package/dist/search-policy.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Owner-search policy: the ONE rule for whether this server offers an
+ * owner-name query on a county endpoint, and how that query is scoped.
+ *
+ * Every tool (list_counties, find_county, get_parcel_endpoint,
+ * build_owner_query) asks this module and nothing else, so no county can be
+ * offered by one tool and refused by another. Written 2026-10-03 on Leo's
+ * directive to surface as much of the county data as the registry knows,
+ * with clean, commented SOLID/DRY/KISS code.
+ *
+ * Decision order, first match wins:
+ *   1. reviewed_unservable: a human-reviewed capability record says the owner
+ *      name cannot be served. New Jersey's statewide layer publishes OWNER_NAME
+ *      blank on 3.4M rows; only the reviewed record can say so, and it outranks
+ *      anything the field list implies.
+ *   2. attribute_search_unsupported: the registry marks the layer
+ *      `attributeSearch: "unsupported"`. It cannot answer a `where` on any
+ *      column. In atlas 0.6.9 all 67 such endpoints are Florida's FDOR
+ *      statewide layer. Owner and address values still come back from
+ *      location queries, so the reason says that instead of "no owner".
+ *   3. owner_unsearchable: an owner-name column exists but the county marks
+ *      every such column `searchable: false`. A query on it hangs or errors
+ *      (Orleans Parish OWNERNME1, where a column scan takes ~44 s). The owner
+ *      is still returned by a parcel-id or location query.
+ *   4. offered: the first owner-name column that is searchable (the column
+ *      test is the UKS classifier's; see OWNER_RE below).
+ *   5. no_owner_column: the layer documents no owner column at all.
+ *
+ * Separately from the branch, `scopeWhere` is returned whenever the registry
+ * carries one. A shared statewide or regional layer holds every county's rows
+ * (FDOR `CO_NO=23` is Miami-Dade), so an unscoped query returns the whole
+ * state. ownerWhereClause ANDs the scope in front of every owner match.
+ */
+import type { CountyRecord, EndpointRecord } from "@urbankitstudio/atlas";
+/**
+ * The endpoint fields this policy reads, as @urbankitstudio/atlas declares them
+ * (`scopeWhere` and `attributeSearch` since 0.6.11; before that this file
+ * carried a local copy of the two).
+ */
+export type EndpointSearchPolicyFields = Pick<EndpointRecord, "searchFields" | "scopeWhere" | "attributeSearch">;
+type CountyPolicyFields = Pick<CountyRecord, "capabilityOverrides">;
+export type OwnerSearchKind = "offered" | "reviewed_unservable" | "attribute_search_unsupported" | "owner_unsearchable" | "no_owner_column";
+export interface OwnerSearchPolicy {
+    kind: OwnerSearchKind;
+    /** The owner column to query. Set only when kind is "offered". */
+    field: string | null;
+    /** Why no owner query is offered. Null when offered or when there is simply no owner column. */
+    reason: string | null;
+    /** SQL predicate scoping a shared layer to this county, or null. */
+    scopeWhere: string | null;
+}
+export declare const ATTRIBUTE_SEARCH_UNSUPPORTED_REASON = "this layer does not serve attribute searches; owner and address fields are answered only by location queries";
+export declare const OWNER_UNSEARCHABLE_REASON = "the owner column exists but the county marks it unsearchable";
+export declare function ownerSearchPolicy(county: CountyPolicyFields, endpoint: EndpointSearchPolicyFields): OwnerSearchPolicy;
+/**
+ * An ArcGIS `where` is SQL, and a single quote closes the string literal.
+ * encodeURIComponent does not help: `'` and `)` are both in its unreserved set, so
+ * `A') OR 1=1 --` passes through encoding intact and lands OUTSIDE the quotes as a
+ * live predicate against a county's server. Doubling the quote is the SQL-standard
+ * escape and keeps the whole input inside the literal where it belongs.
+ *
+ * Every caller that puts user text in a `where` goes through this, including the
+ * clause rendered for a human to copy: escaping only the URL would leave the same
+ * payload one paste away from running.
+ */
+export declare function escapeSqlLiteral(value: string): string;
+/**
+ * The raw SQL owner match, scoped when the layer is shared. Both the query URL
+ * (which encodes this string) and the clause printed for a human come from
+ * here, so the two can never disagree about the scope or the escaping. The
+ * scope is curated registry text, not user input, so it is not escaped.
+ */
+export declare function ownerWhereClause(field: string, scopeWhere: string | null, ownerName: string): string;
+/**
+ * The list_counties coverage label, summarised across a county's endpoints.
+ * What each label promises a caller deciding whether to spend a request:
+ *   "owner+APN"            build_owner_query returns a URL for at least one endpoint.
+ *   "APN only (county publishes no owner name)"
+ *                          a reviewed record says owner names are not served.
+ *   "location queries only"
+ *                          no endpoint answers attribute searches; parcels are
+ *                          reached by geometry, which also returns owner fields.
+ *   "APN only (owner column not searchable)"
+ *                          an owner column exists but the county marks it unsearchable.
+ *   "APN only"             no endpoint documents an owner column.
+ */
+export declare function ownerCoverageLabel(county: CountyPolicyFields & {
+    endpoints: readonly EndpointSearchPolicyFields[];
+}): string;
+export {};

package/dist/search-policy.js

@@ -0,0 +1,123 @@
+/**
+ * Owner-search policy: the ONE rule for whether this server offers an
+ * owner-name query on a county endpoint, and how that query is scoped.
+ *
+ * Every tool (list_counties, find_county, get_parcel_endpoint,
+ * build_owner_query) asks this module and nothing else, so no county can be
+ * offered by one tool and refused by another. Written 2026-10-03 on Leo's
+ * directive to surface as much of the county data as the registry knows,
+ * with clean, commented SOLID/DRY/KISS code.
+ *
+ * Decision order, first match wins:
+ *   1. reviewed_unservable: a human-reviewed capability record says the owner
+ *      name cannot be served. New Jersey's statewide layer publishes OWNER_NAME
+ *      blank on 3.4M rows; only the reviewed record can say so, and it outranks
+ *      anything the field list implies.
+ *   2. attribute_search_unsupported: the registry marks the layer
+ *      `attributeSearch: "unsupported"`. It cannot answer a `where` on any
+ *      column. In atlas 0.6.9 all 67 such endpoints are Florida's FDOR
+ *      statewide layer. Owner and address values still come back from
+ *      location queries, so the reason says that instead of "no owner".
+ *   3. owner_unsearchable: an owner-name column exists but the county marks
+ *      every such column `searchable: false`. A query on it hangs or errors
+ *      (Orleans Parish OWNERNME1, where a column scan takes ~44 s). The owner
+ *      is still returned by a parcel-id or location query.
+ *   4. offered: the first owner-name column that is searchable (the column
+ *      test is the UKS classifier's; see OWNER_RE below).
+ *   5. no_owner_column: the layer documents no owner column at all.
+ *
+ * Separately from the branch, `scopeWhere` is returned whenever the registry
+ * carries one. A shared statewide or regional layer holds every county's rows
+ * (FDOR `CO_NO=23` is Miami-Dade), so an unscoped query returns the whole
+ * state. ownerWhereClause ANDs the scope in front of every owner match.
+ */
+import { isReviewedUnservable, reviewedCapability } from "@urbankitstudio/atlas";
+// THE OWNER-COLUMN TEST, copied VERBATIM from the UKS canonical classifier:
+// urbankitstudio/src/lib/enrich-core.ts lines 48 (OWNER_RE) and 58
+// (OWNER_EXCLUDE), applied there by firstMatch to `${name} ${label}`. The two
+// copies must stay byte-equal until @urbankitstudio/atlas exports the
+// classifier (a queued UKS follow-up); then import it and delete these lines.
+// Testing the label as well as the name is what makes Mahoning's
+// "OWNNAME1 / Owner Name 1" an owner column. The exclude keeps owner ADDRESS
+// and locale columns (OWNER_ADDR, OWNERCITY) from being offered as a name.
+const OWNER_RE = /owner|taxpayer|tax.?name|grantor|\bown\b|ownnme|ownernme/i;
+const OWNER_EXCLUDE = /addr|address|\bcity\b|\bstate\b|\bzip\b/i;
+function isOwnerNameColumn(sf) {
+    const hay = `${sf.name} ${sf.label}`;
+    return !OWNER_EXCLUDE.test(hay) && OWNER_RE.test(hay);
+}
+export const ATTRIBUTE_SEARCH_UNSUPPORTED_REASON = "this layer does not serve attribute searches; owner and address fields are answered only by location queries";
+export const OWNER_UNSEARCHABLE_REASON = "the owner column exists but the county marks it unsearchable";
+export function ownerSearchPolicy(county, endpoint) {
+    const scopeWhere = endpoint.scopeWhere?.trim() || null;
+    const refuse = (kind, reason) => ({
+        kind,
+        field: null,
+        reason,
+        scopeWhere,
+    });
+    if (isReviewedUnservable(county, "owner_name")) {
+        return refuse("reviewed_unservable", reviewedCapability(county, "owner_name")?.basis?.note ??
+            "this county publishes no usable owner name on its public endpoint");
+    }
+    if (endpoint.attributeSearch === "unsupported") {
+        return refuse("attribute_search_unsupported", ATTRIBUTE_SEARCH_UNSUPPORTED_REASON);
+    }
+    const named = endpoint.searchFields.filter(isOwnerNameColumn);
+    const usable = named.find((sf) => sf.searchable !== false);
+    if (usable)
+        return { kind: "offered", field: usable.name, reason: null, scopeWhere };
+    if (named.length > 0)
+        return refuse("owner_unsearchable", OWNER_UNSEARCHABLE_REASON);
+    return refuse("no_owner_column", null);
+}
+/**
+ * An ArcGIS `where` is SQL, and a single quote closes the string literal.
+ * encodeURIComponent does not help: `'` and `)` are both in its unreserved set, so
+ * `A') OR 1=1 --` passes through encoding intact and lands OUTSIDE the quotes as a
+ * live predicate against a county's server. Doubling the quote is the SQL-standard
+ * escape and keeps the whole input inside the literal where it belongs.
+ *
+ * Every caller that puts user text in a `where` goes through this, including the
+ * clause rendered for a human to copy: escaping only the URL would leave the same
+ * payload one paste away from running.
+ */
+export function escapeSqlLiteral(value) {
+    return value.replace(/'/g, "''");
+}
+/**
+ * The raw SQL owner match, scoped when the layer is shared. Both the query URL
+ * (which encodes this string) and the clause printed for a human come from
+ * here, so the two can never disagree about the scope or the escaping. The
+ * scope is curated registry text, not user input, so it is not escaped.
+ */
+export function ownerWhereClause(field, scopeWhere, ownerName) {
+    const match = `UPPER(${field}) LIKE UPPER('%${escapeSqlLiteral(ownerName)}%')`;
+    return scopeWhere ? `(${scopeWhere}) AND ${match}` : match;
+}
+/**
+ * The list_counties coverage label, summarised across a county's endpoints.
+ * What each label promises a caller deciding whether to spend a request:
+ *   "owner+APN"            build_owner_query returns a URL for at least one endpoint.
+ *   "APN only (county publishes no owner name)"
+ *                          a reviewed record says owner names are not served.
+ *   "location queries only"
+ *                          no endpoint answers attribute searches; parcels are
+ *                          reached by geometry, which also returns owner fields.
+ *   "APN only (owner column not searchable)"
+ *                          an owner column exists but the county marks it unsearchable.
+ *   "APN only"             no endpoint documents an owner column.
+ */
+export function ownerCoverageLabel(county) {
+    const kinds = county.endpoints.map((ep) => ownerSearchPolicy(county, ep).kind);
+    if (kinds.includes("offered"))
+        return "owner+APN";
+    if (kinds.includes("reviewed_unservable"))
+        return "APN only (county publishes no owner name)";
+    if (kinds.length > 0 && kinds.every((k) => k === "attribute_search_unsupported")) {
+        return "location queries only";
+    }
+    if (kinds.includes("owner_unsearchable"))
+        return "APN only (owner column not searchable)";
+    return "APN only";
+}

package/dist/server.d.ts

@@ -11,15 +11,5 @@
  *   get_parcel_endpoint – return the full REST service URL + ready sample query
  *   build_owner_query   – construct exact ArcGIS REST query for an owner name
  */
-/**
- * An ArcGIS `where` is SQL, and a single quote closes the string literal.
- * encodeURIComponent does not help: `'` and `)` are both in its unreserved set, so
- * `A') OR 1=1 --` passes through encoding intact and lands OUTSIDE the quotes as a
- * live predicate against a county's server. Doubling the quote is the SQL-standard
- * escape and keeps the whole input inside the literal where it belongs.
- *
- * Every caller that puts user text in a `where` goes through this, including the
- * clause rendered for a human to copy: escaping only the URL would leave the same
- * payload one paste away from running.
- */
-export declare function escapeSqlLiteral(value: string): string;
+import { escapeSqlLiteral } from "./search-policy.js";
+export { escapeSqlLiteral };

package/dist/server.js

@@ -17,57 +17,42 @@ import { z } from "zod/v3";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { resolve, dirname } from "node:path";
-import { atlas, atlasIndex, slugify, countySlugFromName, isReviewedUnservable, reviewedCapability, } from "@urbankitstudio/atlas";
+import { atlas, atlasIndex, slugify, countySlugFromName, } from "@urbankitstudio/atlas";
+import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, escapeSqlLiteral, } from "./search-policy.js";
+// Re-exported so the package's public surface is unchanged by the move.
+export { escapeSqlLiteral };
 const PKG_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")).version;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/**
- * The owner column a caller can actually USE, or null with a reason.
- *
- * Matching the column name is not enough, and that gap cost a real trial user:
- * they paid for owner data, ran Los Angeles County, got nothing back, and the
- * atlas had said the field was there the whole time. Fourteen counties in the
- * registry document an owner column that is present and empty on every row -
- * New Jersey's statewide layer publishes OWNER_NAME blank across 3,481,240
- * rows, New York's across 3,827,530 - and a reviewed capability record says so.
- * Consult it BEFORE promising the field.
- */
-function ownerFieldFor(county, endpoint) {
-    if (isReviewedUnservable(county, "owner_name")) {
-        const reviewed = reviewedCapability(county, "owner_name");
-        return {
-            field: null,
-            unavailableReason: reviewed?.basis?.note ??
-                "this county publishes no usable owner name on its public endpoint",
-        };
+// Whether an owner query is offered, and how it is scoped, is decided ONLY in
+// ./search-policy.ts. Matching the column name is not enough, and that gap cost
+// a real trial user: they paid for owner data, ran Los Angeles County, got
+// nothing back, and the atlas had said the field was there the whole time.
+/** The Owner/Attribute line shared by find_county and get_parcel_endpoint. */
+function ownerLine(owner) {
+    if (owner.field)
+        return `Owner field: ${owner.field}`;
+    if (owner.kind === "attribute_search_unsupported") {
+        return `Attribute search: not offered (location queries only) - ${owner.reason}`;
     }
-    const f = endpoint.searchFields.find((sf) => /owner|taxpayer|taxname/i.test(sf.name));
-    return { field: f?.name ?? null, unavailableReason: null };
-}
-/** Back-compat shim for call sites that only need the column. */
-function ownerFieldFrom(county, endpoint) {
-    return ownerFieldFor(county, endpoint).field;
+    if (owner.kind === "owner_unsearchable") {
+        return "Owner field: not searchable by name (column exists; use a parcel-id or location query)";
+    }
+    return owner.reason
+        ? `Owner field: NOT AVAILABLE - ${owner.reason}`
+        : "Owner field: NONE - this layer publishes no owner column";
 }
-/**
- * An ArcGIS `where` is SQL, and a single quote closes the string literal.
- * encodeURIComponent does not help: `'` and `)` are both in its unreserved set, so
- * `A') OR 1=1 --` passes through encoding intact and lands OUTSIDE the quotes as a
- * live predicate against a county's server. Doubling the quote is the SQL-standard
- * escape and keeps the whole input inside the literal where it belongs.
- *
- * Every caller that puts user text in a `where` goes through this, including the
- * clause rendered for a human to copy: escaping only the URL would leave the same
- * payload one paste away from running.
- */
-export function escapeSqlLiteral(value) {
-    return value.replace(/'/g, "''");
+/** A shared layer's county predicate, printed so a caller ANDs it into any query of their own. */
+function scopeLine(owner) {
+    return owner.scopeWhere
+        ? `Scope: ${owner.scopeWhere} (shared layer; AND this into every query)`
+        : null;
 }
-function buildArcgisOwnerQuery(county, endpoint, ownerQuery) {
-    const field = ownerFieldFrom(county, endpoint);
-    if (!field)
+function buildArcgisOwnerQuery(endpoint, owner, ownerQuery) {
+    if (!owner.field)
         return "";
-    const where = `UPPER(${field}) LIKE UPPER('%25${encodeURIComponent(escapeSqlLiteral(ownerQuery))}%25')`;
+    const where = encodeURIComponent(ownerWhereClause(owner.field, owner.scopeWhere, ownerQuery));
     const liveFields = endpoint.searchFields
         .filter((sf) => sf.searchable)
         .map((sf) => sf.name)
@@ -84,20 +69,19 @@ function formatCountySummary(c) {
         ? "no REST endpoint mapped"
         : c.endpoints
             .map((ep) => {
-            const owner = ownerFieldFor(c, ep);
+            const owner = ownerSearchPolicy(c, ep);
             const searchable = ep.searchFields
                 .filter((sf) => sf.searchable)
                 .map((sf) => `${sf.name} (${sf.label})`)
                 .join(", ");
+            const scope = scopeLine(owner);
             return [
                 `  URL: ${ep.url}`,
                 `  Service: ${ep.serviceType}/layer ${ep.layerIndex}`,
                 `  Status: ${ep.status} (verified ${ep.lastVerified})`,
+                ...(scope ? [`  ${scope}`] : []),
                 `  Searchable fields: ${searchable || "none"}`,
-                `  Owner field: ${owner.field ??
-                    (owner.unavailableReason
-                        ? `NOT AVAILABLE - ${owner.unavailableReason}`
-                        : "none (this layer publishes no owner column)")}`,
+                `  ${ownerLine(owner)}`,
                 `  License: ${ep.license}`,
             ].join("\n");
         })
@@ -153,17 +137,10 @@ server.registerTool("list_counties", {
             continue;
         const covered = stateFile.counties.filter((c) => c.endpoints.length > 0);
         for (const c of covered) {
-            // "APN only" is not the same claim as "owner+APN minus the owner".
-            // A caller scanning this column is deciding whether to spend a request,
-            // so a county whose owner column exists and is empty must not read as
-            // though owners are simply absent from the schema.
-            const anyOwner = c.endpoints.some((ep) => ownerFieldFor(c, ep).field);
-            const ownerWithheld = c.endpoints.some((ep) => ownerFieldFor(c, ep).unavailableReason);
-            const ownerCoverage = anyOwner
-                ? "owner+APN"
-                : ownerWithheld
-                    ? "APN only (county publishes no owner name)"
-                    : "APN only";
+            // A caller scanning this column is deciding whether to spend a request.
+            // ownerCoverageLabel documents what each label promises; "owner+APN"
+            // means build_owner_query will actually return a URL.
+            const ownerCoverage = ownerCoverageLabel(c);
             rows.push(`${c.state} | ${c.county.padEnd(20)} | ${c.countySlug.padEnd(24)} | ${ownerCoverage}`);
         }
     }
@@ -272,7 +249,7 @@ server.registerTool("find_county", {
 // ---------------------------------------------------------------------------
 server.registerTool("get_parcel_endpoint", {
     title: "Get one county's parcel endpoint record",
-    description: "The default lookup once the county is known. Takes an exact state and county and returns that county's ArcGIS REST service URL, layer index, searchable field names, verified owner/taxpayer field, a generic sample ?where=…&f=json query, and the UrbanKit deep-link. If the county name is uncertain, misspelled, or you hold only a FIPS code, call find_county first. To search for a named person or company, call build_owner_query rather than editing the sample query by hand.",
+    description: "The default lookup once the county is known. Takes an exact state and county and returns that county's ArcGIS REST service URL, layer index, searchable field names, verified owner/taxpayer field (or why no owner query is offered), the county's Scope predicate when the layer is shared statewide or regionally (AND it into any query of your own), a generic sample ?where=…&f=json query, and the UrbanKit deep-link. If the county name is uncertain, misspelled, or you hold only a FIPS code, call find_county first. To search for a named person or company, call build_owner_query rather than editing the sample query by hand.",
     inputSchema: {
         state: z
             .string()
@@ -328,11 +305,12 @@ server.registerTool("get_parcel_endpoint", {
         "",
     ];
     countyRecord.endpoints.forEach((ep, i) => {
-        const owner = ownerFieldFor(countyRecord, ep);
+        const owner = ownerSearchPolicy(countyRecord, ep);
         const ownerField = owner.field;
         const sampleOwnerUrl = ownerField
-            ? buildArcgisOwnerQuery(countyRecord, ep, "SMITH")
+            ? buildArcgisOwnerQuery(ep, owner, "SMITH")
             : null;
+        const scope = scopeLine(owner);
         lines.push(`Endpoint ${i + 1}:`);
         lines.push(`  URL:         ${ep.url}`);
         lines.push(`  Service:     ${ep.serviceType}`);
@@ -341,16 +319,15 @@ server.registerTool("get_parcel_endpoint", {
         lines.push(`  Status:      ${ep.status} (verified ${ep.lastVerified})`);
         lines.push(`  CORS:        ${ep.corsEnabled === null ? "unknown" : ep.corsEnabled}`);
         lines.push(`  License:     ${ep.license}${ep.licenseUrl ? ` (${ep.licenseUrl})` : ""}`);
+        if (scope)
+            lines.push(`  ${scope}`);
         lines.push("");
         lines.push("  Searchable fields:");
         ep.searchFields
             .filter((sf) => sf.searchable)
             .forEach((sf) => lines.push(`    ${sf.name.padEnd(20)} – ${sf.label}`));
         lines.push("");
-        lines.push(`  Owner field: ${ownerField ??
-            (owner.unavailableReason
-                ? `NOT AVAILABLE - ${owner.unavailableReason}`
-                : "NONE - this layer publishes no owner column")}`);
+        lines.push(`  ${ownerLine(owner)}`);
         if (ep.sampleQuery) {
             lines.push("");
             lines.push("  Sample query (from atlas):");
@@ -375,7 +352,7 @@ server.registerTool("get_parcel_endpoint", {
 // ---------------------------------------------------------------------------
 server.registerTool("build_owner_query", {
     title: "Build an owner-name search URL for one county",
-    description: "The only tool that searches for a named owner. Fills a person or company name into that county's verified owner/taxpayer field as UPPER(field) LIKE UPPER('%NAME%'), a case-insensitive partial match, and returns a URL you can fetch or open in a browser. get_parcel_endpoint returns the endpoint and a generic sample query, not a name search, so come here for the name. This server does not execute the query and returns no parcel records: fetch the returned URL yourself. Counties that publish no owner name are refused here with that reason.",
+    description: "The only tool that searches for a named owner. Fills a person or company name into that county's verified owner/taxpayer field as UPPER(field) LIKE UPPER('%NAME%'), a case-insensitive partial match, and returns a URL you can fetch or open in a browser. On a shared statewide or regional layer the county's scope predicate is ANDed in front, as (scope) AND UPPER(field) LIKE …, so only that county's rows come back. get_parcel_endpoint returns the endpoint and a generic sample query, not a name search, so come here for the name. This server does not execute the query and returns no parcel records: fetch the returned URL yourself. An endpoint is refused, with the reason, when a reviewed record says the county publishes no owner name, when the layer serves no attribute search (query it by location instead), or when its owner column is not searchable by name (use a parcel-id or location query instead).",
     inputSchema: {
         state: z
             .string()
@@ -419,22 +396,38 @@ server.registerTool("build_owner_query", {
     }
     const results = [];
     for (const ep of countyRecord.endpoints) {
-        const owner = ownerFieldFor(countyRecord, ep);
+        const owner = ownerSearchPolicy(countyRecord, ep);
         const ownerField = owner.field;
         if (!ownerField) {
             // Refusing with the reason beats handing back a query that returns zero
-            // rows forever. The caller can then choose a different county or a
-            // different field instead of concluding the owner simply is not there.
-            results.push(owner.unavailableReason
-                ? `Endpoint: ${ep.url}\nOWNER NAME NOT AVAILABLE for ${countyRecord.county}, ${countyRecord.stateName}: ${owner.unavailableReason}\nNo owner query is possible here. Search by parcel number or address instead, or pick a county whose coverage reads owner+APN in list_counties.`
-                : `Endpoint: ${ep.url}\nNote: this layer publishes no owner or taxpayer column - PIN-only lookup. Try searching by parcel number instead.`);
+            // rows forever, or one that hangs. The caller can then choose a
+            // different county or query instead of concluding the owner is absent.
+            const place = `${countyRecord.county}, ${countyRecord.stateName}`;
+            let refusal;
+            switch (owner.kind) {
+                case "attribute_search_unsupported":
+                    refusal = `OWNER SEARCH NOT OFFERED on this layer for ${place}: ${owner.reason}\nNo where-clause query is possible here. Query the layer by location (a point or envelope geometry) to read the owner fields of the parcels there.`;
+                    break;
+                case "owner_unsearchable":
+                    // The owner IS published; only a name search on it is unsupported.
+                    refusal = `OWNER COLUMN NOT SEARCHABLE BY NAME for ${place}: ${owner.reason}\nUse a parcel-id or location query instead; either returns the owner of the matching parcel.`;
+                    break;
+                case "reviewed_unservable":
+                    refusal = `OWNER NAME NOT AVAILABLE for ${place}: ${owner.reason}\nNo owner query is possible here. Search by parcel number or address instead, or pick a county whose coverage reads owner+APN in list_counties.`;
+                    break;
+                default:
+                    refusal = "Note: this layer publishes no owner or taxpayer column - PIN-only lookup. Try searching by parcel number instead.";
+            }
+            results.push(`Endpoint: ${ep.url}\n${refusal}`);
             continue;
         }
-        const queryUrl = buildArcgisOwnerQuery(countyRecord, ep, owner_name);
-        const where = `UPPER(${ownerField}) LIKE UPPER('%${escapeSqlLiteral(owner_name)}%')`;
+        const queryUrl = buildArcgisOwnerQuery(ep, owner, owner_name);
+        const where = ownerWhereClause(ownerField, owner.scopeWhere, owner_name);
+        const scope = scopeLine(owner);
         results.push([
             `County:      ${countyRecord.county}, ${countyRecord.stateName}`,
             `Owner field: ${ownerField}`,
+            ...(scope ? [scope] : []),
             `WHERE clause: ${where}`,
             ``,
             `Query URL:`,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@urbankitstudio/mcp-atlas",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "mcpName": "io.github.LEOyrh/mcp-atlas",
-  "description": "Query the verified parcel ArcGIS REST endpoints of 235 counties across 51 US states (50 states plus DC), 247 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP).",
+  "description": "Query the verified parcel ArcGIS REST endpoints of 246 counties across 51 US states (50 states plus DC), 258 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP).",
   "keywords": [
     "mcp",
     "mcp-server",
@@ -24,7 +24,7 @@
   "bugs": {
     "url": "https://github.com/urbankitstudio/mcp-atlas/issues"
   },
-  "author": "UrbanKit Studio <urbankitstudio@gmail.com>",
+  "author": "UrbanKit Studio <contact@urbankitstudio.com>",
   "license": "MIT",
   "type": "module",
   "main": "./dist/server.js",
@@ -43,11 +43,12 @@
     "typecheck": "tsc --noEmit",
     "smoke": "node test/smoke.mjs",
     "test:currency": "node --test test/atlas-currency.test.mjs",
-    "prepublishOnly": "npm run typecheck && npm run build && npm run smoke"
+    "test:policy": "node --test test/search-policy.test.mjs",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run smoke && npm run test:policy"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@urbankitstudio/atlas": "^0.6.9"
+    "@urbankitstudio/atlas": "^0.6.14"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",