@urbankitstudio/mcp-atlas 0.3.9 → 0.3.11
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/LICENSE +1 -1
- package/README.md +68 -6
- package/dist/city-datasets.d.ts +2 -2
- package/dist/city-datasets.js +2 -2
- package/dist/search-policy.d.ts +171 -12
- package/dist/search-policy.js +338 -22
- package/dist/server.js +65 -64
- package/dist/tool-input.d.ts +23 -0
- package/dist/tool-input.js +25 -0
- package/package.json +5 -5
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -4,11 +4,11 @@
|
|
|
4
4
|
|
|
5
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 515 counties across 51 US states (50 states plus DC), 509 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:** 515 counties across 51 US states (50 states plus DC), 509 endpoints, 509 of them live (atlas 0.7.2). 481 of the counties have an endpoint; for the other 34 the atlas records why not (see "A county we cannot serve" below).
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -124,8 +124,10 @@ What each Coverage label promises:
|
|
|
124
124
|
|-------|---------|
|
|
125
125
|
| `owner+APN` | `build_owner_query` returns a URL for at least one endpoint |
|
|
126
126
|
| `APN only (county publishes no owner name)` | A reviewed record says the county serves no usable owner name |
|
|
127
|
+
| `APN only (owner name withheld)` | A reviewed record says owner names are withheld: by a statute, by the county's terms, or while we ask the county |
|
|
127
128
|
| `location queries only` | No endpoint answers attribute searches; parcels are reached by geometry, which also returns owner fields |
|
|
128
129
|
| `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 |
|
|
130
|
+
| `APN only (confidential flag incomplete)` | An owner column exists, but the layer's confidential-owner flag is malformed, so no owner query is offered |
|
|
129
131
|
| `APN only` | No endpoint documents an owner column |
|
|
130
132
|
|
|
131
133
|
---
|
|
@@ -153,7 +155,10 @@ layer index, searchable fields, owner field (or why no owner query is offered),
|
|
|
153
155
|
the county's `Scope:` predicate when the layer is shared statewide or
|
|
154
156
|
regionally, a generic sample `?where=…&f=json` query and the UrbanKit deep-link
|
|
155
157
|
for one county. For a named owner, use
|
|
156
|
-
`build_owner_query` rather than editing the sample query by hand.
|
|
158
|
+
`build_owner_query` rather than editing the sample query by hand. On a layer
|
|
159
|
+
that flags confidential owners it prints the `Confidential flag:` exclusion
|
|
160
|
+
to AND into any query of your own, and prints its own sample owner query in
|
|
161
|
+
place of the atlas's, so the one sample shown carries this server's clauses.
|
|
157
162
|
|
|
158
163
|
| Parameter | Type | Required | Description |
|
|
159
164
|
|-----------|------|----------|-------------|
|
|
@@ -174,12 +179,69 @@ returns a URL you can fetch or open. On a shared statewide or regional layer
|
|
|
174
179
|
is ANDed in front, as
|
|
175
180
|
`(scope) AND UPPER(field) LIKE …`, so only that county's rows come back.
|
|
176
181
|
|
|
182
|
+
Some layers publish an owner whose record must not be shown, and flag it in a
|
|
183
|
+
column beside the owner: Texas Tax Code §25.025 lets peace officers, judges,
|
|
184
|
+
family-violence victims and others keep their home address confidential, and
|
|
185
|
+
Harris and Collin mark those accounts (Ector carries a forward guess). On such
|
|
186
|
+
a layer the query excludes flagged rows, as
|
|
187
|
+
`(…) AND UPPER(CAST(flag AS VARCHAR(255))) NOT LIKE '%Y%'`, a contains test
|
|
188
|
+
for every flag value (Harris packs one flag per ownership slot, `YNNNNNNNNN`).
|
|
189
|
+
SQL `UPPER` matches the atlas's uppercase rule on ASCII only, so each of the 17
|
|
190
|
+
non-ASCII characters whose uppercase holds an ASCII letter (`ß`, a dotless i,
|
|
191
|
+
the `fi` ligatures, `ẙ` and the like) gets a clause of its own when it shares a
|
|
192
|
+
letter with a value: `CAST(flag AS VARCHAR(255)) NOT LIKE '%ẙ%'` drops a cell
|
|
193
|
+
holding one. Those clauses still lean on the county's database (an `UPPER` that
|
|
194
|
+
maps a-z to A-Z, a `LIKE` that reads past an embedded NUL, no cell cut off at the
|
|
195
|
+
255-character cast, one encoding for cell and literal), so the query ends with a
|
|
196
|
+
clause that does not: `flag IN (…)`, the exact raw cells the atlas lists as safe
|
|
197
|
+
(`confidentialFlag.safeValues`: Harris's blank and N runs, each 10 characters;
|
|
198
|
+
Collin `F`; Ector `0`). A row stays only when the database itself says its cell
|
|
199
|
+
equals one of those values, under its own comparison rules, so a NUL, a cut-off
|
|
200
|
+
cell or a value nobody has reviewed drops out. A backend that ignores trailing
|
|
201
|
+
spaces or case also keeps the same safe value padded differently or in another
|
|
202
|
+
case; none of those holds a flag value. A flag without safe values, or with one that holds a marker, offers no
|
|
203
|
+
owner query. On 2026-10-26 the `IN` clause kept exactly the rows the contains
|
|
204
|
+
clauses keep on all three layers (Harris 1,541,671, Collin 435,783, Ector
|
|
205
|
+
77,042), and those lists were each layer's complete distinct values.
|
|
206
|
+
A value longer than one character is a contains test too, which deliberately
|
|
207
|
+
excludes more than the atlas's trimmed-equality rule: for `SEALED`, the cells
|
|
208
|
+
` SEALED` and `UNSEALED` drop out as well. The cast lets one form serve a text
|
|
209
|
+
or an integer column, and UPPER on both sides compares the flag without regard
|
|
210
|
+
to case. A row with no flag recorded (NULL) counts as flagged and drops
|
|
211
|
+
out. The flag column comes back with each row; never show or pass on a row
|
|
212
|
+
whose flag is set.
|
|
213
|
+
|
|
177
214
|
An endpoint is refused, with the reason, rather than handed a query that finds
|
|
178
|
-
nothing or
|
|
215
|
+
nothing, hangs, or serves confidential owners:
|
|
179
216
|
|
|
180
217
|
- a reviewed record says the county publishes no usable owner name;
|
|
181
218
|
- the layer serves no attribute search at all (query it by location instead);
|
|
182
|
-
- the owner column is not searchable by name (use a parcel-id or location query)
|
|
219
|
+
- the owner column is not searchable by name (use a parcel-id or location query);
|
|
220
|
+
- the layer carries a confidential-owner flag that is present but incomplete
|
|
221
|
+
(no column, no values, or a value that is not ASCII letters and digits
|
|
222
|
+
only), so no exclusion can be built.
|
|
223
|
+
|
|
224
|
+
A refusal that points to a location, parcel-id or address read also prints the
|
|
225
|
+
layer's `Confidential flag:` line, and on a flagged layer its advice follows
|
|
226
|
+
the flag. With a well-formed flag, the read must request the flag column in
|
|
227
|
+
`outFields` and keep a row only when its flag cell is exactly one of the safe
|
|
228
|
+
values and contains no flag value, dropping every other row (a missing or NULL
|
|
229
|
+
cell included); a layer with no attribute search takes no where clause, so that
|
|
230
|
+
filtering is the reader's, and its `Confidential flag:` line gives that row
|
|
231
|
+
rule in place of "AND this into every query". With an incomplete flag, the refusal advises no
|
|
232
|
+
read at all: do not read owner fields on that layer. `find_county` and
|
|
233
|
+
`get_parcel_endpoint` carry the same advice in their `Confidential flag:` line,
|
|
234
|
+
and their Owner line says why no owner query is offered.
|
|
235
|
+
|
|
236
|
+
Every free-text argument of every tool refuses control characters (CR, LF,
|
|
237
|
+
TAB, NUL and the rest of U+0000 to U+001F, U+007F, and the C1 controls U+0080
|
|
238
|
+
to U+009F), the line and paragraph separators U+2028 and U+2029, and the whole
|
|
239
|
+
Unicode Bidi_Control set (U+061C, U+200E, U+200F, U+202A to U+202E and U+2066
|
|
240
|
+
to U+2069), so an argument echoed into an answer cannot start a line of its
|
|
241
|
+
own there or reorder how the text around it displays. Other invisible
|
|
242
|
+
characters, such as U+200B, U+FEFF and the soft hyphen U+00AD, still pass. A
|
|
243
|
+
validation error on a tool argument never repeats the value it refused (the
|
|
244
|
+
MCP SDK's own error for an unknown tool name does quote that name).
|
|
183
245
|
|
|
184
246
|
| Parameter | Type | Required | Description |
|
|
185
247
|
|-----------|------|----------|-------------|
|
|
@@ -311,4 +373,4 @@ over stdio, nothing more. It still never executes a query or returns a parcel re
|
|
|
311
373
|
|
|
312
374
|
## License
|
|
313
375
|
|
|
314
|
-
MIT — © 2026 UrbanKit Studio
|
|
376
|
+
MIT — © 2026 UrbanKit Studio LLC
|
package/dist/city-datasets.d.ts
CHANGED
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
* inside the package, so there is no "registry temporarily unavailable" case
|
|
11
11
|
* here, and every URL it returns is a string for the caller to run.
|
|
12
12
|
*
|
|
13
|
-
* It mirrors the hosted MCP tool of the same name (
|
|
14
|
-
*
|
|
13
|
+
* It mirrors the hosted MCP tool of the same name (get_city_datasets on
|
|
14
|
+
* urbankitstudio.com/api/mcp): same input caps, same enum, same street handling
|
|
15
15
|
* (cut at the first comma, then trim), and the same snake_case wire keys for the
|
|
16
16
|
* list, found, ambiguous and not-found answers. The deliberate differences:
|
|
17
17
|
* - the hosted metering sentence is gone (this server has no tiers or keys),
|
package/dist/city-datasets.js
CHANGED
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
* inside the package, so there is no "registry temporarily unavailable" case
|
|
11
11
|
* here, and every URL it returns is a string for the caller to run.
|
|
12
12
|
*
|
|
13
|
-
* It mirrors the hosted MCP tool of the same name (
|
|
14
|
-
*
|
|
13
|
+
* It mirrors the hosted MCP tool of the same name (get_city_datasets on
|
|
14
|
+
* urbankitstudio.com/api/mcp): same input caps, same enum, same street handling
|
|
15
15
|
* (cut at the first comma, then trim), and the same snake_case wire keys for the
|
|
16
16
|
* list, found, ambiguous and not-found answers. The deliberate differences:
|
|
17
17
|
* - the hosted metering sentence is gone (this server has no tiers or keys),
|
package/dist/search-policy.d.ts
CHANGED
|
@@ -22,24 +22,35 @@
|
|
|
22
22
|
* every such column `searchable: false`. A query on it hangs or errors
|
|
23
23
|
* (Orleans Parish OWNERNME1, where a column scan takes ~44 s). The owner
|
|
24
24
|
* is still returned by a parcel-id or location query.
|
|
25
|
-
* 4.
|
|
25
|
+
* 4. confidential_flag_incomplete: a searchable owner column exists, but the
|
|
26
|
+
* layer's `confidentialFlag` is present and malformed, so no exclusion can
|
|
27
|
+
* be built. A malformed flag is never read as "no flag": that would hand
|
|
28
|
+
* out the confidential owners the flag exists to keep out.
|
|
29
|
+
* 5. offered: the first owner-name column that is searchable (the column
|
|
26
30
|
* test is the UKS classifier's; see OWNER_RE below).
|
|
27
|
-
*
|
|
31
|
+
* 6. no_owner_column: the layer documents no owner column at all.
|
|
28
32
|
*
|
|
29
33
|
* Separately from the branch, `scopeWhere` is returned whenever the registry
|
|
30
34
|
* carries one. A shared statewide or regional layer holds every county's rows
|
|
31
35
|
* (FDOR `CO_NO=23` is Miami-Dade), so an unscoped query returns the whole
|
|
32
36
|
* state. ownerWhereClause ANDs the scope in front of every owner match.
|
|
37
|
+
*
|
|
38
|
+
* Likewise `confidential` is returned whenever the endpoint carries the
|
|
39
|
+
* atlas's `confidentialFlag` (0.6.43): the county's own column marking an
|
|
40
|
+
* owner whose record must not be shown (Texas Tax Code §25.025; Harris,
|
|
41
|
+
* Collin and Ector). ownerWhereClause ANDs its exclusion after the owner
|
|
42
|
+
* match, and buildArcgisOwnerQuery requests the column. A flag that is
|
|
43
|
+
* present but malformed comes back as `{ kind: "incomplete" }`, never null.
|
|
33
44
|
*/
|
|
34
|
-
import type { CountyRecord, EndpointRecord } from "@urbankitstudio/atlas";
|
|
45
|
+
import type { ConfidentialFlag, CountyRecord, EndpointRecord } from "@urbankitstudio/atlas";
|
|
35
46
|
/**
|
|
36
47
|
* The endpoint fields this policy reads, as @urbankitstudio/atlas declares them
|
|
37
48
|
* (`scopeWhere` and `attributeSearch` since 0.6.11; before that this file
|
|
38
|
-
* carried a local copy of the two).
|
|
49
|
+
* carried a local copy of the two; `confidentialFlag` since 0.6.43).
|
|
39
50
|
*/
|
|
40
|
-
export type EndpointSearchPolicyFields = Pick<EndpointRecord, "searchFields" | "scopeWhere" | "attributeSearch">;
|
|
51
|
+
export type EndpointSearchPolicyFields = Pick<EndpointRecord, "searchFields" | "scopeWhere" | "attributeSearch" | "confidentialFlag">;
|
|
41
52
|
type CountyPolicyFields = Pick<CountyRecord, "capabilityOverrides">;
|
|
42
|
-
export type OwnerSearchKind = "offered" | "reviewed_unservable" | "attribute_search_unsupported" | "owner_unsearchable" | "no_owner_column";
|
|
53
|
+
export type OwnerSearchKind = "offered" | "reviewed_unservable" | "attribute_search_unsupported" | "owner_unsearchable" | "confidential_flag_incomplete" | "no_owner_column";
|
|
43
54
|
export interface OwnerSearchPolicy {
|
|
44
55
|
kind: OwnerSearchKind;
|
|
45
56
|
/** The owner column to query. Set only when kind is "offered". */
|
|
@@ -48,7 +59,117 @@ export interface OwnerSearchPolicy {
|
|
|
48
59
|
reason: string | null;
|
|
49
60
|
/** SQL predicate scoping a shared layer to this county, or null. */
|
|
50
61
|
scopeWhere: string | null;
|
|
62
|
+
/**
|
|
63
|
+
* The layer's confidential-owner flag: the exclusion when the flag is well
|
|
64
|
+
* formed, `incomplete` when it is present but malformed. Null ONLY when the
|
|
65
|
+
* endpoint carries no flag at all, so a truthy check means "flagged".
|
|
66
|
+
*/
|
|
67
|
+
confidential: ConfidentialPolicy | null;
|
|
68
|
+
}
|
|
69
|
+
export interface ConfidentialExclusion {
|
|
70
|
+
kind: "exclude";
|
|
71
|
+
/** The flag column, requested with the owner so a reader can drop a flagged row too. */
|
|
72
|
+
field: string;
|
|
73
|
+
/** ANDed into every owner query. */
|
|
74
|
+
where: string;
|
|
75
|
+
/** The flag values, uppercased, for a reader that filters rows itself. */
|
|
76
|
+
values: string[];
|
|
77
|
+
/** The exact raw cells the layer holds for an unflagged owner; every other cell drops out. */
|
|
78
|
+
safeValues: Array<string | number>;
|
|
79
|
+
}
|
|
80
|
+
export interface IncompleteConfidentialFlag {
|
|
81
|
+
kind: "incomplete";
|
|
82
|
+
/** The flag column when it is a usable identifier, else null. */
|
|
83
|
+
field: string | null;
|
|
84
|
+
/** What is wrong with the flag record. */
|
|
85
|
+
problem: string;
|
|
51
86
|
}
|
|
87
|
+
export type ConfidentialPolicy = ConfidentialExclusion | IncompleteConfidentialFlag;
|
|
88
|
+
/**
|
|
89
|
+
* The exclusion for a layer's confidential-owner flag. Every value V is a
|
|
90
|
+
* CONTAINS test, `NOT LIKE '%V%'`: Harris packs one Y/N per ownership slot,
|
|
91
|
+
* "YNNNNNNNNN", which an equality test would keep. The atlas README makes a
|
|
92
|
+
* value longer than one character an equality test after trimming; this
|
|
93
|
+
* server makes it a contains test too, which DELIBERATELY EXCLUDES MORE than
|
|
94
|
+
* the atlas's rule (" SEALED" and "UNSEALED" both drop out for "SEALED").
|
|
95
|
+
* That is the fail-closed direction, and it needs no TRIM, which the three
|
|
96
|
+
* layers refuse (below).
|
|
97
|
+
*
|
|
98
|
+
* FAIL CLOSED ON MALFORMED METADATA. Only an absent flag (undefined) means
|
|
99
|
+
* "unflagged". A flag that is present but whose field is not a bare
|
|
100
|
+
* identifier, whose values are missing or empty, whose values are not all
|
|
101
|
+
* ASCII letters and digits, or that lists no usable safe values comes back
|
|
102
|
+
* `incomplete`: ownerSearchPolicy then
|
|
103
|
+
* offers no owner query, and get_parcel_endpoint withholds the atlas's sample
|
|
104
|
+
* query.
|
|
105
|
+
*
|
|
106
|
+
* The cell is CAST to text first. Ector's conf_flg is a small integer, and its
|
|
107
|
+
* server answers `conf_flg NOT LIKE '%1%'` (and `<> '1'`) with an ArcGIS error
|
|
108
|
+
* (code 400, inside an HTTP 200 response), which would break every Ector owner
|
|
109
|
+
* query; the cast form answers on all three
|
|
110
|
+
* layers with the same counts as the bare form (measured 2026-10-25). The atlas
|
|
111
|
+
* already reads the cell as text.
|
|
112
|
+
*
|
|
113
|
+
* The cast cell is UPPERed and so is each value, as the atlas compares after
|
|
114
|
+
* uppercasing: `UPPER(CAST(f AS VARCHAR(255))) NOT LIKE '%Y%'`. A backend whose
|
|
115
|
+
* LIKE is case-sensitive would otherwise keep a "y" cell.
|
|
116
|
+
*
|
|
117
|
+
* NON-ASCII CELLS. SQL UPPER matches JavaScript's toUpperCase on ASCII only. A
|
|
118
|
+
* non-ASCII character can only make the atlas's rule flag a cell when its
|
|
119
|
+
* JavaScript uppercase holds a letter of the value ("\u00df" reads as "SS",
|
|
120
|
+
* a dotless "\u0131" as "I", "\u1e99" as "Y" plus a ring), and a backend
|
|
121
|
+
* may leave it as it is. So every such character that shares a letter with a
|
|
122
|
+
* value gets its own `CAST(f AS VARCHAR(255)) NOT LIKE '%c%'`, on the raw cell:
|
|
123
|
+
* a cell holding one drops out. UPPER_TO_ASCII lists them all (17), and the
|
|
124
|
+
* tests recompute it over every code point. What stays assumed of the backend:
|
|
125
|
+
* UPPER maps ASCII a-z to A-Z (a Turkish-locale UPPER does not), LIKE reads the
|
|
126
|
+
* whole cell (SQLite's stops at an embedded NUL), a flag cell fits the
|
|
127
|
+
* 255-character cast, and the cell and the literals share one encoding.
|
|
128
|
+
* Measured live on 2026-10-26, Harris and Collin answer those clauses with
|
|
129
|
+
* unchanged counts and hold no such cell. Measured live on
|
|
130
|
+
* 2026-10-25, Harris and Collin already compare case-insensitively, and the
|
|
131
|
+
* UPPER form keeps the same rows as the bare form (Harris 1,541,671, Collin
|
|
132
|
+
* 435,783); Ector answers the UPPER form with 77,042.
|
|
133
|
+
*
|
|
134
|
+
* The cell is NOT trimmed: TRIM(...) gets the same ArcGIS error on all three
|
|
135
|
+
* layers. A contains test needs no trim, which is why every value uses it.
|
|
136
|
+
*
|
|
137
|
+
* SAFE VALUES CLOSE WHAT THE CLAUSES ABOVE ASSUME. The atlas lists the exact
|
|
138
|
+
* raw cells a layer holds for an unflagged owner (Harris: blank and N runs,
|
|
139
|
+
* each padded to 10 characters; Collin "F"; Ector 0), and the where ends with
|
|
140
|
+
* `f IN (<those literals>)` on the raw column: a row stays only when the
|
|
141
|
+
* backend itself says its cell equals one of them under its own comparison
|
|
142
|
+
* rules. A NUL, a cut-off cell, a character a backend uppercases differently
|
|
143
|
+
* or a new value nobody has reviewed all fail that, so the row drops out. A
|
|
144
|
+
* PAD SPACE or case-insensitive backend also keeps a safe value padded or
|
|
145
|
+
* cased differently, which holds no marker either. A flag with no safe values, or
|
|
146
|
+
* a safe value that holds a marker, is incomplete: no owner query. Measured
|
|
147
|
+
* live on 2026-10-26, the IN clause keeps exactly the rows the contains clauses
|
|
148
|
+
* keep on all three layers.
|
|
149
|
+
*
|
|
150
|
+
* NULL is FLAGGED (fail-closed), as the atlas README requires of a row that
|
|
151
|
+
* lacks the column: a NULL cell makes the comparison UNKNOWN, so the row
|
|
152
|
+
* drops out. Harris has 5,235 NULL cells and Collin 15,003, and both fall
|
|
153
|
+
* outside the clause live. Never COALESCE the cell to '' here: that would serve
|
|
154
|
+
* them. This server stays fail-closed on a NULL cell.
|
|
155
|
+
*/
|
|
156
|
+
/**
|
|
157
|
+
* Every code point outside ASCII whose JavaScript toUpperCase holds an ASCII
|
|
158
|
+
* letter or digit: Unicode's special casings (sharp s, the ligatures, the
|
|
159
|
+
* letters with a combining mark) plus the dotless i and the long s.
|
|
160
|
+
*/
|
|
161
|
+
export declare const UPPER_TO_ASCII: readonly string[];
|
|
162
|
+
export declare function confidentialExclusion(flag: ConfidentialFlag | undefined): ConfidentialPolicy | null;
|
|
163
|
+
/** The reason build_owner_query and the Owner line give for a malformed flag. */
|
|
164
|
+
export declare function incompleteFlagReason(flag: IncompleteConfidentialFlag): string;
|
|
165
|
+
/**
|
|
166
|
+
* The Confidential flag line find_county, get_parcel_endpoint and
|
|
167
|
+
* build_owner_query print, so a caller ANDs the exclusion into any query of
|
|
168
|
+
* their own, as with the scope. A malformed flag is reported as present but
|
|
169
|
+
* incomplete, never left out. A layer with no attribute search takes no
|
|
170
|
+
* where clause, so there the line gives the row rule instead of "AND this in".
|
|
171
|
+
*/
|
|
172
|
+
export declare function confidentialLine(owner: Pick<OwnerSearchPolicy, "confidential" | "kind">): string | null;
|
|
52
173
|
export declare const ATTRIBUTE_SEARCH_UNSUPPORTED_REASON = "this layer does not serve attribute searches; owner and address fields are answered only by location queries";
|
|
53
174
|
export declare const OWNER_UNSEARCHABLE_REASON = "the owner column exists but the county marks it unsearchable";
|
|
54
175
|
export declare function ownerSearchPolicy(county: CountyPolicyFields, endpoint: EndpointSearchPolicyFields): OwnerSearchPolicy;
|
|
@@ -65,23 +186,35 @@ export declare function ownerSearchPolicy(county: CountyPolicyFields, endpoint:
|
|
|
65
186
|
*/
|
|
66
187
|
export declare function escapeSqlLiteral(value: string): string;
|
|
67
188
|
/**
|
|
68
|
-
* The raw SQL owner match, scoped when the layer is shared
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
189
|
+
* The raw SQL owner match, scoped when the layer is shared and with the
|
|
190
|
+
* county's confidential owners excluded when the layer flags them. Both the
|
|
191
|
+
* query URL (which encodes this string) and the clause printed for a human
|
|
192
|
+
* come from here, so the two can never disagree about the scope, the exclusion
|
|
193
|
+
* or the escaping. The scope is curated registry text, not user input, so it
|
|
194
|
+
* is not escaped. A layer with no confidential flag gets exactly the clause it
|
|
195
|
+
* got before the flag existed. An incomplete flag throws: there is no clause
|
|
196
|
+
* that keeps its owners out, so none is built.
|
|
72
197
|
*/
|
|
73
|
-
export declare function ownerWhereClause(field: string, scopeWhere: string | null, ownerName: string): string;
|
|
198
|
+
export declare function ownerWhereClause(field: string, scopeWhere: string | null, ownerName: string, confidential: ConfidentialPolicy | null): string;
|
|
74
199
|
/**
|
|
75
200
|
* The list_counties coverage label, summarised across a county's endpoints.
|
|
76
201
|
* What each label promises a caller deciding whether to spend a request:
|
|
77
202
|
* "owner+APN" build_owner_query returns a URL for at least one endpoint.
|
|
78
203
|
* "APN only (county publishes no owner name)"
|
|
79
|
-
* a reviewed record says
|
|
204
|
+
* a reviewed record says the county serves no owner name
|
|
205
|
+
* (status not_published).
|
|
206
|
+
* "APN only (owner name withheld)"
|
|
207
|
+
* a reviewed record says owner names are withheld: by a
|
|
208
|
+
* statute, by the county's terms, or while the county is
|
|
209
|
+
* asked (status restricted).
|
|
80
210
|
* "location queries only"
|
|
81
211
|
* no endpoint answers attribute searches; parcels are
|
|
82
212
|
* reached by geometry, which also returns owner fields.
|
|
83
213
|
* "APN only (owner column not searchable)"
|
|
84
214
|
* an owner column exists but the county marks it unsearchable.
|
|
215
|
+
* "APN only (confidential flag incomplete)"
|
|
216
|
+
* an owner column exists but the layer's confidential flag
|
|
217
|
+
* is malformed, so no owner query is offered.
|
|
85
218
|
* "APN only" no endpoint documents an owner column.
|
|
86
219
|
*/
|
|
87
220
|
export declare function ownerCoverageLabel(county: CountyPolicyFields & {
|
|
@@ -95,6 +228,32 @@ export declare function ownerCoverageLabel(county: CountyPolicyFields & {
|
|
|
95
228
|
* `offersPagination`, read here, never re-derived.
|
|
96
229
|
*/
|
|
97
230
|
export declare function buildArcgisOwnerQuery(endpoint: Pick<EndpointRecord, "url" | "searchFields" | "supportsPagination">, owner: OwnerSearchPolicy, ownerQuery: string): string;
|
|
231
|
+
/**
|
|
232
|
+
* The Owner/Attribute line shared by find_county and get_parcel_endpoint. On
|
|
233
|
+
* a flagged layer the read it points to carries the flag rule, or, for an
|
|
234
|
+
* incomplete flag, gives way to "do not read owner fields here".
|
|
235
|
+
*/
|
|
236
|
+
export declare function ownerLine(owner: OwnerSearchPolicy): string;
|
|
237
|
+
/**
|
|
238
|
+
* The build_owner_query refusal for an endpoint that offers no owner query.
|
|
239
|
+
* Every refusal that points the caller at another read (by location, by parcel
|
|
240
|
+
* id or address) also carries the Confidential flag line. On a flagged layer
|
|
241
|
+
* the advice itself changes too: a well-formed flag adds the rule that read
|
|
242
|
+
* must follow, and an incomplete one replaces the read with "do not read
|
|
243
|
+
* owner fields on this layer".
|
|
244
|
+
*/
|
|
245
|
+
export declare function ownerRefusal(owner: OwnerSearchPolicy, place: string): string;
|
|
246
|
+
/**
|
|
247
|
+
* The two sample queries get_parcel_endpoint prints. On a flagged layer the
|
|
248
|
+
* atlas's own sample is withheld, well formed flag or not, so the one sample
|
|
249
|
+
* shown is built with this server's clauses (UPPER, the non-ASCII clauses and
|
|
250
|
+
* the safe values), which are stricter than the atlas's. The sample owner query
|
|
251
|
+
* is built with the exclusion, and only where an owner query is offered.
|
|
252
|
+
*/
|
|
253
|
+
export declare function parcelEndpointSamples(endpoint: Pick<EndpointRecord, "url" | "searchFields" | "supportsPagination" | "sampleQuery">, owner: OwnerSearchPolicy): {
|
|
254
|
+
atlas: string | null;
|
|
255
|
+
owner: string | null;
|
|
256
|
+
};
|
|
98
257
|
/** The build_owner_query note on how many rows the query returns. */
|
|
99
258
|
export declare function ownerQueryRowsNote(endpoint: Pick<EndpointRecord, "supportsPagination" | "maxRecordCount">): string;
|
|
100
259
|
export {};
|
package/dist/search-policy.js
CHANGED
|
@@ -22,21 +22,221 @@
|
|
|
22
22
|
* every such column `searchable: false`. A query on it hangs or errors
|
|
23
23
|
* (Orleans Parish OWNERNME1, where a column scan takes ~44 s). The owner
|
|
24
24
|
* is still returned by a parcel-id or location query.
|
|
25
|
-
* 4.
|
|
25
|
+
* 4. confidential_flag_incomplete: a searchable owner column exists, but the
|
|
26
|
+
* layer's `confidentialFlag` is present and malformed, so no exclusion can
|
|
27
|
+
* be built. A malformed flag is never read as "no flag": that would hand
|
|
28
|
+
* out the confidential owners the flag exists to keep out.
|
|
29
|
+
* 5. offered: the first owner-name column that is searchable (the column
|
|
26
30
|
* test is the UKS classifier's; see OWNER_RE below).
|
|
27
|
-
*
|
|
31
|
+
* 6. no_owner_column: the layer documents no owner column at all.
|
|
28
32
|
*
|
|
29
33
|
* Separately from the branch, `scopeWhere` is returned whenever the registry
|
|
30
34
|
* carries one. A shared statewide or regional layer holds every county's rows
|
|
31
35
|
* (FDOR `CO_NO=23` is Miami-Dade), so an unscoped query returns the whole
|
|
32
36
|
* state. ownerWhereClause ANDs the scope in front of every owner match.
|
|
37
|
+
*
|
|
38
|
+
* Likewise `confidential` is returned whenever the endpoint carries the
|
|
39
|
+
* atlas's `confidentialFlag` (0.6.43): the county's own column marking an
|
|
40
|
+
* owner whose record must not be shown (Texas Tax Code §25.025; Harris,
|
|
41
|
+
* Collin and Ector). ownerWhereClause ANDs its exclusion after the owner
|
|
42
|
+
* match, and buildArcgisOwnerQuery requests the column. A flag that is
|
|
43
|
+
* present but malformed comes back as `{ kind: "incomplete" }`, never null.
|
|
33
44
|
*/
|
|
34
45
|
import { isReviewedUnservable, offersPagination, reviewedCapability } from "@urbankitstudio/atlas";
|
|
35
|
-
//
|
|
36
|
-
//
|
|
37
|
-
//
|
|
38
|
-
|
|
39
|
-
//
|
|
46
|
+
// A bare column identifier: the field is written into the SQL unquoted, so
|
|
47
|
+
// nothing else may pass. A dotted (joined-layer) name is refused too, which
|
|
48
|
+
// fails closed.
|
|
49
|
+
const FLAG_FIELD_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
50
|
+
// A value is a SQL literal, printed in the answer, and uppercased on both sides
|
|
51
|
+
// of the comparison, so only ASCII letters and digits pass: JavaScript and the
|
|
52
|
+
// database agree on the uppercase of the VALUE, and none of them is a LIKE
|
|
53
|
+
// wildcard, a quote, whitespace or a control character. This constrains the
|
|
54
|
+
// value only, not the remote cell (see the UPPER note below). "\u00df" (which JavaScript uppercases
|
|
55
|
+
// to "SS") and the dotless "\u0131" make the flag incomplete.
|
|
56
|
+
const FLAG_VALUE_RE = /^[A-Za-z0-9]+$/;
|
|
57
|
+
// A safe value is compared whole, as a quoted SQL literal, so printable ASCII
|
|
58
|
+
// passes (padding included; a quote is doubled) except a backslash, which a
|
|
59
|
+
// backend that reads it as an escape would take as the end of the literal.
|
|
60
|
+
const SAFE_VALUE_RE = /^[\x20-\x5b\x5d-\x7e]*$/;
|
|
61
|
+
function flagProblem(flag) {
|
|
62
|
+
if (typeof flag !== "object" || flag === null) {
|
|
63
|
+
return { field: null, problem: "the flag record is not an object" };
|
|
64
|
+
}
|
|
65
|
+
const { field, values } = flag;
|
|
66
|
+
const goodField = typeof field === "string" && FLAG_FIELD_RE.test(field) ? field : null;
|
|
67
|
+
if (!goodField)
|
|
68
|
+
return { field: null, problem: "the flag names no usable column" };
|
|
69
|
+
if (!Array.isArray(values) || values.length === 0) {
|
|
70
|
+
return { field: goodField, problem: "the flag lists no values" };
|
|
71
|
+
}
|
|
72
|
+
// An index loop, on the RAW value: find(), some() and map() skip or
|
|
73
|
+
// misreport a hole ([, "Y"]) or an undefined element, and a test on the
|
|
74
|
+
// uppercased value would let "\u00df" through as "SS".
|
|
75
|
+
for (let i = 0; i < values.length; i++) {
|
|
76
|
+
const v = values[i];
|
|
77
|
+
if (typeof v !== "string" || !FLAG_VALUE_RE.test(v)) {
|
|
78
|
+
return { field: goodField, problem: "a flag value is not ASCII letters and digits only" };
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
const safe = flag.safeValues;
|
|
82
|
+
if (!Array.isArray(safe) || safe.length === 0) {
|
|
83
|
+
return { field: goodField, problem: "the flag lists no safe values" };
|
|
84
|
+
}
|
|
85
|
+
const markers = values.map((v) => v.toUpperCase());
|
|
86
|
+
const seen = new Set();
|
|
87
|
+
for (let i = 0; i < safe.length; i++) {
|
|
88
|
+
const s = safe[i];
|
|
89
|
+
if (!((typeof s === "string" && SAFE_VALUE_RE.test(s)) || (typeof s === "number" && Number.isSafeInteger(s)))) {
|
|
90
|
+
return { field: goodField, problem: "a safe value is not printable ASCII text without a backslash, or an integer" };
|
|
91
|
+
}
|
|
92
|
+
if (markers.some((m) => String(s).trim().toUpperCase().includes(m))) {
|
|
93
|
+
return { field: goodField, problem: "a safe value holds a flag value" };
|
|
94
|
+
}
|
|
95
|
+
const key = `${typeof s}:${String(s)}`;
|
|
96
|
+
if (seen.has(key))
|
|
97
|
+
return { field: goodField, problem: "a safe value repeats" };
|
|
98
|
+
seen.add(key);
|
|
99
|
+
}
|
|
100
|
+
return { field: goodField, problem: null };
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* The exclusion for a layer's confidential-owner flag. Every value V is a
|
|
104
|
+
* CONTAINS test, `NOT LIKE '%V%'`: Harris packs one Y/N per ownership slot,
|
|
105
|
+
* "YNNNNNNNNN", which an equality test would keep. The atlas README makes a
|
|
106
|
+
* value longer than one character an equality test after trimming; this
|
|
107
|
+
* server makes it a contains test too, which DELIBERATELY EXCLUDES MORE than
|
|
108
|
+
* the atlas's rule (" SEALED" and "UNSEALED" both drop out for "SEALED").
|
|
109
|
+
* That is the fail-closed direction, and it needs no TRIM, which the three
|
|
110
|
+
* layers refuse (below).
|
|
111
|
+
*
|
|
112
|
+
* FAIL CLOSED ON MALFORMED METADATA. Only an absent flag (undefined) means
|
|
113
|
+
* "unflagged". A flag that is present but whose field is not a bare
|
|
114
|
+
* identifier, whose values are missing or empty, whose values are not all
|
|
115
|
+
* ASCII letters and digits, or that lists no usable safe values comes back
|
|
116
|
+
* `incomplete`: ownerSearchPolicy then
|
|
117
|
+
* offers no owner query, and get_parcel_endpoint withholds the atlas's sample
|
|
118
|
+
* query.
|
|
119
|
+
*
|
|
120
|
+
* The cell is CAST to text first. Ector's conf_flg is a small integer, and its
|
|
121
|
+
* server answers `conf_flg NOT LIKE '%1%'` (and `<> '1'`) with an ArcGIS error
|
|
122
|
+
* (code 400, inside an HTTP 200 response), which would break every Ector owner
|
|
123
|
+
* query; the cast form answers on all three
|
|
124
|
+
* layers with the same counts as the bare form (measured 2026-10-25). The atlas
|
|
125
|
+
* already reads the cell as text.
|
|
126
|
+
*
|
|
127
|
+
* The cast cell is UPPERed and so is each value, as the atlas compares after
|
|
128
|
+
* uppercasing: `UPPER(CAST(f AS VARCHAR(255))) NOT LIKE '%Y%'`. A backend whose
|
|
129
|
+
* LIKE is case-sensitive would otherwise keep a "y" cell.
|
|
130
|
+
*
|
|
131
|
+
* NON-ASCII CELLS. SQL UPPER matches JavaScript's toUpperCase on ASCII only. A
|
|
132
|
+
* non-ASCII character can only make the atlas's rule flag a cell when its
|
|
133
|
+
* JavaScript uppercase holds a letter of the value ("\u00df" reads as "SS",
|
|
134
|
+
* a dotless "\u0131" as "I", "\u1e99" as "Y" plus a ring), and a backend
|
|
135
|
+
* may leave it as it is. So every such character that shares a letter with a
|
|
136
|
+
* value gets its own `CAST(f AS VARCHAR(255)) NOT LIKE '%c%'`, on the raw cell:
|
|
137
|
+
* a cell holding one drops out. UPPER_TO_ASCII lists them all (17), and the
|
|
138
|
+
* tests recompute it over every code point. What stays assumed of the backend:
|
|
139
|
+
* UPPER maps ASCII a-z to A-Z (a Turkish-locale UPPER does not), LIKE reads the
|
|
140
|
+
* whole cell (SQLite's stops at an embedded NUL), a flag cell fits the
|
|
141
|
+
* 255-character cast, and the cell and the literals share one encoding.
|
|
142
|
+
* Measured live on 2026-10-26, Harris and Collin answer those clauses with
|
|
143
|
+
* unchanged counts and hold no such cell. Measured live on
|
|
144
|
+
* 2026-10-25, Harris and Collin already compare case-insensitively, and the
|
|
145
|
+
* UPPER form keeps the same rows as the bare form (Harris 1,541,671, Collin
|
|
146
|
+
* 435,783); Ector answers the UPPER form with 77,042.
|
|
147
|
+
*
|
|
148
|
+
* The cell is NOT trimmed: TRIM(...) gets the same ArcGIS error on all three
|
|
149
|
+
* layers. A contains test needs no trim, which is why every value uses it.
|
|
150
|
+
*
|
|
151
|
+
* SAFE VALUES CLOSE WHAT THE CLAUSES ABOVE ASSUME. The atlas lists the exact
|
|
152
|
+
* raw cells a layer holds for an unflagged owner (Harris: blank and N runs,
|
|
153
|
+
* each padded to 10 characters; Collin "F"; Ector 0), and the where ends with
|
|
154
|
+
* `f IN (<those literals>)` on the raw column: a row stays only when the
|
|
155
|
+
* backend itself says its cell equals one of them under its own comparison
|
|
156
|
+
* rules. A NUL, a cut-off cell, a character a backend uppercases differently
|
|
157
|
+
* or a new value nobody has reviewed all fail that, so the row drops out. A
|
|
158
|
+
* PAD SPACE or case-insensitive backend also keeps a safe value padded or
|
|
159
|
+
* cased differently, which holds no marker either. A flag with no safe values, or
|
|
160
|
+
* a safe value that holds a marker, is incomplete: no owner query. Measured
|
|
161
|
+
* live on 2026-10-26, the IN clause keeps exactly the rows the contains clauses
|
|
162
|
+
* keep on all three layers.
|
|
163
|
+
*
|
|
164
|
+
* NULL is FLAGGED (fail-closed), as the atlas README requires of a row that
|
|
165
|
+
* lacks the column: a NULL cell makes the comparison UNKNOWN, so the row
|
|
166
|
+
* drops out. Harris has 5,235 NULL cells and Collin 15,003, and both fall
|
|
167
|
+
* outside the clause live. Never COALESCE the cell to '' here: that would serve
|
|
168
|
+
* them. This server stays fail-closed on a NULL cell.
|
|
169
|
+
*/
|
|
170
|
+
/**
|
|
171
|
+
* Every code point outside ASCII whose JavaScript toUpperCase holds an ASCII
|
|
172
|
+
* letter or digit: Unicode's special casings (sharp s, the ligatures, the
|
|
173
|
+
* letters with a combining mark) plus the dotless i and the long s.
|
|
174
|
+
*/
|
|
175
|
+
export const UPPER_TO_ASCII = [
|
|
176
|
+
"\u00df", "\u0131", "\u0149", "\u017f", "\u01f0", "\u1e96", "\u1e97", "\u1e98", "\u1e99",
|
|
177
|
+
"\u1e9a", "\ufb00", "\ufb01", "\ufb02", "\ufb03", "\ufb04", "\ufb05", "\ufb06",
|
|
178
|
+
];
|
|
179
|
+
export function confidentialExclusion(flag) {
|
|
180
|
+
if (flag === undefined)
|
|
181
|
+
return null;
|
|
182
|
+
const { field, problem } = flagProblem(flag);
|
|
183
|
+
if (problem !== null || field === null) {
|
|
184
|
+
return { kind: "incomplete", field, problem: problem ?? "the flag names no usable column" };
|
|
185
|
+
}
|
|
186
|
+
const raw = `CAST(${field} AS VARCHAR(255))`;
|
|
187
|
+
const values = flag.values.map((v) => v.toUpperCase());
|
|
188
|
+
const safeValues = [...flag.safeValues];
|
|
189
|
+
const expanders = UPPER_TO_ASCII.filter((ch) => [...ch.toUpperCase()].some((u) => values.some((v) => v.includes(u))));
|
|
190
|
+
const where = [
|
|
191
|
+
...values.map((v) => `UPPER(${raw}) NOT LIKE '%${escapeSqlLiteral(v)}%'`),
|
|
192
|
+
...expanders.map((ch) => `${raw} NOT LIKE '%${ch}%'`),
|
|
193
|
+
`${field} IN (${safeValues.map(sqlLiteral).join(", ")})`,
|
|
194
|
+
].join(" AND ");
|
|
195
|
+
return { kind: "exclude", field, where, values, safeValues };
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* What a read that goes around the owner query (by location or parcel id)
|
|
199
|
+
* must do on a flagged layer: bring the flag column back and keep only the rows
|
|
200
|
+
* the exclusion would keep. A location query on a layer that takes no where
|
|
201
|
+
* clause cannot AND the exclusion in, so the reader filters the rows itself.
|
|
202
|
+
*/
|
|
203
|
+
function flaggedRowRule(c) {
|
|
204
|
+
return `request ${c.field} in outFields and keep a row only when its ${c.field} cell is exactly one of ${JSON.stringify(c.safeValues)} and contains no ${c.values.join(" or ")} in any letter case; drop every other row, a missing or NULL cell included, and never show or pass on such a row`;
|
|
205
|
+
}
|
|
206
|
+
/** A safe value as a SQL literal: an integer bare, text quoted with its quotes doubled. */
|
|
207
|
+
function sqlLiteral(v) {
|
|
208
|
+
return typeof v === "number" ? String(v) : `'${escapeSqlLiteral(v)}'`;
|
|
209
|
+
}
|
|
210
|
+
/** An incomplete flag can keep no flagged owner out of any read, so none is advised. */
|
|
211
|
+
const INCOMPLETE_FLAG_NO_READ = "The layer's confidential-owner flag is incomplete, so no read can keep flagged owners out: do not read owner fields on this layer";
|
|
212
|
+
/** The reason build_owner_query and the Owner line give for a malformed flag. */
|
|
213
|
+
export function incompleteFlagReason(flag) {
|
|
214
|
+
return `the layer flags confidential owners${flag.field ? ` in ${flag.field}` : ""}, but its flag record is incomplete (${flag.problem}), so no owner query could keep them out`;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* The Confidential flag line find_county, get_parcel_endpoint and
|
|
218
|
+
* build_owner_query print, so a caller ANDs the exclusion into any query of
|
|
219
|
+
* their own, as with the scope. A malformed flag is reported as present but
|
|
220
|
+
* incomplete, never left out. A layer with no attribute search takes no
|
|
221
|
+
* where clause, so there the line gives the row rule instead of "AND this in".
|
|
222
|
+
*/
|
|
223
|
+
export function confidentialLine(owner) {
|
|
224
|
+
const c = owner.confidential;
|
|
225
|
+
if (!c)
|
|
226
|
+
return null;
|
|
227
|
+
if (c.kind === "incomplete") {
|
|
228
|
+
return `Confidential flag: present but incomplete (${c.problem}): no exclusion can be built, so no owner query is offered on this layer; do not read owner fields here`;
|
|
229
|
+
}
|
|
230
|
+
if (owner.kind === "attribute_search_unsupported") {
|
|
231
|
+
return `Confidential flag: ${c.where} (the county flags confidential owners in ${c.field}; this layer takes no where clause, so ${flaggedRowRule(c)})`;
|
|
232
|
+
}
|
|
233
|
+
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)`;
|
|
234
|
+
}
|
|
235
|
+
// THE OWNER-COLUMN TEST, copied VERBATIM from the UrbanKit Studio canonical
|
|
236
|
+
// owner classifier (OWNER_RE and OWNER_EXCLUDE), which applies them to
|
|
237
|
+
// `${name} ${label}`. The two copies must stay byte-equal until
|
|
238
|
+
// @urbankitstudio/atlas exports the classifier (a queued follow-up); then
|
|
239
|
+
// import it and delete these lines.
|
|
40
240
|
// Testing the label as well as the name is what makes Mahoning's
|
|
41
241
|
// "OWNNAME1 / Owner Name 1" an owner column. The exclude keeps owner ADDRESS
|
|
42
242
|
// and locale columns (OWNER_ADDR, OWNERCITY) from being offered as a name.
|
|
@@ -50,11 +250,13 @@ export const ATTRIBUTE_SEARCH_UNSUPPORTED_REASON = "this layer does not serve at
|
|
|
50
250
|
export const OWNER_UNSEARCHABLE_REASON = "the owner column exists but the county marks it unsearchable";
|
|
51
251
|
export function ownerSearchPolicy(county, endpoint) {
|
|
52
252
|
const scopeWhere = endpoint.scopeWhere?.trim() || null;
|
|
253
|
+
const confidential = confidentialExclusion(endpoint.confidentialFlag);
|
|
53
254
|
const refuse = (kind, reason) => ({
|
|
54
255
|
kind,
|
|
55
256
|
field: null,
|
|
56
257
|
reason,
|
|
57
258
|
scopeWhere,
|
|
259
|
+
confidential,
|
|
58
260
|
});
|
|
59
261
|
if (isReviewedUnservable(county, "owner_name")) {
|
|
60
262
|
return refuse("reviewed_unservable", reviewedCapability(county, "owner_name")?.basis?.note ??
|
|
@@ -65,8 +267,11 @@ export function ownerSearchPolicy(county, endpoint) {
|
|
|
65
267
|
}
|
|
66
268
|
const named = endpoint.searchFields.filter(isOwnerNameColumn);
|
|
67
269
|
const usable = named.find((sf) => sf.searchable !== false);
|
|
270
|
+
if (usable && confidential?.kind === "incomplete") {
|
|
271
|
+
return refuse("confidential_flag_incomplete", incompleteFlagReason(confidential));
|
|
272
|
+
}
|
|
68
273
|
if (usable)
|
|
69
|
-
return { kind: "offered", field: usable.name, reason: null, scopeWhere };
|
|
274
|
+
return { kind: "offered", field: usable.name, reason: null, scopeWhere, confidential };
|
|
70
275
|
if (named.length > 0)
|
|
71
276
|
return refuse("owner_unsearchable", OWNER_UNSEARCHABLE_REASON);
|
|
72
277
|
return refuse("no_owner_column", null);
|
|
@@ -86,39 +291,60 @@ export function escapeSqlLiteral(value) {
|
|
|
86
291
|
return value.replace(/'/g, "''");
|
|
87
292
|
}
|
|
88
293
|
/**
|
|
89
|
-
* The raw SQL owner match, scoped when the layer is shared
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
*
|
|
294
|
+
* The raw SQL owner match, scoped when the layer is shared and with the
|
|
295
|
+
* county's confidential owners excluded when the layer flags them. Both the
|
|
296
|
+
* query URL (which encodes this string) and the clause printed for a human
|
|
297
|
+
* come from here, so the two can never disagree about the scope, the exclusion
|
|
298
|
+
* or the escaping. The scope is curated registry text, not user input, so it
|
|
299
|
+
* is not escaped. A layer with no confidential flag gets exactly the clause it
|
|
300
|
+
* got before the flag existed. An incomplete flag throws: there is no clause
|
|
301
|
+
* that keeps its owners out, so none is built.
|
|
93
302
|
*/
|
|
94
|
-
export function ownerWhereClause(field, scopeWhere, ownerName) {
|
|
303
|
+
export function ownerWhereClause(field, scopeWhere, ownerName, confidential) {
|
|
304
|
+
if (confidential?.kind === "incomplete") {
|
|
305
|
+
throw new Error(`no owner query on a layer whose confidential flag is incomplete (${confidential.problem})`);
|
|
306
|
+
}
|
|
95
307
|
const match = `UPPER(${field}) LIKE UPPER('%${escapeSqlLiteral(ownerName)}%')`;
|
|
96
|
-
|
|
308
|
+
const scoped = scopeWhere ? `(${scopeWhere}) AND ${match}` : match;
|
|
309
|
+
return confidential ? `(${scoped}) AND ${confidential.where}` : scoped;
|
|
97
310
|
}
|
|
98
311
|
/**
|
|
99
312
|
* The list_counties coverage label, summarised across a county's endpoints.
|
|
100
313
|
* What each label promises a caller deciding whether to spend a request:
|
|
101
314
|
* "owner+APN" build_owner_query returns a URL for at least one endpoint.
|
|
102
315
|
* "APN only (county publishes no owner name)"
|
|
103
|
-
* a reviewed record says
|
|
316
|
+
* a reviewed record says the county serves no owner name
|
|
317
|
+
* (status not_published).
|
|
318
|
+
* "APN only (owner name withheld)"
|
|
319
|
+
* a reviewed record says owner names are withheld: by a
|
|
320
|
+
* statute, by the county's terms, or while the county is
|
|
321
|
+
* asked (status restricted).
|
|
104
322
|
* "location queries only"
|
|
105
323
|
* no endpoint answers attribute searches; parcels are
|
|
106
324
|
* reached by geometry, which also returns owner fields.
|
|
107
325
|
* "APN only (owner column not searchable)"
|
|
108
326
|
* an owner column exists but the county marks it unsearchable.
|
|
327
|
+
* "APN only (confidential flag incomplete)"
|
|
328
|
+
* an owner column exists but the layer's confidential flag
|
|
329
|
+
* is malformed, so no owner query is offered.
|
|
109
330
|
* "APN only" no endpoint documents an owner column.
|
|
110
331
|
*/
|
|
111
332
|
export function ownerCoverageLabel(county) {
|
|
112
333
|
const kinds = county.endpoints.map((ep) => ownerSearchPolicy(county, ep).kind);
|
|
113
334
|
if (kinds.includes("offered"))
|
|
114
335
|
return "owner+APN";
|
|
115
|
-
if (kinds.includes("reviewed_unservable"))
|
|
116
|
-
return
|
|
336
|
+
if (kinds.includes("reviewed_unservable")) {
|
|
337
|
+
return reviewedCapability(county, "owner_name")?.status === "restricted"
|
|
338
|
+
? "APN only (owner name withheld)"
|
|
339
|
+
: "APN only (county publishes no owner name)";
|
|
340
|
+
}
|
|
117
341
|
if (kinds.length > 0 && kinds.every((k) => k === "attribute_search_unsupported")) {
|
|
118
342
|
return "location queries only";
|
|
119
343
|
}
|
|
120
344
|
if (kinds.includes("owner_unsearchable"))
|
|
121
345
|
return "APN only (owner column not searchable)";
|
|
346
|
+
if (kinds.includes("confidential_flag_incomplete"))
|
|
347
|
+
return "APN only (confidential flag incomplete)";
|
|
122
348
|
return "APN only";
|
|
123
349
|
}
|
|
124
350
|
/**
|
|
@@ -131,11 +357,14 @@ export function ownerCoverageLabel(county) {
|
|
|
131
357
|
export function buildArcgisOwnerQuery(endpoint, owner, ownerQuery) {
|
|
132
358
|
if (!owner.field)
|
|
133
359
|
return "";
|
|
134
|
-
const where = encodeURIComponent(ownerWhereClause(owner.field, owner.scopeWhere, ownerQuery));
|
|
135
|
-
const
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
360
|
+
const where = encodeURIComponent(ownerWhereClause(owner.field, owner.scopeWhere, ownerQuery, owner.confidential));
|
|
361
|
+
const fields = endpoint.searchFields.filter((sf) => sf.searchable).map((sf) => sf.name);
|
|
362
|
+
// The flag column comes back with the owner, as the atlas asks, so whoever
|
|
363
|
+
// reads the rows can drop a flagged one as well.
|
|
364
|
+
if (owner.confidential?.kind === "exclude" && !fields.includes(owner.confidential.field)) {
|
|
365
|
+
fields.push(owner.confidential.field);
|
|
366
|
+
}
|
|
367
|
+
const liveFields = fields.join(",");
|
|
139
368
|
return (`${endpoint.url}/query` +
|
|
140
369
|
`?where=${where}` +
|
|
141
370
|
`&outFields=${liveFields}` +
|
|
@@ -143,6 +372,93 @@ export function buildArcgisOwnerQuery(endpoint, owner, ownerQuery) {
|
|
|
143
372
|
`&f=json` +
|
|
144
373
|
(offersPagination(endpoint) ? `&resultRecordCount=25` : ""));
|
|
145
374
|
}
|
|
375
|
+
/**
|
|
376
|
+
* The Owner/Attribute line shared by find_county and get_parcel_endpoint. On
|
|
377
|
+
* a flagged layer the read it points to carries the flag rule, or, for an
|
|
378
|
+
* incomplete flag, gives way to "do not read owner fields here".
|
|
379
|
+
*/
|
|
380
|
+
export function ownerLine(owner) {
|
|
381
|
+
if (owner.field)
|
|
382
|
+
return `Owner field: ${owner.field}`;
|
|
383
|
+
const c = owner.confidential;
|
|
384
|
+
if (owner.kind === "attribute_search_unsupported") {
|
|
385
|
+
const base = `Attribute search: not offered (location queries only) - ${owner.reason}`;
|
|
386
|
+
if (!c)
|
|
387
|
+
return base;
|
|
388
|
+
return c.kind === "incomplete"
|
|
389
|
+
? `${base}; the confidential flag is incomplete, so do not read owner fields here`
|
|
390
|
+
: `${base}; a location query takes no where clause, so ${flaggedRowRule(c)}`;
|
|
391
|
+
}
|
|
392
|
+
if (owner.kind === "owner_unsearchable") {
|
|
393
|
+
if (!c)
|
|
394
|
+
return "Owner field: not searchable by name (column exists; use a parcel-id or location query)";
|
|
395
|
+
return c.kind === "incomplete"
|
|
396
|
+
? "Owner field: not searchable by name (column exists, but the confidential flag is incomplete, so do not read owner fields here)"
|
|
397
|
+
: `Owner field: not searchable by name (column exists; use a parcel-id or location query, AND the Confidential flag clause into its where, and ${flaggedRowRule(c)})`;
|
|
398
|
+
}
|
|
399
|
+
if (owner.kind === "confidential_flag_incomplete") {
|
|
400
|
+
return `Owner field: not offered - ${owner.reason}`;
|
|
401
|
+
}
|
|
402
|
+
return owner.reason
|
|
403
|
+
? `Owner field: NOT AVAILABLE - ${owner.reason}`
|
|
404
|
+
: "Owner field: NONE - this layer publishes no owner column";
|
|
405
|
+
}
|
|
406
|
+
/**
|
|
407
|
+
* The build_owner_query refusal for an endpoint that offers no owner query.
|
|
408
|
+
* Every refusal that points the caller at another read (by location, by parcel
|
|
409
|
+
* id or address) also carries the Confidential flag line. On a flagged layer
|
|
410
|
+
* the advice itself changes too: a well-formed flag adds the rule that read
|
|
411
|
+
* must follow, and an incomplete one replaces the read with "do not read
|
|
412
|
+
* owner fields on this layer".
|
|
413
|
+
*/
|
|
414
|
+
export function ownerRefusal(owner, place) {
|
|
415
|
+
let refusal;
|
|
416
|
+
const c = owner.confidential;
|
|
417
|
+
switch (owner.kind) {
|
|
418
|
+
case "attribute_search_unsupported": {
|
|
419
|
+
const advice = !c
|
|
420
|
+
? "Query the layer by location (a point or envelope geometry) to read the owner fields of the parcels there."
|
|
421
|
+
: c.kind === "incomplete"
|
|
422
|
+
? `${INCOMPLETE_FLAG_NO_READ}, by location or otherwise.`
|
|
423
|
+
: `To read owner fields, query the layer by location (a point or envelope geometry). It takes no where clause, so the exclusion below cannot be ANDed in: ${flaggedRowRule(c)}.`;
|
|
424
|
+
refusal = `OWNER SEARCH NOT OFFERED on this layer for ${place}: ${owner.reason}\nNo where-clause query is possible here. ${advice}`;
|
|
425
|
+
break;
|
|
426
|
+
}
|
|
427
|
+
case "owner_unsearchable": {
|
|
428
|
+
// The owner IS published; only a name search on it is unsupported.
|
|
429
|
+
const advice = !c
|
|
430
|
+
? "Use a parcel-id or location query instead; either returns the owner of the matching parcel."
|
|
431
|
+
: c.kind === "incomplete"
|
|
432
|
+
? `${INCOMPLETE_FLAG_NO_READ}, by parcel id, location or otherwise.`
|
|
433
|
+
: `Use a parcel-id or location query instead; either returns the owner of the matching parcel. AND the exclusion below into its where, and ${flaggedRowRule(c)}.`;
|
|
434
|
+
refusal = `OWNER COLUMN NOT SEARCHABLE BY NAME for ${place}: ${owner.reason}\n${advice}`;
|
|
435
|
+
break;
|
|
436
|
+
}
|
|
437
|
+
case "reviewed_unservable":
|
|
438
|
+
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.`;
|
|
439
|
+
break;
|
|
440
|
+
case "confidential_flag_incomplete":
|
|
441
|
+
refusal = `OWNER SEARCH REFUSED for ${place}: ${owner.reason}.\nNo owner query is offered on this layer until its flag record is fixed.`;
|
|
442
|
+
break;
|
|
443
|
+
default:
|
|
444
|
+
refusal = "Note: this layer publishes no owner or taxpayer column - PIN-only lookup. Try searching by parcel number instead.";
|
|
445
|
+
}
|
|
446
|
+
const confidential = confidentialLine(owner);
|
|
447
|
+
return confidential ? `${refusal}\n${confidential}` : refusal;
|
|
448
|
+
}
|
|
449
|
+
/**
|
|
450
|
+
* The two sample queries get_parcel_endpoint prints. On a flagged layer the
|
|
451
|
+
* atlas's own sample is withheld, well formed flag or not, so the one sample
|
|
452
|
+
* shown is built with this server's clauses (UPPER, the non-ASCII clauses and
|
|
453
|
+
* the safe values), which are stricter than the atlas's. The sample owner query
|
|
454
|
+
* is built with the exclusion, and only where an owner query is offered.
|
|
455
|
+
*/
|
|
456
|
+
export function parcelEndpointSamples(endpoint, owner) {
|
|
457
|
+
return {
|
|
458
|
+
atlas: endpoint.sampleQuery && owner.confidential === null ? endpoint.sampleQuery : null,
|
|
459
|
+
owner: owner.field ? buildArcgisOwnerQuery(endpoint, owner, "SMITH") : null,
|
|
460
|
+
};
|
|
461
|
+
}
|
|
146
462
|
/** The build_owner_query note on how many rows the query returns. */
|
|
147
463
|
export function ownerQueryRowsNote(endpoint) {
|
|
148
464
|
if (offersPagination(endpoint))
|
package/dist/server.js
CHANGED
|
@@ -20,7 +20,8 @@ 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, } from "@urbankitstudio/atlas";
|
|
23
|
-
import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, escapeSqlLiteral, } from "./search-policy.js";
|
|
23
|
+
import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, escapeSqlLiteral, confidentialLine, parcelEndpointSamples, ownerRefusal, ownerLine, } from "./search-policy.js";
|
|
24
|
+
import { freeText } from "./tool-input.js";
|
|
24
25
|
import { getCityDatasets, CITY_REF_MAX_LEN, CITY_STATE_MAX_LEN, CITY_STREET_MAX_LEN, } from "./city-datasets.js";
|
|
25
26
|
// Re-exported so the package's public surface is unchanged by the move.
|
|
26
27
|
export { escapeSqlLiteral };
|
|
@@ -58,26 +59,22 @@ function refState(text) {
|
|
|
58
59
|
// ./search-policy.ts. Matching the column name is not enough, and that gap cost
|
|
59
60
|
// a real trial user: they paid for owner data, ran Los Angeles County, got
|
|
60
61
|
// nothing back, and the atlas had said the field was there the whole time.
|
|
61
|
-
/** The Owner/Attribute line shared by find_county and get_parcel_endpoint. */
|
|
62
|
-
function ownerLine(owner) {
|
|
63
|
-
if (owner.field)
|
|
64
|
-
return `Owner field: ${owner.field}`;
|
|
65
|
-
if (owner.kind === "attribute_search_unsupported") {
|
|
66
|
-
return `Attribute search: not offered (location queries only) - ${owner.reason}`;
|
|
67
|
-
}
|
|
68
|
-
if (owner.kind === "owner_unsearchable") {
|
|
69
|
-
return "Owner field: not searchable by name (column exists; use a parcel-id or location query)";
|
|
70
|
-
}
|
|
71
|
-
return owner.reason
|
|
72
|
-
? `Owner field: NOT AVAILABLE - ${owner.reason}`
|
|
73
|
-
: "Owner field: NONE - this layer publishes no owner column";
|
|
74
|
-
}
|
|
75
62
|
/** A shared layer's county predicate, printed so a caller ANDs it into any query of their own. */
|
|
76
63
|
function scopeLine(owner) {
|
|
77
64
|
return owner.scopeWhere
|
|
78
65
|
? `Scope: ${owner.scopeWhere} (shared layer; AND this into every query)`
|
|
79
66
|
: null;
|
|
80
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* The statement the publisher's terms require wherever its data is shown (a
|
|
70
|
+
* credit line, or a disclaimer such as Springfield's for Greene MO), verbatim
|
|
71
|
+
* and never shortened, on every answer about a county record that carries one,
|
|
72
|
+
* with or without an endpoint. Empty when the record names none. The hosted
|
|
73
|
+
* MCP, the REST API and the `uks` CLI key on the record the same way.
|
|
74
|
+
*/
|
|
75
|
+
function creditLine(c) {
|
|
76
|
+
return c.credit ? `Data credit: ${c.credit}` : "";
|
|
77
|
+
}
|
|
81
78
|
function formatCountySummary(c) {
|
|
82
79
|
if (!countyHasEndpoint(c)) {
|
|
83
80
|
return [
|
|
@@ -85,6 +82,7 @@ function formatCountySummary(c) {
|
|
|
85
82
|
`FIPS: ${c.countyFips ?? "n/a"}`,
|
|
86
83
|
coverageText(c, recordRef(c)),
|
|
87
84
|
c.notes ? `Notes: ${c.notes}` : "",
|
|
85
|
+
creditLine(c),
|
|
88
86
|
]
|
|
89
87
|
.filter(Boolean)
|
|
90
88
|
.join("\n");
|
|
@@ -97,11 +95,13 @@ function formatCountySummary(c) {
|
|
|
97
95
|
.map((sf) => `${sf.name} (${sf.label})`)
|
|
98
96
|
.join(", ");
|
|
99
97
|
const scope = scopeLine(owner);
|
|
98
|
+
const confidential = confidentialLine(owner);
|
|
100
99
|
return [
|
|
101
100
|
` URL: ${ep.url}`,
|
|
102
101
|
` Service: ${ep.serviceType}/layer ${ep.layerIndex}`,
|
|
103
102
|
` Status: ${ep.status} (verified ${ep.lastVerified})`,
|
|
104
103
|
...(scope ? [` ${scope}`] : []),
|
|
104
|
+
...(confidential ? [` ${confidential}`] : []),
|
|
105
105
|
` Searchable fields: ${searchable || "none"}`,
|
|
106
106
|
` ${ownerLine(owner)}`,
|
|
107
107
|
` License: ${ep.license}`,
|
|
@@ -114,6 +114,7 @@ function formatCountySummary(c) {
|
|
|
114
114
|
`Endpoints (${c.endpoints.length}):`,
|
|
115
115
|
epSummary,
|
|
116
116
|
c.notes ? `Notes: ${c.notes}` : "",
|
|
117
|
+
creditLine(c),
|
|
117
118
|
]
|
|
118
119
|
.filter(Boolean)
|
|
119
120
|
.join("\n");
|
|
@@ -126,7 +127,7 @@ const server = new McpServer(
|
|
|
126
127
|
// while the package was 0.1.6 - six releases of drift, and every MCP client
|
|
127
128
|
// that asked the server its version got the wrong answer.
|
|
128
129
|
{ name: "mcp-atlas", version: PKG_VERSION }, {
|
|
129
|
-
instructions: "UrbanKit Atlas MCP server. Use list_counties to discover coverage, find_county or get_parcel_endpoint to get the ArcGIS REST URL, and build_owner_query to construct a ready-to-fire owner-name lookup URL. get_city_datasets describes a covered city's code-violation, building-permit and zoning-case datasets and returns a ready query URL for a street; it holds no owner data.",
|
|
130
|
+
instructions: "UrbanKit Atlas MCP server. Use list_counties to discover coverage, find_county or get_parcel_endpoint to get the ArcGIS REST URL, and build_owner_query to construct a ready-to-fire owner-name lookup URL. get_city_datasets describes a covered city's code-violation, building-permit and zoning-case datasets and returns a ready query URL for a street; it holds no owner data. When an answer carries a 'Data credit:' line, the publisher requires that statement wherever its data is shown: show it verbatim with the county's results.",
|
|
130
131
|
});
|
|
131
132
|
// ---------------------------------------------------------------------------
|
|
132
133
|
// Tool: list_counties
|
|
@@ -135,8 +136,7 @@ server.registerTool("list_counties", {
|
|
|
135
136
|
title: "List covered counties",
|
|
136
137
|
description: `Browse what the atlas covers. Answers "is this county covered?" and "what can I search there?" with one line per county: state, name, slug, and whether owner-name search is available or the county publishes parcel numbers only. Deliberately returns NO endpoint URLs or field names; call get_parcel_endpoint for one county's technical record. Filter with a state abbreviation ('IL') or name ('Illinois'), or omit state for all ~${atlas.totals.counties} counties.`,
|
|
137
138
|
inputSchema: {
|
|
138
|
-
state:
|
|
139
|
-
.string()
|
|
139
|
+
state: freeText()
|
|
140
140
|
.optional()
|
|
141
141
|
.describe("Optional: two-letter state abbreviation (e.g. 'IL') or full state name (e.g. 'Illinois')"),
|
|
142
142
|
},
|
|
@@ -197,13 +197,13 @@ server.registerTool("find_county", {
|
|
|
197
197
|
title: "Resolve an uncertain county reference",
|
|
198
198
|
description: "Use when you do NOT already know the exact state and county. Fuzzy-matches one free-text reference ('Kane', 'Cook County IL', a misspelling, or a 5-digit FIPS code) against every covered county and names each county it matched, so an ambiguous reference comes back as a list to choose from rather than a silent guess. Each match carries that county's technical record, the same record get_parcel_endpoint returns for one county. Call get_parcel_endpoint directly whenever you already hold an exact state and county; come here only to turn a vague, misspelled or coded reference into definite ones.",
|
|
199
199
|
inputSchema: {
|
|
200
|
-
query:
|
|
201
|
-
.string()
|
|
200
|
+
query: freeText()
|
|
202
201
|
.min(2)
|
|
203
202
|
.describe("County name, 'County Name State' (e.g. 'Kane IL'), or 5-digit FIPS code"),
|
|
204
203
|
},
|
|
205
204
|
}, ({ query }) => {
|
|
206
|
-
// Commas and any run of
|
|
205
|
+
// Commas and any run of spaces are one space: "Cook County, IL". A tab or a
|
|
206
|
+
// line break never gets here: the schema refuses it (./tool-input.ts).
|
|
207
207
|
const q = query.toLowerCase().replace(/[\s,]+/g, " ").trim();
|
|
208
208
|
if (q.length < 2) {
|
|
209
209
|
return {
|
|
@@ -285,13 +285,11 @@ server.registerTool("find_county", {
|
|
|
285
285
|
// ---------------------------------------------------------------------------
|
|
286
286
|
server.registerTool("get_parcel_endpoint", {
|
|
287
287
|
title: "Get one county's parcel endpoint record",
|
|
288
|
-
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.",
|
|
288
|
+
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), the exclusion for owners the county flags confidential when the layer carries such a flag (AND it in too), 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.",
|
|
289
289
|
inputSchema: {
|
|
290
|
-
state:
|
|
291
|
-
.string()
|
|
290
|
+
state: freeText()
|
|
292
291
|
.describe("Two-letter state abbreviation (e.g. 'IL') or full state name"),
|
|
293
|
-
county:
|
|
294
|
-
.string()
|
|
292
|
+
county: freeText()
|
|
295
293
|
.describe("County name (e.g. 'Kane' or 'Kane County')"),
|
|
296
294
|
},
|
|
297
295
|
}, ({ state, county }) => {
|
|
@@ -337,10 +335,9 @@ server.registerTool("get_parcel_endpoint", {
|
|
|
337
335
|
countyRecord.endpoints.forEach((ep, i) => {
|
|
338
336
|
const owner = ownerSearchPolicy(countyRecord, ep);
|
|
339
337
|
const ownerField = owner.field;
|
|
340
|
-
const
|
|
341
|
-
? buildArcgisOwnerQuery(ep, owner, "SMITH")
|
|
342
|
-
: null;
|
|
338
|
+
const samples = parcelEndpointSamples(ep, owner);
|
|
343
339
|
const scope = scopeLine(owner);
|
|
340
|
+
const confidential = confidentialLine(owner);
|
|
344
341
|
lines.push(`Endpoint ${i + 1}:`);
|
|
345
342
|
lines.push(` URL: ${ep.url}`);
|
|
346
343
|
lines.push(` Service: ${ep.serviceType}`);
|
|
@@ -351,6 +348,8 @@ server.registerTool("get_parcel_endpoint", {
|
|
|
351
348
|
lines.push(` License: ${ep.license}${ep.licenseUrl ? ` (${ep.licenseUrl})` : ""}`);
|
|
352
349
|
if (scope)
|
|
353
350
|
lines.push(` ${scope}`);
|
|
351
|
+
if (confidential)
|
|
352
|
+
lines.push(` ${confidential}`);
|
|
354
353
|
lines.push("");
|
|
355
354
|
lines.push(" Searchable fields:");
|
|
356
355
|
ep.searchFields
|
|
@@ -358,21 +357,26 @@ server.registerTool("get_parcel_endpoint", {
|
|
|
358
357
|
.forEach((sf) => lines.push(` ${sf.name.padEnd(20)} – ${sf.label}`));
|
|
359
358
|
lines.push("");
|
|
360
359
|
lines.push(` ${ownerLine(owner)}`);
|
|
361
|
-
|
|
360
|
+
// parcelEndpointSamples withholds the atlas's sample on any flagged
|
|
361
|
+
// layer; the sample owner query carries the exclusion.
|
|
362
|
+
if (samples.atlas) {
|
|
362
363
|
lines.push("");
|
|
363
364
|
lines.push(" Sample query (from atlas):");
|
|
364
|
-
lines.push(` ${
|
|
365
|
+
lines.push(` ${samples.atlas}`);
|
|
365
366
|
}
|
|
366
|
-
if (
|
|
367
|
+
if (samples.owner) {
|
|
367
368
|
lines.push("");
|
|
368
369
|
lines.push(' Sample owner query (SMITH — replace with target name):');
|
|
369
|
-
lines.push(` ${
|
|
370
|
+
lines.push(` ${samples.owner}`);
|
|
370
371
|
}
|
|
371
372
|
lines.push("");
|
|
372
373
|
lines.push(` UrbanKit deep-link: https://urbankitstudio.com/tools/parcel-lookup?endpoint=${encodeURIComponent(ep.url)}${ownerField ? `&fieldHint=${ownerField}` : ""}`);
|
|
373
374
|
if (i < countyRecord.endpoints.length - 1)
|
|
374
375
|
lines.push("\n" + "-".repeat(40));
|
|
375
376
|
});
|
|
377
|
+
const credit = creditLine(countyRecord);
|
|
378
|
+
if (credit)
|
|
379
|
+
lines.push("", credit);
|
|
376
380
|
return {
|
|
377
381
|
content: [{ type: "text", text: lines.join("\n") }],
|
|
378
382
|
};
|
|
@@ -382,16 +386,13 @@ server.registerTool("get_parcel_endpoint", {
|
|
|
382
386
|
// ---------------------------------------------------------------------------
|
|
383
387
|
server.registerTool("build_owner_query", {
|
|
384
388
|
title: "Build an owner-name search URL for one county",
|
|
385
|
-
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),
|
|
389
|
+
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. Where the layer carries the county's own confidential-owner flag (Texas Tax Code §25.025), flagged rows are excluded in the query, a row with no flag recorded counts as flagged, and the flag column is returned with each row. 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 or that owner names are withheld, when the layer serves no attribute search (query it by location instead), when its owner column is not searchable by name (use a parcel-id or location query instead), or when the layer's confidential-owner flag is present but incomplete, so no exclusion can be built.",
|
|
386
390
|
inputSchema: {
|
|
387
|
-
state:
|
|
388
|
-
.string()
|
|
391
|
+
state: freeText()
|
|
389
392
|
.describe("Two-letter state abbreviation (e.g. 'IL') or full state name"),
|
|
390
|
-
county:
|
|
391
|
-
.string()
|
|
393
|
+
county: freeText()
|
|
392
394
|
.describe("County name (e.g. 'Kane' or 'Kane County')"),
|
|
393
|
-
owner_name:
|
|
394
|
-
.string()
|
|
395
|
+
owner_name: freeText()
|
|
395
396
|
.min(2)
|
|
396
397
|
.describe("Owner/taxpayer name to search for (partial match, case-insensitive)"),
|
|
397
398
|
},
|
|
@@ -438,31 +439,18 @@ server.registerTool("build_owner_query", {
|
|
|
438
439
|
// rows forever, or one that hangs. The caller can then choose a
|
|
439
440
|
// different county or query instead of concluding the owner is absent.
|
|
440
441
|
const place = `${countyRecord.county}, ${countyRecord.stateName}`;
|
|
441
|
-
|
|
442
|
-
switch (owner.kind) {
|
|
443
|
-
case "attribute_search_unsupported":
|
|
444
|
-
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.`;
|
|
445
|
-
break;
|
|
446
|
-
case "owner_unsearchable":
|
|
447
|
-
// The owner IS published; only a name search on it is unsupported.
|
|
448
|
-
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.`;
|
|
449
|
-
break;
|
|
450
|
-
case "reviewed_unservable":
|
|
451
|
-
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.`;
|
|
452
|
-
break;
|
|
453
|
-
default:
|
|
454
|
-
refusal = "Note: this layer publishes no owner or taxpayer column - PIN-only lookup. Try searching by parcel number instead.";
|
|
455
|
-
}
|
|
456
|
-
results.push(`Endpoint: ${ep.url}\n${refusal}`);
|
|
442
|
+
results.push(`Endpoint: ${ep.url}\n${ownerRefusal(owner, place)}`);
|
|
457
443
|
continue;
|
|
458
444
|
}
|
|
459
445
|
const queryUrl = buildArcgisOwnerQuery(ep, owner, owner_name);
|
|
460
|
-
const where = ownerWhereClause(ownerField, owner.scopeWhere, owner_name);
|
|
446
|
+
const where = ownerWhereClause(ownerField, owner.scopeWhere, owner_name, owner.confidential);
|
|
461
447
|
const scope = scopeLine(owner);
|
|
448
|
+
const confidential = confidentialLine(owner);
|
|
462
449
|
results.push([
|
|
463
450
|
`County: ${countyRecord.county}, ${countyRecord.stateName}`,
|
|
464
451
|
`Owner field: ${ownerField}`,
|
|
465
452
|
...(scope ? [scope] : []),
|
|
453
|
+
...(confidential ? [confidential] : []),
|
|
466
454
|
`WHERE clause: ${where}`,
|
|
467
455
|
``,
|
|
468
456
|
`Query URL:`,
|
|
@@ -470,11 +458,20 @@ server.registerTool("build_owner_query", {
|
|
|
470
458
|
``,
|
|
471
459
|
`Notes:`,
|
|
472
460
|
` - ${ownerQueryRowsNote(ep)}`,
|
|
461
|
+
...(owner.confidential?.kind === "exclude"
|
|
462
|
+
? [
|
|
463
|
+
` - Owners the county flags confidential are excluded, and a row with no flag recorded (NULL) counts as flagged. ${owner.confidential.field} comes back with each row: if one is flagged, do not show or pass it on`,
|
|
464
|
+
]
|
|
465
|
+
: []),
|
|
473
466
|
` - Partial name match (e.g. "SMITH" matches "SMITH JOHN" and "BLACKSMITH LLC")`,
|
|
474
467
|
` - Case-insensitive`,
|
|
475
468
|
` - Add &token=<your-token> if the service requires auth (this county is public)`,
|
|
476
469
|
].join("\n"));
|
|
477
470
|
}
|
|
471
|
+
// The URLs fetch the publisher's rows, so its statement goes with them.
|
|
472
|
+
const credit = creditLine(countyRecord);
|
|
473
|
+
if (credit)
|
|
474
|
+
results.push(credit);
|
|
478
475
|
return {
|
|
479
476
|
content: [{ type: "text", text: results.join("\n\n" + "=".repeat(60) + "\n\n") }],
|
|
480
477
|
};
|
|
@@ -489,19 +486,23 @@ server.registerTool("get_city_datasets", {
|
|
|
489
486
|
title: "Find a city's violation, permit and zoning datasets",
|
|
490
487
|
description: "Find the public code-violation, building-permit and zoning-case datasets UrbanKit has verified for a U.S. city, and how to query them by street. Give a city slug or name (state optional), optionally a kind ('violations', 'permits' or 'zoning') and a street; omit city to list every covered city. Returns each dataset's endpoint (Socrata, ArcGIS, CKAN or CARTO), the address column it searches, its date field and filter, coverage notes, and a ready query URL you run yourself against the city's server. This server does not execute the query and returns no city records: fetch the returned URL yourself. Returns no owner data: for a parcel's owner use get_parcel_endpoint or build_owner_query.",
|
|
491
488
|
inputSchema: {
|
|
492
|
-
city:
|
|
493
|
-
.string()
|
|
489
|
+
city: freeText()
|
|
494
490
|
.max(CITY_REF_MAX_LEN)
|
|
495
491
|
.optional()
|
|
496
492
|
.describe("City slug ('fort-worth') or name ('Fort Worth', 'Fort Worth, TX'). Omit to list covered cities."),
|
|
497
|
-
state:
|
|
498
|
-
.string()
|
|
493
|
+
state: freeText()
|
|
499
494
|
.max(CITY_STATE_MAX_LEN)
|
|
500
495
|
.optional()
|
|
501
496
|
.describe("Optional 2-letter code or state name, for a name used in two states."),
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
497
|
+
// zod's own enum error quotes the value it received, and the SDK prints
|
|
498
|
+
// that error in the answer, so a kind carrying a line break would land
|
|
499
|
+
// there raw. This message names the choices and never the input.
|
|
500
|
+
kind: z
|
|
501
|
+
.enum(["violations", "permits", "zoning"], {
|
|
502
|
+
errorMap: () => ({ message: "kind must be violations, permits or zoning" }),
|
|
503
|
+
})
|
|
504
|
+
.optional(),
|
|
505
|
+
street: freeText()
|
|
505
506
|
.max(CITY_STREET_MAX_LEN)
|
|
506
507
|
.optional()
|
|
507
508
|
.describe("Optional street line only, e.g. 'Commerce' or '600 Commerce St'. A street name alone returns the most."),
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one check every free-text tool argument passes at the boundary.
|
|
3
|
+
*
|
|
4
|
+
* Tools echo their arguments into a plain-text answer (the owner name inside
|
|
5
|
+
* the printed WHERE clause, an unknown state inside "No covered counties
|
|
6
|
+
* found"). A line break in an argument can therefore start a line of its own
|
|
7
|
+
* in that answer, such as a fake "Query URL:" heading over an unfiltered URL.
|
|
8
|
+
* SQL escaping does not help: the text stays inside the literal and still
|
|
9
|
+
* breaks the line. So every free-text argument in every tool's schema is built
|
|
10
|
+
* here, and it refuses the ASCII control characters (U+0000-U+001F and U+007F,
|
|
11
|
+
* which take in CR, LF and TAB), the C1 controls U+0080-U+009F (NEL, U+0085,
|
|
12
|
+
* is a line break to some readers, and CSI, U+009B, starts a terminal escape),
|
|
13
|
+
* the Unicode line and paragraph separators U+2028 and U+2029, and the whole
|
|
14
|
+
* Bidi_Control set (U+061C, U+200E, U+200F, U+202A-U+202E and U+2066-U+2069),
|
|
15
|
+
* which can reorder how the text is displayed. Other invisible characters,
|
|
16
|
+
* such as U+200B, U+FEFF and the soft hyphen U+00AD, still pass: they break no
|
|
17
|
+
* line and reorder nothing.
|
|
18
|
+
*/
|
|
19
|
+
import { z } from "zod/v3";
|
|
20
|
+
export declare const NO_CONTROL_CHARS_RE: RegExp;
|
|
21
|
+
export declare const CONTROL_CHARS_MESSAGE = "must not contain control characters, line breaks or bidi controls (U+0000-U+001F, U+007F-U+009F, U+061C, U+200E, U+200F, U+2028, U+2029, U+202A-U+202E, U+2066-U+2069)";
|
|
22
|
+
/** A string argument that refuses control characters, line separators and bidi controls. */
|
|
23
|
+
export declare function freeText(): z.ZodString;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one check every free-text tool argument passes at the boundary.
|
|
3
|
+
*
|
|
4
|
+
* Tools echo their arguments into a plain-text answer (the owner name inside
|
|
5
|
+
* the printed WHERE clause, an unknown state inside "No covered counties
|
|
6
|
+
* found"). A line break in an argument can therefore start a line of its own
|
|
7
|
+
* in that answer, such as a fake "Query URL:" heading over an unfiltered URL.
|
|
8
|
+
* SQL escaping does not help: the text stays inside the literal and still
|
|
9
|
+
* breaks the line. So every free-text argument in every tool's schema is built
|
|
10
|
+
* here, and it refuses the ASCII control characters (U+0000-U+001F and U+007F,
|
|
11
|
+
* which take in CR, LF and TAB), the C1 controls U+0080-U+009F (NEL, U+0085,
|
|
12
|
+
* is a line break to some readers, and CSI, U+009B, starts a terminal escape),
|
|
13
|
+
* the Unicode line and paragraph separators U+2028 and U+2029, and the whole
|
|
14
|
+
* Bidi_Control set (U+061C, U+200E, U+200F, U+202A-U+202E and U+2066-U+2069),
|
|
15
|
+
* which can reorder how the text is displayed. Other invisible characters,
|
|
16
|
+
* such as U+200B, U+FEFF and the soft hyphen U+00AD, still pass: they break no
|
|
17
|
+
* line and reorder nothing.
|
|
18
|
+
*/
|
|
19
|
+
import { z } from "zod/v3";
|
|
20
|
+
export const NO_CONTROL_CHARS_RE = /^[^\u0000-\u001F\u007F-\u009F\u061C\u200E\u200F\u2028\u2029\u202A-\u202E\u2066-\u2069]*$/;
|
|
21
|
+
export const CONTROL_CHARS_MESSAGE = "must not contain control characters, line breaks or bidi controls (U+0000-U+001F, U+007F-U+009F, U+061C, U+200E, U+200F, U+2028, U+2029, U+202A-U+202E, U+2066-U+2069)";
|
|
22
|
+
/** A string argument that refuses control characters, line separators and bidi controls. */
|
|
23
|
+
export function freeText() {
|
|
24
|
+
return z.string().regex(NO_CONTROL_CHARS_RE, CONTROL_CHARS_MESSAGE);
|
|
25
|
+
}
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@urbankitstudio/mcp-atlas",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.11",
|
|
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 515 counties across 51 US states (50 states plus DC), 509 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",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"bugs": {
|
|
28
28
|
"url": "https://github.com/urbankitstudio/mcp-atlas/issues"
|
|
29
29
|
},
|
|
30
|
-
"author": "UrbanKit Studio <contact@urbankitstudio.com>",
|
|
30
|
+
"author": "UrbanKit Studio LLC <contact@urbankitstudio.com>",
|
|
31
31
|
"license": "MIT",
|
|
32
32
|
"type": "module",
|
|
33
33
|
"main": "./dist/server.js",
|
|
@@ -46,12 +46,12 @@
|
|
|
46
46
|
"typecheck": "tsc --noEmit",
|
|
47
47
|
"smoke": "node test/smoke.mjs",
|
|
48
48
|
"test:currency": "node --test test/atlas-currency.test.mjs",
|
|
49
|
-
"test:policy": "node --test test/search-policy.test.mjs test/city-datasets.test.mjs",
|
|
49
|
+
"test:policy": "node --test test/search-policy.test.mjs test/city-datasets.test.mjs test/confirm-registry.test.mjs test/coverage-claims.test.mjs test/tool-input.test.mjs test/log-hygiene.test.mjs",
|
|
50
50
|
"prepublishOnly": "npm run typecheck && npm run build && npm run smoke && npm run test:policy"
|
|
51
51
|
},
|
|
52
52
|
"dependencies": {
|
|
53
53
|
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
54
|
-
"@urbankitstudio/atlas": "^0.
|
|
54
|
+
"@urbankitstudio/atlas": "^0.7.2"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@types/node": "^26.0.0",
|