@urbankitstudio/mcp-atlas 0.3.6 → 0.3.8

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.
Files changed (3) hide show
  1. package/README.md +23 -3
  2. package/dist/server.js +99 -71
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -2,13 +2,13 @@
2
2
 
3
3
  # @urbankitstudio/mcp-atlas
4
4
 
5
- [![mcp-atlas MCP server](https://glama.ai/mcp/servers/LEOyrh/mcp-atlas/badges/card.svg)](https://glama.ai/mcp/servers/LEOyrh/mcp-atlas)
5
+ [![mcp-atlas MCP server](https://glama.ai/mcp/servers/urbankitstudio/mcp-atlas/badges/card.svg)](https://glama.ai/mcp/servers/urbankitstudio/mcp-atlas)
6
6
 
7
- Query the parcel ArcGIS REST endpoints of 395 counties across 51 US states (50 states plus DC), 413 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP).
7
+ Query the parcel ArcGIS REST endpoints of 494 counties across 51 US states (50 states plus DC), 494 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP).
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:** 395 counties across 51 US states (50 states plus DC), 413 endpoints, 412 of them live (atlas 0.6.36).
11
+ **Coverage:** 494 counties across 51 US states (50 states plus DC), 494 endpoints, 493 of them live (atlas 0.6.38). 467 of the counties have an endpoint; for the other 27 the atlas records why not (see "A county we cannot serve" below).
12
12
 
13
13
  ---
14
14
 
@@ -77,6 +77,26 @@ takes an exact pair and answers about one. If you already know the county, skip
77
77
  This server never executes a query and returns no parcel records. It tells you
78
78
  the URL to fetch; fetching it is yours to do.
79
79
 
80
+ ### A county we cannot serve
81
+
82
+ `find_county`, `get_parcel_endpoint` and `build_owner_query` give one answer for
83
+ a county with no endpoint to hand back, the same text the hosted UrbanKit MCP
84
+ server, its REST API and the `uks` CLI give. It comes from
85
+ `coverageAnswer()` in `@urbankitstudio/atlas` 0.6.38:
86
+
87
+ - **The atlas has no record** (a misspelling lands here too): "This county is not
88
+ in the UrbanKit atlas", with a prompt to check the spelling first.
89
+ - **The atlas records the county and it publishes nothing we can serve** (Shelby
90
+ TN, whose terms bar public display; Columbia PA, whose layer has parcel numbers
91
+ only): the reason in one sentence, the date we last checked, the date of the
92
+ next check when one is set, the county's own office and, where the county sells
93
+ the data, its own product.
94
+
95
+ Both end with a free request for the county: a ready body for `request_county`
96
+ on the hosted MCP server or `POST https://urbankitstudio.com/api/atlas/request`.
97
+ Requesting does not promise we add the county. `list_counties` still lists only
98
+ the counties we serve.
99
+
80
100
  ### `list_counties`
81
101
 
82
102
  Browse coverage. Answers "is this county covered?" and "what can I search
package/dist/server.js CHANGED
@@ -19,21 +19,41 @@ import { z } from "zod/v3";
19
19
  import { readFileSync } from "node:fs";
20
20
  import { fileURLToPath } from "node:url";
21
21
  import { resolve, dirname } from "node:path";
22
- import { atlas, atlasIndex, slugify, countySlugFromName, } from "@urbankitstudio/atlas";
22
+ import { atlas, atlasIndex, slugify, countySlugFromName, countyHasEndpoint, coverageAnswer, coverageAnswerText, } from "@urbankitstudio/atlas";
23
23
  import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, escapeSqlLiteral, } from "./search-policy.js";
24
24
  import { getCityDatasets, CITY_REF_MAX_LEN, CITY_STATE_MAX_LEN, CITY_STREET_MAX_LEN, } from "./city-datasets.js";
25
25
  // Re-exported so the package's public surface is unchanged by the move.
26
26
  export { escapeSqlLiteral };
27
27
  const PKG_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")).version;
28
- // This server carries no network tool of its own, so a county it does not hold
29
- // is pointed at the hosted request path instead (free; UKS PR #941, 2026-10-06).
30
- const REQUEST_COUNTY_HINT = "This county is not in the UrbanKit atlas yet. Offer to request it for the person you are helping; if they say yes, " +
31
- 'POST {"county_fips": "<5 digits>"} (or {"state_slug": "<state-slug>", "county_slug": "<county-slug>"}) ' +
32
- "to https://urbankitstudio.com/api/atlas/request, or call the hosted MCP tool request_county at https://urbankitstudio.com/api/mcp, " +
33
- 'adding their email ("requester_email") if they want to be told when it ships. Requesting is free.';
34
28
  // ---------------------------------------------------------------------------
35
29
  // Helpers
36
30
  // ---------------------------------------------------------------------------
31
+ // This server carries no network tool of its own, so a county it cannot serve
32
+ // (the atlas has no record, or records it with no public endpoint) gets the
33
+ // atlas package's coverage answer: why, when we checked, and the free request
34
+ // path on the hosted server. The text is the one the hosted MCP, the REST API
35
+ // and the `uks` CLI print, and it is pure, so every surface gives the same one.
36
+ function coverageText(record, ref) {
37
+ const block = coverageAnswer(record, ref);
38
+ return block ? coverageAnswerText(block) : null;
39
+ }
40
+ function recordRef(c) {
41
+ return { state: c.state, county: c.county, fips: c.countyFips };
42
+ }
43
+ /** True when the text is a state abbreviation, name or slug ("il", "new york", "new-york"), in any case. */
44
+ function namesState(text) {
45
+ const t = text.trim().toLowerCase();
46
+ return atlasIndex.states.some((s) => s.abbrev.toLowerCase() === t || s.name.toLowerCase() === t || s.slug === slugify(t));
47
+ }
48
+ /**
49
+ * The state a request ref may carry: the caller's text when it names a state,
50
+ * else "" so the answer asks for a FIPS code instead of sending a made-up
51
+ * state_slug ("zz", "ill"). The hosted get_county_endpoint does the same.
52
+ */
53
+ function refState(text) {
54
+ const t = text.trim();
55
+ return namesState(t) ? t : "";
56
+ }
37
57
  // Whether an owner query is offered, and how it is scoped, is decided ONLY in
38
58
  // ./search-policy.ts. Matching the column name is not enough, and that gap cost
39
59
  // a real trial user: they paid for owner data, ran Los Angeles County, got
@@ -59,27 +79,35 @@ function scopeLine(owner) {
59
79
  : null;
60
80
  }
61
81
  function formatCountySummary(c) {
62
- const epSummary = c.endpoints.length === 0
63
- ? "no REST endpoint mapped"
64
- : c.endpoints
65
- .map((ep) => {
66
- const owner = ownerSearchPolicy(c, ep);
67
- const searchable = ep.searchFields
68
- .filter((sf) => sf.searchable)
69
- .map((sf) => `${sf.name} (${sf.label})`)
70
- .join(", ");
71
- const scope = scopeLine(owner);
72
- return [
73
- ` URL: ${ep.url}`,
74
- ` Service: ${ep.serviceType}/layer ${ep.layerIndex}`,
75
- ` Status: ${ep.status} (verified ${ep.lastVerified})`,
76
- ...(scope ? [` ${scope}`] : []),
77
- ` Searchable fields: ${searchable || "none"}`,
78
- ` ${ownerLine(owner)}`,
79
- ` License: ${ep.license}`,
80
- ].join("\n");
81
- })
82
- .join("\n---\n");
82
+ if (!countyHasEndpoint(c)) {
83
+ return [
84
+ `${c.county}, ${c.stateName} (${c.state})`,
85
+ `FIPS: ${c.countyFips ?? "n/a"}`,
86
+ coverageText(c, recordRef(c)),
87
+ c.notes ? `Notes: ${c.notes}` : "",
88
+ ]
89
+ .filter(Boolean)
90
+ .join("\n");
91
+ }
92
+ const epSummary = c.endpoints
93
+ .map((ep) => {
94
+ const owner = ownerSearchPolicy(c, ep);
95
+ const searchable = ep.searchFields
96
+ .filter((sf) => sf.searchable)
97
+ .map((sf) => `${sf.name} (${sf.label})`)
98
+ .join(", ");
99
+ const scope = scopeLine(owner);
100
+ return [
101
+ ` URL: ${ep.url}`,
102
+ ` Service: ${ep.serviceType}/layer ${ep.layerIndex}`,
103
+ ` Status: ${ep.status} (verified ${ep.lastVerified})`,
104
+ ...(scope ? [` ${scope}`] : []),
105
+ ` Searchable fields: ${searchable || "none"}`,
106
+ ` ${ownerLine(owner)}`,
107
+ ` License: ${ep.license}`,
108
+ ].join("\n");
109
+ })
110
+ .join("\n---\n");
83
111
  return [
84
112
  `${c.county}, ${c.stateName} (${c.state})`,
85
113
  `FIPS: ${c.countyFips ?? "n/a"}`,
@@ -129,7 +157,7 @@ server.registerTool("list_counties", {
129
157
  const stateFile = atlas.byStateSlug.get(stateEntry.slug);
130
158
  if (!stateFile)
131
159
  continue;
132
- const covered = stateFile.counties.filter((c) => c.endpoints.length > 0);
160
+ const covered = stateFile.counties.filter(countyHasEndpoint);
133
161
  for (const c of covered) {
134
162
  // A caller scanning this column is deciding whether to spend a request.
135
163
  // ownerCoverageLabel documents what each label promises; "owner+APN"
@@ -175,10 +203,34 @@ server.registerTool("find_county", {
175
203
  .describe("County name, 'County Name State' (e.g. 'Kane IL'), or 5-digit FIPS code"),
176
204
  },
177
205
  }, ({ query }) => {
178
- const q = query.trim().toLowerCase();
206
+ // Commas and any run of whitespace (a tab too) are one space: "Cook County, IL".
207
+ const q = query.toLowerCase().replace(/[\s,]+/g, " ").trim();
208
+ if (q.length < 2) {
209
+ return {
210
+ content: [
211
+ { type: "text", text: "Give a county name, 'Name ST', or a 5-digit FIPS code." },
212
+ ],
213
+ isError: true,
214
+ };
215
+ }
179
216
  // FIPS lookup
180
217
  const isFips = /^\d{5}$/.test(q);
181
218
  const matches = [];
219
+ // Parse optional state suffix: "Kane IL", "Kane Illinois", "Kings New York". The
220
+ // last two words are tried as a state first, then the last one; a tail that names
221
+ // no state stays part of the county name, so "Kane County" and "Orleans Parish"
222
+ // stay whole.
223
+ let countyPart = q;
224
+ let statePart = null;
225
+ const words = q.split(" ");
226
+ if (words.length > 2 && namesState(words.slice(-2).join(" "))) {
227
+ countyPart = words.slice(0, -2).join(" ");
228
+ statePart = words.slice(-2).join(" ");
229
+ }
230
+ else if (words.length > 1 && namesState(words[words.length - 1])) {
231
+ countyPart = words.slice(0, -1).join(" ");
232
+ statePart = words[words.length - 1];
233
+ }
182
234
  for (const stateEntry of atlasIndex.states) {
183
235
  if (!stateEntry.populated)
184
236
  continue;
@@ -191,17 +243,6 @@ server.registerTool("find_county", {
191
243
  matches.push(county);
192
244
  continue;
193
245
  }
194
- // Parse optional state suffix: "Kane IL" or "Kane Illinois"
195
- let countyPart = q;
196
- let statePart = null;
197
- const spaceIdx = q.lastIndexOf(" ");
198
- if (spaceIdx > 0) {
199
- const last = q.slice(spaceIdx + 1);
200
- if (last.length === 2 || last.length > 3) {
201
- countyPart = q.slice(0, spaceIdx);
202
- statePart = last;
203
- }
204
- }
205
246
  if (statePart) {
206
247
  const stateOk = stateEntry.abbrev.toLowerCase() === statePart ||
207
248
  stateEntry.name.toLowerCase() === statePart ||
@@ -218,15 +259,15 @@ server.registerTool("find_county", {
218
259
  }
219
260
  }
220
261
  if (matches.length === 0) {
262
+ // statePart is set only for a trailing word that names a state, so a junk
263
+ // word ("Nowhere County ZZ") is never sent as the request's state_slug.
264
+ const ref = isFips
265
+ ? { state: q.slice(0, 2), fips: q }
266
+ : statePart
267
+ ? { state: statePart, county: countyPart }
268
+ : { state: "", county: q };
221
269
  return {
222
- content: [
223
- {
224
- type: "text",
225
- text: `No county matched "${query}".\n` +
226
- `Try: "Kane IL", "Cook County IL", "17031" (FIPS), or use list_counties to browse.\n` +
227
- REQUEST_COUNTY_HINT,
228
- },
229
- ],
270
+ content: [{ type: "text", text: coverageText(undefined, ref) }],
230
271
  };
231
272
  }
232
273
  const text = matches.map(formatCountySummary).join("\n\n" + "=".repeat(60) + "\n\n");
@@ -278,21 +319,14 @@ server.registerTool("get_parcel_endpoint", {
278
319
  content: [
279
320
  {
280
321
  type: "text",
281
- text: `County "${county}" not found in state "${state}".\n` +
282
- `Use list_counties or find_county to verify the name.\n` +
283
- REQUEST_COUNTY_HINT,
322
+ text: coverageText(undefined, { state: refState(state), county: county.trim() }),
284
323
  },
285
324
  ],
286
325
  };
287
326
  }
288
- if (countyRecord.endpoints.length === 0) {
327
+ if (!countyHasEndpoint(countyRecord)) {
289
328
  return {
290
- content: [
291
- {
292
- type: "text",
293
- text: `${countyRecord.county}, ${countyRecord.stateName} is in the atlas but has no verified REST endpoint yet.`,
294
- },
295
- ],
329
+ content: [{ type: "text", text: formatCountySummary(countyRecord) }],
296
330
  };
297
331
  }
298
332
  const lines = [
@@ -385,12 +419,16 @@ server.registerTool("build_owner_query", {
385
419
  content: [
386
420
  {
387
421
  type: "text",
388
- text: `County "${county}" not found in state "${state}". Use find_county to verify.\n` +
389
- REQUEST_COUNTY_HINT,
422
+ text: coverageText(undefined, { state: refState(stateInput), county: county.trim() }),
390
423
  },
391
424
  ],
392
425
  };
393
426
  }
427
+ if (!countyHasEndpoint(countyRecord)) {
428
+ return {
429
+ content: [{ type: "text", text: formatCountySummary(countyRecord) }],
430
+ };
431
+ }
394
432
  const results = [];
395
433
  for (const ep of countyRecord.endpoints) {
396
434
  const owner = ownerSearchPolicy(countyRecord, ep);
@@ -437,16 +475,6 @@ server.registerTool("build_owner_query", {
437
475
  ` - Add &token=<your-token> if the service requires auth (this county is public)`,
438
476
  ].join("\n"));
439
477
  }
440
- if (results.length === 0) {
441
- return {
442
- content: [
443
- {
444
- type: "text",
445
- text: `${countyRecord.county}, ${countyRecord.stateName} has no REST endpoints in the atlas yet.`,
446
- },
447
- ],
448
- };
449
- }
450
478
  return {
451
479
  content: [{ type: "text", text: results.join("\n\n" + "=".repeat(60) + "\n\n") }],
452
480
  };
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@urbankitstudio/mcp-atlas",
3
- "version": "0.3.6",
3
+ "version": "0.3.8",
4
4
  "mcpName": "io.github.urbankitstudio/mcp-atlas",
5
- "description": "Query the parcel ArcGIS REST endpoints of 395 counties across 51 US states (50 states plus DC), 413 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.",
5
+ "description": "Query the parcel ArcGIS REST endpoints of 494 counties across 51 US states (50 states plus DC), 494 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": [
7
7
  "mcp",
8
8
  "mcp-server",
@@ -51,7 +51,7 @@
51
51
  },
52
52
  "dependencies": {
53
53
  "@modelcontextprotocol/sdk": "^1.32.1",
54
- "@urbankitstudio/atlas": "^0.6.36"
54
+ "@urbankitstudio/atlas": "^0.6.38"
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/node": "^26.0.0",