@urbankitstudio/mcp-atlas 0.3.7 → 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.
- package/README.md +23 -3
- package/dist/server.js +99 -71
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
# @urbankitstudio/mcp-atlas
|
|
4
4
|
|
|
5
|
-
[](https://glama.ai/mcp/servers/urbankitstudio/mcp-atlas)
|
|
6
6
|
|
|
7
|
-
Query the parcel ArcGIS REST endpoints of
|
|
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:**
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
.
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
.
|
|
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(
|
|
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
|
-
|
|
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:
|
|
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
|
|
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:
|
|
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.
|
|
3
|
+
"version": "0.3.8",
|
|
4
4
|
"mcpName": "io.github.urbankitstudio/mcp-atlas",
|
|
5
|
-
"description": "Query the parcel ArcGIS REST endpoints of
|
|
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.
|
|
54
|
+
"@urbankitstudio/atlas": "^0.6.38"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@types/node": "^26.0.0",
|