@urbankitstudio/mcp-atlas 0.4.4 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,7 +8,7 @@ Query the parcel ArcGIS REST endpoints of 546 counties across 51 US states (50 s
8
8
 
9
9
  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.
10
10
 
11
- **Coverage:** 546 counties across 51 US states (50 states plus DC), 522 endpoints, 522 of them live (atlas 0.9.6). 494 of the counties have an endpoint; for the other 52 the atlas records why not (see "A county we cannot serve" below).
11
+ **Coverage:** 546 counties across 51 US states (50 states plus DC), 522 endpoints, 522 of them live (atlas 0.9.7). 494 of the counties have an endpoint; for the other 52 the atlas records why not (see "A county we cannot serve" below).
12
12
 
13
13
  ---
14
14
 
@@ -138,7 +138,9 @@ Resolves a reference you cannot state exactly. Fuzzy-matches a partial or
138
138
  misspelled name, a "County State" phrase, or a 5-digit FIPS code against every
139
139
  covered county, and names each county it matched so an ambiguous reference
140
140
  comes back as a list to choose from. Each match carries that county's record:
141
- endpoint URLs, searchable field names, owner field, sample query, license.
141
+ endpoint URLs, searchable field names, owner field, sample query, license. A
142
+ record that gives a column a role prints a `Field role:` line for it (see
143
+ `get_parcel_endpoint`).
142
144
 
143
145
  | Parameter | Type | Required | Description |
144
146
  |-----------|------|----------|-------------|
@@ -159,6 +161,10 @@ for one county. For a named owner, use
159
161
  that flags confidential owners it prints the `Confidential flag:` exclusion
160
162
  to AND into any query of your own, and prints its own sample owner query in
161
163
  place of the atlas's, so the one sample shown carries this server's clauses.
164
+ Where a record gives a column a role (atlas 0.9.7; today only Dooly County, GA:
165
+ a second owner-mailing line and the site address's directional, both columns
166
+ you cannot search on) it prints one `Field role:` line per such column after
167
+ the searchable fields, saying how to read it.
162
168
  Where the owners sit in a joined table, the owner field line names the table
163
169
  and the sample owner query goes to it.
164
170
 
@@ -184,6 +184,12 @@ export declare function incompleteFlagReason(flag: IncompleteConfidentialFlag):
184
184
  * where clause, so there the line gives the row rule instead of "AND this in".
185
185
  */
186
186
  export declare function confidentialLine(owner: Pick<OwnerSearchPolicy, "confidential" | "kind">): string | null;
187
+ /**
188
+ * One line per searchField that declares a role, in field order, for find_county
189
+ * and get_parcel_endpoint to print after the searchable fields. Empty when the
190
+ * endpoint declares none.
191
+ */
192
+ export declare function fieldRoleLines(endpoint: Pick<EndpointRecord, "searchFields">): string[];
187
193
  export declare const ATTRIBUTE_SEARCH_UNSUPPORTED_REASON = "this layer does not serve attribute searches; owner and address fields are answered only by location queries";
188
194
  export declare const OWNER_UNSEARCHABLE_REASON = "the owner column exists but the county marks it unsearchable";
189
195
  export declare function ownerSearchPolicy(county: CountyPolicyFields, endpoint: EndpointSearchPolicyFields): OwnerSearchPolicy;
@@ -239,6 +239,31 @@ export function confidentialLine(owner) {
239
239
  }
240
240
  return `Confidential flag: ${c.where} (the county flags confidential owners in ${c.field}; AND this into every query, and never show or pass on a flagged row)`;
241
241
  }
242
+ /**
243
+ * What an agent does with each role a searchField declares (atlas 0.9.7,
244
+ * `SearchField.role`). The wording is this server's own, written from the
245
+ * atlas package's reading rules; no text from a record is interpolated except
246
+ * the column's name and label, which the field lists print already. A column
247
+ * with no role prints nothing, so an endpoint that declares none is unchanged.
248
+ */
249
+ const FIELD_ROLE_USE = {
250
+ "mailing-fallback": "a second owner-mailing line. Read it only when the endpoint's primary mailing column is blank or a placeholder such as \"N/A\", never when that column is masked or withheld, and only when its value is a mailing line (a whole house number then a word, a P O Box or Drawer with its number, or a rural route box) with no owner-entity, share, c/o or attention word and no word that says it is withheld (such as CONFIDENTIAL). A redaction marker in it withholds the whole row",
251
+ "situs-directional": "the directional of the site address, kept in its own column apart from the house-number and street-name columns. Compose the site address as house number, directional, street name, using the value only when it is a direction (N, S, E, W, NE, NW, SE, SW or spelled out). A redaction marker in it withholds the whole row",
252
+ };
253
+ /**
254
+ * One line per searchField that declares a role, in field order, for find_county
255
+ * and get_parcel_endpoint to print after the searchable fields. Empty when the
256
+ * endpoint declares none.
257
+ */
258
+ export function fieldRoleLines(endpoint) {
259
+ const lines = [];
260
+ for (const sf of endpoint.searchFields) {
261
+ if (!sf.role || !Object.hasOwn(FIELD_ROLE_USE, sf.role))
262
+ continue;
263
+ lines.push(`Field role: ${queryFieldName(sf)} (${sf.label}) is the ${sf.role}: ${FIELD_ROLE_USE[sf.role]}`);
264
+ }
265
+ return lines;
266
+ }
242
267
  // THE OWNER-COLUMN TEST, copied VERBATIM from the UrbanKit Studio canonical
243
268
  // owner classifier (OWNER_RE and OWNER_EXCLUDE), which applies them to
244
269
  // `${name} ${label}`. The two copies must stay byte-equal until
package/dist/server.js CHANGED
@@ -20,7 +20,7 @@ import { readFileSync } from "node:fs";
20
20
  import { fileURLToPath } from "node:url";
21
21
  import { resolve, dirname } from "node:path";
22
22
  import { atlas, atlasIndex, slugify, countySlugFromName, countyHasEndpoint, coverageAnswer, coverageAnswerText, queryFieldName, } from "@urbankitstudio/atlas";
23
- import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, ownerTableNotes, escapeSqlLiteral, confidentialLine, parcelEndpointSamples, ownerRefusal, ownerLine, } from "./search-policy.js";
23
+ import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, ownerTableNotes, escapeSqlLiteral, confidentialLine, fieldRoleLines, parcelEndpointSamples, ownerRefusal, ownerLine, } from "./search-policy.js";
24
24
  import { freeText } from "./tool-input.js";
25
25
  import { getCityDatasets, CITY_REF_MAX_LEN, CITY_STATE_MAX_LEN, CITY_STREET_MAX_LEN, } from "./city-datasets.js";
26
26
  // Re-exported so the package's public surface is unchanged by the move.
@@ -103,6 +103,7 @@ function formatCountySummary(c) {
103
103
  ...(scope ? [` ${scope}`] : []),
104
104
  ...(confidential ? [` ${confidential}`] : []),
105
105
  ` Searchable fields: ${searchable || "none"}`,
106
+ ...fieldRoleLines(ep).map((l) => ` ${l}`),
106
107
  ` ${ownerLine(owner)}`,
107
108
  ` License: ${ep.license}`,
108
109
  ].join("\n");
@@ -355,6 +356,8 @@ server.registerTool("get_parcel_endpoint", {
355
356
  ep.searchFields
356
357
  .filter((sf) => sf.searchable)
357
358
  .forEach((sf) => lines.push(` ${queryFieldName(sf).padEnd(20)} – ${sf.label}`));
359
+ for (const roleLine of fieldRoleLines(ep))
360
+ lines.push(` ${roleLine}`);
358
361
  lines.push("");
359
362
  lines.push(` ${ownerLine(owner)}`);
360
363
  // parcelEndpointSamples withholds the atlas's sample on any flagged
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@urbankitstudio/mcp-atlas",
3
- "version": "0.4.4",
3
+ "version": "0.4.5",
4
4
  "mcpName": "io.github.urbankitstudio/mcp-atlas",
5
5
  "description": "Query the parcel ArcGIS REST endpoints of 546 counties across 51 US states (50 states plus DC), 522 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP), plus verified city code-violation, building-permit and zoning-case datasets.",
6
6
  "keywords": [
@@ -51,7 +51,7 @@
51
51
  },
52
52
  "dependencies": {
53
53
  "@modelcontextprotocol/sdk": "^1.32.1",
54
- "@urbankitstudio/atlas": "^0.9.6"
54
+ "@urbankitstudio/atlas": "^0.9.7"
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/node": "^26.0.0",