@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 UrbanKit Studio
3
+ Copyright (c) 2026 UrbanKit Studio LLC
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -4,11 +4,11 @@
4
4
 
5
5
  [![mcp-atlas MCP server](https://glama.ai/mcp/servers/urbankitstudio/mcp-atlas/badges/card.svg)](https://glama.ai/mcp/servers/urbankitstudio/mcp-atlas)
6
6
 
7
- Query the parcel ArcGIS REST endpoints of 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).
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:** 494 counties across 51 US states (50 states plus DC), 494 endpoints, 493 of them live (atlas 0.6.39). 467 of the counties have an endpoint; for the other 27 the atlas records why not (see "A county we cannot serve" below).
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 hangs:
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
@@ -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 (urbankitstudio api/mcp.ts,
14
- * case "get_city_datasets"): same input caps, same enum, same street handling
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),
@@ -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 (urbankitstudio api/mcp.ts,
14
- * case "get_city_datasets"): same input caps, same enum, same street handling
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),
@@ -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. offered: the first owner-name column that is searchable (the column
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
- * 5. no_owner_column: the layer documents no owner column at all.
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. Both the query URL
69
- * (which encodes this string) and the clause printed for a human come from
70
- * here, so the two can never disagree about the scope or the escaping. The
71
- * scope is curated registry text, not user input, so it is not escaped.
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 owner names are not served.
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 {};
@@ -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. offered: the first owner-name column that is searchable (the column
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
- * 5. no_owner_column: the layer documents no owner column at all.
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
- // THE OWNER-COLUMN TEST, copied VERBATIM from the UKS canonical classifier:
36
- // urbankitstudio/src/lib/enrich-core.ts lines 48 (OWNER_RE) and 58
37
- // (OWNER_EXCLUDE), applied there by firstMatch to `${name} ${label}`. The two
38
- // copies must stay byte-equal until @urbankitstudio/atlas exports the
39
- // classifier (a queued UKS follow-up); then import it and delete these lines.
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. Both the query URL
90
- * (which encodes this string) and the clause printed for a human come from
91
- * here, so the two can never disagree about the scope or the escaping. The
92
- * scope is curated registry text, not user input, so it is not escaped.
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
- return scopeWhere ? `(${scopeWhere}) AND ${match}` : match;
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 owner names are not served.
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 "APN only (county publishes no owner name)";
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 liveFields = endpoint.searchFields
136
- .filter((sf) => sf.searchable)
137
- .map((sf) => sf.name)
138
- .join(",");
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: z
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: z
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 whitespace (a tab too) are one space: "Cook County, IL".
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: z
291
- .string()
290
+ state: freeText()
292
291
  .describe("Two-letter state abbreviation (e.g. 'IL') or full state name"),
293
- county: z
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 sampleOwnerUrl = ownerField
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
- if (ep.sampleQuery) {
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(` ${ep.sampleQuery}`);
365
+ lines.push(` ${samples.atlas}`);
365
366
  }
366
- if (sampleOwnerUrl) {
367
+ if (samples.owner) {
367
368
  lines.push("");
368
369
  lines.push(' Sample owner query (SMITH — replace with target name):');
369
- lines.push(` ${sampleOwnerUrl}`);
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), or when its owner column is not searchable by name (use a parcel-id or location query 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: z
388
- .string()
391
+ state: freeText()
389
392
  .describe("Two-letter state abbreviation (e.g. 'IL') or full state name"),
390
- county: z
391
- .string()
393
+ county: freeText()
392
394
  .describe("County name (e.g. 'Kane' or 'Kane County')"),
393
- owner_name: z
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
- let refusal;
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: z
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: z
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
- kind: z.enum(["violations", "permits", "zoning"]).optional(),
503
- street: z
504
- .string()
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.9",
3
+ "version": "0.3.11",
4
4
  "mcpName": "io.github.urbankitstudio/mcp-atlas",
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.",
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.6.39"
54
+ "@urbankitstudio/atlas": "^0.7.2"
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/node": "^26.0.0",