@urbankitstudio/mcp-atlas 0.3.11 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -3
- package/dist/owner-join.d.ts +111 -0
- package/dist/owner-join.js +348 -0
- package/dist/search-policy.d.ts +31 -5
- package/dist/search-policy.js +67 -6
- package/dist/server.js +12 -6
- package/package.json +4 -4
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 539 counties across 51 US states (50 states plus DC), 522 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:** 539 counties across 51 US states (50 states plus DC), 522 endpoints, 522 of them live (atlas 0.9.1). 494 of the counties have an endpoint; for the other 45 the atlas records why not (see "A county we cannot serve" below).
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -159,6 +159,8 @@ for one county. For a named owner, use
|
|
|
159
159
|
that flags confidential owners it prints the `Confidential flag:` exclusion
|
|
160
160
|
to AND into any query of your own, and prints its own sample owner query in
|
|
161
161
|
place of the atlas's, so the one sample shown carries this server's clauses.
|
|
162
|
+
Where the owners sit in a joined table, the owner field line names the table
|
|
163
|
+
and the sample owner query goes to it.
|
|
162
164
|
|
|
163
165
|
| Parameter | Type | Required | Description |
|
|
164
166
|
|-----------|------|----------|-------------|
|
|
@@ -179,10 +181,36 @@ returns a URL you can fetch or open. On a shared statewide or regional layer
|
|
|
179
181
|
is ANDed in front, as
|
|
180
182
|
`(scope) AND UPPER(field) LIKE …`, so only that county's rows come back.
|
|
181
183
|
|
|
184
|
+
Some counties keep their owners in a separate table of the parcel service,
|
|
185
|
+
joined to the parcel layer on a key (the atlas's `ownerJoin`; Sussex County DE
|
|
186
|
+
is the first, since atlas 0.9.1). There the query goes to the table, not
|
|
187
|
+
the layer: the same `UPPER(field) LIKE …` on the table's owner column, with the
|
|
188
|
+
parcel key and the searchable owner and mailing columns in `outFields`, `orderByFields`
|
|
189
|
+
so that pages read with `resultOffset` come in one order, and no geometry
|
|
190
|
+
parameter, which a table ignores. The rows are ownership records, one or more
|
|
191
|
+
per parcel, and the notes under the URL say how to read them: discard the
|
|
192
|
+
whole response if any row does not hold the searched name in the owner column
|
|
193
|
+
(the table did not apply the where clause), de-duplicate the rows of one key
|
|
194
|
+
by the owner and mailing values (accents, case and invisible characters do not
|
|
195
|
+
make a second row, though "PEÑA" and "PENA" stay two), drop a row whose
|
|
196
|
+
values another row of the key already carries (the same owner once with and
|
|
197
|
+
once without a mailing line is one record), and state no owner for a key left
|
|
198
|
+
with more different rows than the record allows, or for a row whose key is
|
|
199
|
+
blank or only invisible characters. These follow the UrbanKit Studio engine's
|
|
200
|
+
rules, with the two small differences the CHANGELOG names.
|
|
201
|
+
`readOwnerJoinRows` in `dist/owner-join.js` holds the same
|
|
202
|
+
rules in code. A join is used only where
|
|
203
|
+
the atlas's validator accepts one: beside a withheld owner or mailing column,
|
|
204
|
+
a scope, a shared service, a confidential flag, a layer that does not page or
|
|
205
|
+
takes no attribute search, or a `wireName`, the record is served as its plain
|
|
206
|
+
layer.
|
|
207
|
+
|
|
182
208
|
Some layers publish an owner whose record must not be shown, and flag it in a
|
|
183
209
|
column beside the owner: Texas Tax Code §25.025 lets peace officers, judges,
|
|
184
210
|
family-violence victims and others keep their home address confidential, and
|
|
185
|
-
Harris and Collin mark those accounts (Ector carries a forward guess).
|
|
211
|
+
Harris and Collin mark those accounts (Ector carries a forward guess). Brown
|
|
212
|
+
County WI flags its confidential rows in `Confidential` (`1`, safe value `0`,
|
|
213
|
+
atlas 0.8.0) and gets the same exclusion. On such
|
|
186
214
|
a layer the query excludes flagged rows, as
|
|
187
215
|
`(…) AND UPPER(CAST(flag AS VARCHAR(255))) NOT LIKE '%Y%'`, a contains test
|
|
188
216
|
for every flag value (Harris packs one flag per ownership slot, `YNNNNNNNNN`).
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The owner join: owner rows a county keeps in a separate TABLE of its parcel
|
|
3
|
+
* service (atlas 0.9.0 `ownerJoin`).
|
|
4
|
+
*
|
|
5
|
+
* Sussex County DE is the first: its parcel polygons are keyed on `Name` (the
|
|
6
|
+
* PIN) and its owners sit in table 1 of the same service, keyed on `PIN`, one
|
|
7
|
+
* or more rows per parcel. On such a record the layer's own searchFields carry
|
|
8
|
+
* no owner column, so a reader that knows nothing of the join sees a
|
|
9
|
+
* parcel-number-only layer. That is the safe default, and it is what this
|
|
10
|
+
* server answered before 0.4.0.
|
|
11
|
+
*
|
|
12
|
+
* An owner-name search on such a record goes to the TABLE, as an attribute
|
|
13
|
+
* query and nothing else: a `where` on the table's owner column, never a
|
|
14
|
+
* geometry parameter. A table has no geometry and ignores one, answering with
|
|
15
|
+
* arbitrary rows.
|
|
16
|
+
*
|
|
17
|
+
* This file holds the same rules as UrbanKit Studio's own join engine and as
|
|
18
|
+
* rule J8 of the registry validator: when a join may be used at all
|
|
19
|
+
* (usableOwnerJoin), which columns one table request asks for
|
|
20
|
+
* (ownerJoinOutFields), and how its rows are read (readOwnerJoinRows). The
|
|
21
|
+
* site's engine asks the table by key and checks that every row echoes a key
|
|
22
|
+
* it asked; an owner-name search asks by owner, so the echo it checks is the
|
|
23
|
+
* owner predicate.
|
|
24
|
+
*
|
|
25
|
+
* THIS SERVER BUILDS THE URL AND NEVER FETCHES IT, so no tool here sees a row.
|
|
26
|
+
* The reading rules reach a caller two ways, and both come from this file:
|
|
27
|
+
* ownerJoinNotes is the text build_owner_query prints under the URL, and
|
|
28
|
+
* readOwnerJoinRows is the same rules in code, shipped in dist/owner-join.js
|
|
29
|
+
* for a caller that reads the rows with this package. No fetch, no clock.
|
|
30
|
+
*/
|
|
31
|
+
import type { CountyRecord, EndpointRecord, OwnerJoin } from "@urbankitstudio/atlas";
|
|
32
|
+
/** The endpoint fields that decide whether its join may be used. */
|
|
33
|
+
export type OwnerJoinEndpointFields = Pick<EndpointRecord, "searchFields" | "ownerJoin" | "scopeWhere" | "sharedService" | "confidentialFlag" | "supportsPagination" | "attributeSearch">;
|
|
34
|
+
type CountyJoinFields = Pick<CountyRecord, "capabilityOverrides">;
|
|
35
|
+
/** One table row: the `attributes` of a returned feature, cut to the columns asked for. */
|
|
36
|
+
export type OwnerJoinRow = Record<string, unknown>;
|
|
37
|
+
/**
|
|
38
|
+
* The join an owner query may use on this endpoint, or null. Null means the
|
|
39
|
+
* record is served as the plain layer its searchFields describe, and the table
|
|
40
|
+
* is never named or asked.
|
|
41
|
+
*/
|
|
42
|
+
export declare function usableOwnerJoin(county: CountyJoinFields, endpoint: OwnerJoinEndpointFields): OwnerJoin | null;
|
|
43
|
+
/** The table's layer URL without a trailing slash, ready for `/query`. */
|
|
44
|
+
export declare function ownerJoinTableUrl(join: OwnerJoin): string;
|
|
45
|
+
/**
|
|
46
|
+
* The columns one owner-name query asks the table for: the parcel key first,
|
|
47
|
+
* then the content columns, and the searched owner column whatever its flags.
|
|
48
|
+
*/
|
|
49
|
+
export declare function ownerJoinOutFields(join: OwnerJoin, ownerField: string): string[];
|
|
50
|
+
/** The most different rows one key may hold and still be read as its owners.
|
|
51
|
+
* Without `multiple: "rows"`, or with a ceiling that is not a positive
|
|
52
|
+
* integer, it is 1: picking one of several owners would be a guess. */
|
|
53
|
+
export declare function ownerJoinRowCap(join: OwnerJoin): number;
|
|
54
|
+
/**
|
|
55
|
+
* Does this owner cell satisfy the predicate the query sent,
|
|
56
|
+
* `UPPER(col) LIKE UPPER('%<name>%')`? A `%` or `_` inside the name is a LIKE
|
|
57
|
+
* wildcard on the county's server (the where clause escapes quotes only), so
|
|
58
|
+
* it is one here. A cell that is not text never matches: SQL keeps no row
|
|
59
|
+
* whose owner is NULL under that predicate.
|
|
60
|
+
*/
|
|
61
|
+
export declare function ownerCellMatches(cell: unknown, ownerQuery: string): boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Did the table answer the question that was asked? True only when EVERY
|
|
64
|
+
* returned row holds the searched name in the owner column. A table that
|
|
65
|
+
* ignores `where` returns its first rows whatever was asked; one stray row
|
|
66
|
+
* fails the whole response, because a server that ignored the clause once
|
|
67
|
+
* cannot be trusted on the rows that happen to match.
|
|
68
|
+
*/
|
|
69
|
+
export declare function verifyOwnerEcho(rows: readonly OwnerJoinRow[], ownerField: string, ownerQuery: string): boolean;
|
|
70
|
+
/**
|
|
71
|
+
* What the table said about one parcel key.
|
|
72
|
+
* joined its matching ownership rows, de-duplicated, within the row cap
|
|
73
|
+
* ambiguous more different rows than the record allows: none is served
|
|
74
|
+
*/
|
|
75
|
+
export type OwnerJoinKeyRows = {
|
|
76
|
+
state: "joined";
|
|
77
|
+
rows: OwnerJoinRow[];
|
|
78
|
+
} | {
|
|
79
|
+
state: "ambiguous";
|
|
80
|
+
count: number;
|
|
81
|
+
};
|
|
82
|
+
export type OwnerJoinRead = {
|
|
83
|
+
ok: true;
|
|
84
|
+
/** Parcel key to its rows, in first-seen order. */
|
|
85
|
+
byKey: Map<string, OwnerJoinKeyRows>;
|
|
86
|
+
/** Rows that matched but carry no usable key: tied to no parcel, so not served. */
|
|
87
|
+
unkeyed: number;
|
|
88
|
+
} | {
|
|
89
|
+
ok: false;
|
|
90
|
+
reason: "join-integrity";
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* Read the features of an owner-name query against the table.
|
|
94
|
+
*
|
|
95
|
+
* `features` is the response's `features` array, every page read so far.
|
|
96
|
+
* `ownerField` and `ownerQuery` are the column and the name the query was
|
|
97
|
+
* built with. The whole result is refused as `join-integrity` when any row
|
|
98
|
+
* fails the owner echo; otherwise each key's rows are de-duplicated by content
|
|
99
|
+
* and held to the record's row cap.
|
|
100
|
+
*
|
|
101
|
+
* A key's rows here are the ones that matched the name. The parcel may hold
|
|
102
|
+
* other owners, which a name search does not return.
|
|
103
|
+
*/
|
|
104
|
+
export declare function readOwnerJoinRows(join: OwnerJoin, ownerField: string, ownerQuery: string, features: readonly unknown[]): OwnerJoinRead;
|
|
105
|
+
/**
|
|
106
|
+
* The notes build_owner_query prints under a table query: what the rows are,
|
|
107
|
+
* and the reading rules of readOwnerJoinRows in words, since the caller
|
|
108
|
+
* fetches the URL and this server never sees a row.
|
|
109
|
+
*/
|
|
110
|
+
export declare function ownerJoinNotes(join: OwnerJoin, ownerField: string, layerUrl: string): string[];
|
|
111
|
+
export {};
|
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The owner join: owner rows a county keeps in a separate TABLE of its parcel
|
|
3
|
+
* service (atlas 0.9.0 `ownerJoin`).
|
|
4
|
+
*
|
|
5
|
+
* Sussex County DE is the first: its parcel polygons are keyed on `Name` (the
|
|
6
|
+
* PIN) and its owners sit in table 1 of the same service, keyed on `PIN`, one
|
|
7
|
+
* or more rows per parcel. On such a record the layer's own searchFields carry
|
|
8
|
+
* no owner column, so a reader that knows nothing of the join sees a
|
|
9
|
+
* parcel-number-only layer. That is the safe default, and it is what this
|
|
10
|
+
* server answered before 0.4.0.
|
|
11
|
+
*
|
|
12
|
+
* An owner-name search on such a record goes to the TABLE, as an attribute
|
|
13
|
+
* query and nothing else: a `where` on the table's owner column, never a
|
|
14
|
+
* geometry parameter. A table has no geometry and ignores one, answering with
|
|
15
|
+
* arbitrary rows.
|
|
16
|
+
*
|
|
17
|
+
* This file holds the same rules as UrbanKit Studio's own join engine and as
|
|
18
|
+
* rule J8 of the registry validator: when a join may be used at all
|
|
19
|
+
* (usableOwnerJoin), which columns one table request asks for
|
|
20
|
+
* (ownerJoinOutFields), and how its rows are read (readOwnerJoinRows). The
|
|
21
|
+
* site's engine asks the table by key and checks that every row echoes a key
|
|
22
|
+
* it asked; an owner-name search asks by owner, so the echo it checks is the
|
|
23
|
+
* owner predicate.
|
|
24
|
+
*
|
|
25
|
+
* THIS SERVER BUILDS THE URL AND NEVER FETCHES IT, so no tool here sees a row.
|
|
26
|
+
* The reading rules reach a caller two ways, and both come from this file:
|
|
27
|
+
* ownerJoinNotes is the text build_owner_query prints under the URL, and
|
|
28
|
+
* readOwnerJoinRows is the same rules in code, shipped in dist/owner-join.js
|
|
29
|
+
* for a caller that reads the rows with this package. No fetch, no clock.
|
|
30
|
+
*/
|
|
31
|
+
import { offersAttributeSearch, offersPagination, reviewedCapability } from "@urbankitstudio/atlas";
|
|
32
|
+
/**
|
|
33
|
+
* Is anything beside the join that the join path does not handle? The
|
|
34
|
+
* registry validator refuses each of these on a record with an ownerJoin
|
|
35
|
+
* "until that combination is built" (its rule J8), so no published record is
|
|
36
|
+
* expected to reach a true here. This is the same refusal at run time, for a
|
|
37
|
+
* record that got past the validator:
|
|
38
|
+
* - the county withholds owner or mailing columns (a reviewed `restricted`
|
|
39
|
+
* record): withheld columns are marked on searchFields, and nothing marks
|
|
40
|
+
* the table's;
|
|
41
|
+
* - scopeWhere or sharedService: the service holds other counties' rows, and
|
|
42
|
+
* the scope is a predicate on the layer, not on the table;
|
|
43
|
+
* - confidentialFlag: the flag is on the polygon row, the owner on the table
|
|
44
|
+
* row, so no exclusion could be ANDed into the table query. Any flag that
|
|
45
|
+
* is present counts, well formed or not;
|
|
46
|
+
* - supportsPagination: false: the table is read in pages;
|
|
47
|
+
* - attributeSearch "unsupported": the table is asked by `where` and nothing
|
|
48
|
+
* else;
|
|
49
|
+
* - any wireName, on either field list: the join path sends bare names.
|
|
50
|
+
*/
|
|
51
|
+
function joinCompanionRefused(county, endpoint, join) {
|
|
52
|
+
return (reviewedCapability(county, "owner_name")?.status === "restricted" ||
|
|
53
|
+
reviewedCapability(county, "owner_mailing_address")?.status === "restricted" ||
|
|
54
|
+
endpoint.scopeWhere !== undefined ||
|
|
55
|
+
endpoint.sharedService === true ||
|
|
56
|
+
endpoint.confidentialFlag !== undefined ||
|
|
57
|
+
!offersPagination(endpoint) ||
|
|
58
|
+
!offersAttributeSearch(endpoint) ||
|
|
59
|
+
[...endpoint.searchFields, ...join.fields].some((f) => f.wireName !== undefined));
|
|
60
|
+
}
|
|
61
|
+
/** Whether the join record has the parts a table query is built from. */
|
|
62
|
+
function joinReadable(join) {
|
|
63
|
+
const text = (v) => typeof v === "string" && v.trim() !== "";
|
|
64
|
+
return (text(join.url) &&
|
|
65
|
+
text(join.key) &&
|
|
66
|
+
text(join.parcelKey) &&
|
|
67
|
+
text(join.orderField) &&
|
|
68
|
+
Array.isArray(join.fields) &&
|
|
69
|
+
join.fields.every((f) => typeof f === "object" && f !== null && text(f.name)) &&
|
|
70
|
+
join.fields.some((f) => f.name === join.key));
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* The join an owner query may use on this endpoint, or null. Null means the
|
|
74
|
+
* record is served as the plain layer its searchFields describe, and the table
|
|
75
|
+
* is never named or asked.
|
|
76
|
+
*/
|
|
77
|
+
export function usableOwnerJoin(county, endpoint) {
|
|
78
|
+
const join = endpoint.ownerJoin;
|
|
79
|
+
if (typeof join !== "object" || join === null || !joinReadable(join))
|
|
80
|
+
return null;
|
|
81
|
+
// ANCHOR owner-join-companions
|
|
82
|
+
return joinCompanionRefused(county, endpoint, join) ? null : join;
|
|
83
|
+
}
|
|
84
|
+
/** The table's layer URL without a trailing slash, ready for `/query`. */
|
|
85
|
+
export function ownerJoinTableUrl(join) {
|
|
86
|
+
return join.url.replace(/\/+$/, "");
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* The table columns that carry what a row serves: every documented searchable
|
|
90
|
+
* column except the key, the row label and the order column, the same
|
|
91
|
+
* searchable-only rule build_owner_query applies to a parcel layer. On Sussex DE
|
|
92
|
+
* that is the owner name alone: the record marks its mailing columns
|
|
93
|
+
* `searchable: false`, so they are never requested. The row label (`rowIdField`) is left
|
|
94
|
+
* out on purpose: it is not unique, and two rows that differ only by it are
|
|
95
|
+
* one ownership record.
|
|
96
|
+
*/
|
|
97
|
+
function ownerJoinContentFields(join) {
|
|
98
|
+
const skipped = new Set([join.key, join.rowIdField, join.orderField]);
|
|
99
|
+
// Bare names: usableOwnerJoin refuses a join beside any wireName.
|
|
100
|
+
return join.fields.filter((f) => f.searchable && !skipped.has(f.name)).map((f) => f.name);
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* The columns one owner-name query asks the table for: the parcel key first,
|
|
104
|
+
* then the content columns, and the searched owner column whatever its flags.
|
|
105
|
+
*/
|
|
106
|
+
export function ownerJoinOutFields(join, ownerField) {
|
|
107
|
+
const fields = [join.key, ...ownerJoinContentFields(join)];
|
|
108
|
+
if (!fields.includes(ownerField))
|
|
109
|
+
fields.push(ownerField);
|
|
110
|
+
return fields;
|
|
111
|
+
}
|
|
112
|
+
/** The most different rows one key may hold and still be read as its owners.
|
|
113
|
+
* Without `multiple: "rows"`, or with a ceiling that is not a positive
|
|
114
|
+
* integer, it is 1: picking one of several owners would be a guess. */
|
|
115
|
+
export function ownerJoinRowCap(join) {
|
|
116
|
+
const cap = join.maxRowsPerKey;
|
|
117
|
+
return join.multiple === "rows" && typeof cap === "number" && Number.isInteger(cap) && cap >= 1 ? cap : 1;
|
|
118
|
+
}
|
|
119
|
+
/** Text as the owner comparison reads it: compatibility forms and accents
|
|
120
|
+
* folded away, then upper-cased. A county database decides for itself what
|
|
121
|
+
* LIKE matches, and one that ignores accents honestly returns an accented
|
|
122
|
+
* name for a plain search, so such a row is not a stray one. */
|
|
123
|
+
function foldName(text) {
|
|
124
|
+
return [...text.normalize("NFKD").replace(/\p{M}/gu, "").toUpperCase()];
|
|
125
|
+
}
|
|
126
|
+
/** SQL LIKE over code points: `%` is any run, `_` is any one character. */
|
|
127
|
+
function likeMatches(text, pattern) {
|
|
128
|
+
let t = 0;
|
|
129
|
+
let p = 0;
|
|
130
|
+
let run = -1;
|
|
131
|
+
let resume = 0;
|
|
132
|
+
while (t < text.length) {
|
|
133
|
+
if (p < pattern.length && pattern[p] === "%") {
|
|
134
|
+
run = p++;
|
|
135
|
+
resume = t;
|
|
136
|
+
}
|
|
137
|
+
else if (p < pattern.length && (pattern[p] === "_" || pattern[p] === text[t])) {
|
|
138
|
+
p++;
|
|
139
|
+
t++;
|
|
140
|
+
}
|
|
141
|
+
else if (run !== -1) {
|
|
142
|
+
p = run + 1;
|
|
143
|
+
t = ++resume;
|
|
144
|
+
}
|
|
145
|
+
else {
|
|
146
|
+
return false;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
while (p < pattern.length && pattern[p] === "%")
|
|
150
|
+
p++;
|
|
151
|
+
return p === pattern.length;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Does this owner cell satisfy the predicate the query sent,
|
|
155
|
+
* `UPPER(col) LIKE UPPER('%<name>%')`? A `%` or `_` inside the name is a LIKE
|
|
156
|
+
* wildcard on the county's server (the where clause escapes quotes only), so
|
|
157
|
+
* it is one here. A cell that is not text never matches: SQL keeps no row
|
|
158
|
+
* whose owner is NULL under that predicate.
|
|
159
|
+
*/
|
|
160
|
+
export function ownerCellMatches(cell, ownerQuery) {
|
|
161
|
+
if (typeof cell !== "string")
|
|
162
|
+
return false;
|
|
163
|
+
return likeMatches(foldName(cell), ["%", ...foldName(ownerQuery), "%"]);
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Did the table answer the question that was asked? True only when EVERY
|
|
167
|
+
* returned row holds the searched name in the owner column. A table that
|
|
168
|
+
* ignores `where` returns its first rows whatever was asked; one stray row
|
|
169
|
+
* fails the whole response, because a server that ignored the clause once
|
|
170
|
+
* cannot be trusted on the rows that happen to match.
|
|
171
|
+
*/
|
|
172
|
+
export function verifyOwnerEcho(rows, ownerField, ownerQuery) {
|
|
173
|
+
// ANCHOR owner-join-echo
|
|
174
|
+
return rows.every((row) => ownerCellMatches(row[ownerField], ownerQuery));
|
|
175
|
+
}
|
|
176
|
+
/** A key as both sides compare it: trimmed, nothing else. Null for a value
|
|
177
|
+
* that is neither text nor a safe integer (JSON.parse has already rounded an
|
|
178
|
+
* integer past 2^53, so its digits can be another parcel's), and for a visibly
|
|
179
|
+
* blank one: a key of only zero-width, control or filler characters is blank,
|
|
180
|
+
* as the UrbanKit Studio engine's normalizeJoinKey reads it. */
|
|
181
|
+
function joinKeyOf(value) {
|
|
182
|
+
if (typeof value !== "string" && !(typeof value === "number" && Number.isSafeInteger(value)))
|
|
183
|
+
return null;
|
|
184
|
+
const key = String(value).trim();
|
|
185
|
+
// ANCHOR owner-join-key-blank
|
|
186
|
+
return visibleText(key) === "" ? null : key;
|
|
187
|
+
}
|
|
188
|
+
/** One returned feature cut to the columns that were asked for. Anything else
|
|
189
|
+
* the server sent is dropped here; a feature with no `attributes` object is an
|
|
190
|
+
* empty row, which fails the echo check. */
|
|
191
|
+
function projectFeature(feature, fields) {
|
|
192
|
+
const out = {};
|
|
193
|
+
const attributes = typeof feature === "object" && feature !== null ? feature.attributes : null;
|
|
194
|
+
if (typeof attributes !== "object" || attributes === null)
|
|
195
|
+
return out;
|
|
196
|
+
for (const field of fields) {
|
|
197
|
+
if (Object.prototype.hasOwnProperty.call(attributes, field))
|
|
198
|
+
out[field] = attributes[field];
|
|
199
|
+
}
|
|
200
|
+
return out;
|
|
201
|
+
}
|
|
202
|
+
/** Control characters (C0 and C1), NUL included. */
|
|
203
|
+
const CONTROL_RE = /\p{Cc}/gu;
|
|
204
|
+
/** Format characters: zero-width space and joiners, word joiner, BOM, soft hyphen. */
|
|
205
|
+
const FORMAT_RE = /\p{Cf}/gu;
|
|
206
|
+
/** Combining marks of every kind (Mn, Mc, Me). */
|
|
207
|
+
const MARK_RE = /\p{M}/gu;
|
|
208
|
+
/** Variation selectors, Mongolian free variation selectors, Khmer U+17B4 and U+17B5, the Hangul fillers. */
|
|
209
|
+
const IGNORABLE_RE = /\p{Default_Ignorable_Code_Point}/gu;
|
|
210
|
+
/** The six fillers that render blank: the braille blank, the four Hangul fillers and the musical null notehead. */
|
|
211
|
+
const BLANK_FILLER_RE = /[\u2800\u3164\u115f\u1160\uffa0\u{1d159}]/gu;
|
|
212
|
+
/** The text with every character that renders as nothing removed and each run of
|
|
213
|
+
* whitespace made one space, trimmed. This is UrbanKit Studio's `visibleText`
|
|
214
|
+
* (src/lib/blank-cell.ts), character for character. */
|
|
215
|
+
function visibleText(text) {
|
|
216
|
+
return text
|
|
217
|
+
.replace(/\s+/gu, " ")
|
|
218
|
+
.replace(CONTROL_RE, "")
|
|
219
|
+
.replace(FORMAT_RE, "")
|
|
220
|
+
.replace(MARK_RE, "")
|
|
221
|
+
.replace(IGNORABLE_RE, "")
|
|
222
|
+
.replace(BLANK_FILLER_RE, "")
|
|
223
|
+
.replace(/\s+/gu, " ")
|
|
224
|
+
.trim();
|
|
225
|
+
}
|
|
226
|
+
/** One content cell as the de-duplication compares it: NFKC-normalised, only
|
|
227
|
+
* the visible text, upper-cased. Null for a missing, null or visibly blank cell,
|
|
228
|
+
* which serves nothing. Accents stay: "PEÑA" and "PENA" are two values (the
|
|
229
|
+
* owner echo folds them, this does not). */
|
|
230
|
+
function comparedCell(value) {
|
|
231
|
+
if (value === null || value === undefined)
|
|
232
|
+
return null;
|
|
233
|
+
// ANCHOR owner-join-nfkc
|
|
234
|
+
const text = visibleText(String(value).normalize("NFKC")).toUpperCase();
|
|
235
|
+
return text === "" ? null : text;
|
|
236
|
+
}
|
|
237
|
+
/** Does `wide` carry every value `narrow` carries? A null cell of `narrow` carries nothing. */
|
|
238
|
+
function subsumes(wide, narrow) {
|
|
239
|
+
return narrow.every((cell, i) => cell === null || cell === wide[i]);
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* The rows of one key, one per distinct served content, first occurrence kept;
|
|
243
|
+
* then a row that says nothing another kept row does not is dropped. This is the
|
|
244
|
+
* rule of UrbanKit Studio's join engine (dedupeJoinRows in its
|
|
245
|
+
* radius-join-core.ts), applied to the content columns.
|
|
246
|
+
*
|
|
247
|
+
* Cells compare as `visibleText(String(cell).normalize("NFKC")).toUpperCase()`:
|
|
248
|
+
* each run of whitespace is one space and the characters that render as nothing
|
|
249
|
+
* (controls, format characters such as a zero-width space, combining marks,
|
|
250
|
+
* default-ignorable code points, the blank fillers) are removed. So "SMITH JOHN",
|
|
251
|
+
* the same with two inner spaces and the same with a trailing zero-width space
|
|
252
|
+
* are one row, and so are one name's precomposed and decomposed accents, while
|
|
253
|
+
* "PEÑA" and "PENA" stay two. A null, missing or visibly blank cell is null and
|
|
254
|
+
* serves nothing. Only the comparison folds; the row kept is returned as the
|
|
255
|
+
* county wrote it.
|
|
256
|
+
*
|
|
257
|
+
* A kept row is then dropped when another kept row subsumes it: every non-null
|
|
258
|
+
* cell of the narrow row equals that cell of the wide one. That covers
|
|
259
|
+
* - a row with no served value at all, when the key has another row (a key
|
|
260
|
+
* whose ONLY row is empty keeps it);
|
|
261
|
+
* - one owner once with and once without a mailing line, in either order.
|
|
262
|
+
* A row that carries a value no other row does stays: two named owners sharing
|
|
263
|
+
* a mailing address are two rows, and so is one owner at two mailing addresses.
|
|
264
|
+
* Kept rows are distinct, so two rows never subsume each other and the filter
|
|
265
|
+
* cannot drop every row of a key. The row ceiling counts what is left.
|
|
266
|
+
*
|
|
267
|
+
* Two differences from the UrbanKit Studio engine. It reads cells through the
|
|
268
|
+
* endpoint's roles (owner, site address, mailing) and treats a placeholder owner
|
|
269
|
+
* ("UNKNOWN", "N/A") as no owner, while this compares the raw content columns;
|
|
270
|
+
* every row here has passed the owner echo, so a placeholder owner can only
|
|
271
|
+
* appear when the search is for the placeholder itself. And it tests a cell for
|
|
272
|
+
* blankness before NFKC, so a cell that NFKC turns into nothing visible (a lone
|
|
273
|
+
* spacing accent such as U+00B4 becomes a space and a combining mark) is an empty
|
|
274
|
+
* value there and null here. Keys follow the engine's blank rule exactly.
|
|
275
|
+
*/
|
|
276
|
+
function dedupeByContent(rows, content) {
|
|
277
|
+
const seen = new Set();
|
|
278
|
+
const kept = [];
|
|
279
|
+
for (const row of rows) {
|
|
280
|
+
const cells = content.map((field) => comparedCell(row[field]));
|
|
281
|
+
const signature = JSON.stringify(cells);
|
|
282
|
+
if (seen.has(signature))
|
|
283
|
+
continue;
|
|
284
|
+
seen.add(signature);
|
|
285
|
+
kept.push({ row, cells });
|
|
286
|
+
}
|
|
287
|
+
// ANCHOR owner-join-subsumed
|
|
288
|
+
return kept.filter((k) => !kept.some((o) => o !== k && subsumes(o.cells, k.cells))).map((k) => k.row);
|
|
289
|
+
}
|
|
290
|
+
/**
|
|
291
|
+
* Read the features of an owner-name query against the table.
|
|
292
|
+
*
|
|
293
|
+
* `features` is the response's `features` array, every page read so far.
|
|
294
|
+
* `ownerField` and `ownerQuery` are the column and the name the query was
|
|
295
|
+
* built with. The whole result is refused as `join-integrity` when any row
|
|
296
|
+
* fails the owner echo; otherwise each key's rows are de-duplicated by content
|
|
297
|
+
* and held to the record's row cap.
|
|
298
|
+
*
|
|
299
|
+
* A key's rows here are the ones that matched the name. The parcel may hold
|
|
300
|
+
* other owners, which a name search does not return.
|
|
301
|
+
*/
|
|
302
|
+
export function readOwnerJoinRows(join, ownerField, ownerQuery, features) {
|
|
303
|
+
const fields = ownerJoinOutFields(join, ownerField);
|
|
304
|
+
const rows = features.map((feature) => projectFeature(feature, fields));
|
|
305
|
+
if (!verifyOwnerEcho(rows, ownerField, ownerQuery))
|
|
306
|
+
return { ok: false, reason: "join-integrity" };
|
|
307
|
+
const grouped = new Map();
|
|
308
|
+
let unkeyed = 0;
|
|
309
|
+
for (const row of rows) {
|
|
310
|
+
const key = joinKeyOf(row[join.key]);
|
|
311
|
+
if (key === null) {
|
|
312
|
+
unkeyed++;
|
|
313
|
+
continue;
|
|
314
|
+
}
|
|
315
|
+
const own = grouped.get(key);
|
|
316
|
+
if (own)
|
|
317
|
+
own.push(row);
|
|
318
|
+
else
|
|
319
|
+
grouped.set(key, [row]);
|
|
320
|
+
}
|
|
321
|
+
const content = fields.filter((field) => field !== join.key);
|
|
322
|
+
const cap = ownerJoinRowCap(join);
|
|
323
|
+
const byKey = new Map();
|
|
324
|
+
for (const [key, own] of grouped) {
|
|
325
|
+
const distinct = dedupeByContent(own, content);
|
|
326
|
+
// ANCHOR owner-join-row-cap
|
|
327
|
+
byKey.set(key, distinct.length > cap ? { state: "ambiguous", count: distinct.length } : { state: "joined", rows: distinct });
|
|
328
|
+
}
|
|
329
|
+
return { ok: true, byKey, unkeyed };
|
|
330
|
+
}
|
|
331
|
+
/**
|
|
332
|
+
* The notes build_owner_query prints under a table query: what the rows are,
|
|
333
|
+
* and the reading rules of readOwnerJoinRows in words, since the caller
|
|
334
|
+
* fetches the URL and this server never sees a row.
|
|
335
|
+
*/
|
|
336
|
+
export function ownerJoinNotes(join, ownerField, layerUrl) {
|
|
337
|
+
const cap = ownerJoinRowCap(join);
|
|
338
|
+
return [
|
|
339
|
+
`The rows come from the county's owner table, not the parcel layer: each is one ownership record with no geometry, and its ${join.key} is the parcel's ${join.parcelKey} on the parcel layer ${layerUrl}`,
|
|
340
|
+
`Check every row before using any: each must hold the searched name in ${ownerField}. If one does not, the table did not apply the where clause, so discard the whole response and show none of its owners`,
|
|
341
|
+
`One ${join.key} can hold several rows: de-duplicate them by the values you read, compared without regard to letter case, invisible characters or runs of whitespace (never by a row label, which is not unique), and drop a row whose values another row of the ${join.key} already carries (the same owner once with and once without a mailing line is one record). ` +
|
|
342
|
+
(cap === 1
|
|
343
|
+
? `A ${join.key} left with more than one different row has no single owner: show none of its rows`
|
|
344
|
+
: `A ${join.key} left with more than ${cap} different rows has no owner you can state: show none of its rows`),
|
|
345
|
+
`A row whose ${join.key} is blank, or holds only invisible characters, belongs to no parcel: show none of it`,
|
|
346
|
+
`For more rows add &resultOffset=25 (then 50, and so on) and keep orderByFields=${join.orderField}, which holds the pages in one order`,
|
|
347
|
+
];
|
|
348
|
+
}
|
package/dist/search-policy.d.ts
CHANGED
|
@@ -28,7 +28,13 @@
|
|
|
28
28
|
* out the confidential owners the flag exists to keep out.
|
|
29
29
|
* 5. offered: the first owner-name column that is searchable (the column
|
|
30
30
|
* test is the UKS classifier's; see OWNER_RE below).
|
|
31
|
-
* 6.
|
|
31
|
+
* 6. the owner table: the layer documents no owner column, but the endpoint
|
|
32
|
+
* carries a usable `ownerJoin` (atlas 0.9.0; ./owner-join.ts decides
|
|
33
|
+
* "usable"). The same column test runs on the table's fields: offered
|
|
34
|
+
* with `join` set, so the query goes to the table, or owner_unsearchable
|
|
35
|
+
* when the table marks every owner column unsearchable. A join that may
|
|
36
|
+
* not be used is ignored, and the record is its plain layer.
|
|
37
|
+
* 7. no_owner_column: neither the layer nor a usable table documents one.
|
|
32
38
|
*
|
|
33
39
|
* Separately from the branch, `scopeWhere` is returned whenever the registry
|
|
34
40
|
* carries one. A shared statewide or regional layer holds every county's rows
|
|
@@ -38,17 +44,19 @@
|
|
|
38
44
|
* Likewise `confidential` is returned whenever the endpoint carries the
|
|
39
45
|
* atlas's `confidentialFlag` (0.6.43): the county's own column marking an
|
|
40
46
|
* owner whose record must not be shown (Texas Tax Code §25.025; Harris,
|
|
41
|
-
* Collin and Ector). ownerWhereClause ANDs its exclusion after the owner
|
|
47
|
+
* Collin and Ector, and since atlas 0.8.0 Brown WI). ownerWhereClause ANDs its exclusion after the owner
|
|
42
48
|
* match, and buildArcgisOwnerQuery requests the column. A flag that is
|
|
43
49
|
* present but malformed comes back as `{ kind: "incomplete" }`, never null.
|
|
44
50
|
*/
|
|
45
|
-
import type { ConfidentialFlag, CountyRecord, EndpointRecord } from "@urbankitstudio/atlas";
|
|
51
|
+
import type { ConfidentialFlag, CountyRecord, EndpointRecord, OwnerJoin } from "@urbankitstudio/atlas";
|
|
46
52
|
/**
|
|
47
53
|
* The endpoint fields this policy reads, as @urbankitstudio/atlas declares them
|
|
48
54
|
* (`scopeWhere` and `attributeSearch` since 0.6.11; before that this file
|
|
49
|
-
* carried a local copy of the two; `confidentialFlag` since 0.6.43
|
|
55
|
+
* carried a local copy of the two; `confidentialFlag` since 0.6.43; `ownerJoin`
|
|
56
|
+
* since 0.9.0, with `sharedService` and `supportsPagination`, which decide
|
|
57
|
+
* whether a join may be used).
|
|
50
58
|
*/
|
|
51
|
-
export type EndpointSearchPolicyFields = Pick<EndpointRecord, "searchFields" | "scopeWhere" | "attributeSearch" | "confidentialFlag">;
|
|
59
|
+
export type EndpointSearchPolicyFields = Pick<EndpointRecord, "searchFields" | "scopeWhere" | "attributeSearch" | "confidentialFlag" | "ownerJoin" | "sharedService" | "supportsPagination">;
|
|
52
60
|
type CountyPolicyFields = Pick<CountyRecord, "capabilityOverrides">;
|
|
53
61
|
export type OwnerSearchKind = "offered" | "reviewed_unservable" | "attribute_search_unsupported" | "owner_unsearchable" | "confidential_flag_incomplete" | "no_owner_column";
|
|
54
62
|
export interface OwnerSearchPolicy {
|
|
@@ -65,6 +73,12 @@ export interface OwnerSearchPolicy {
|
|
|
65
73
|
* endpoint carries no flag at all, so a truthy check means "flagged".
|
|
66
74
|
*/
|
|
67
75
|
confidential: ConfidentialPolicy | null;
|
|
76
|
+
/**
|
|
77
|
+
* The county's owner table, when the owner column is the table's and not the
|
|
78
|
+
* layer's: the owner query then goes to `join.url`. Null on a plain layer,
|
|
79
|
+
* and on a record whose join may not be used.
|
|
80
|
+
*/
|
|
81
|
+
join: OwnerJoin | null;
|
|
68
82
|
}
|
|
69
83
|
export interface ConfidentialExclusion {
|
|
70
84
|
kind: "exclude";
|
|
@@ -226,6 +240,13 @@ export declare function ownerCoverageLabel(county: CountyPolicyFields & {
|
|
|
226
240
|
* layer flagged `supportsPagination: false` answers that parameter with HTTP 200
|
|
227
241
|
* and a 400 error body instead of rows. The rule is the package's
|
|
228
242
|
* `offersPagination`, read here, never re-derived.
|
|
243
|
+
*
|
|
244
|
+
* When the owner column is on the county's owner table (`owner.join`), the
|
|
245
|
+
* query goes to the TABLE, never to the layer, which has no such column. It is
|
|
246
|
+
* an attribute query and nothing else: the where clause, the parcel key and
|
|
247
|
+
* the table's content columns, and no geometry parameter, which a table
|
|
248
|
+
* ignores. `orderByFields` rides on the first page too, so a caller who adds
|
|
249
|
+
* `resultOffset` reads the pages in one order.
|
|
229
250
|
*/
|
|
230
251
|
export declare function buildArcgisOwnerQuery(endpoint: Pick<EndpointRecord, "url" | "searchFields" | "supportsPagination">, owner: OwnerSearchPolicy, ownerQuery: string): string;
|
|
231
252
|
/**
|
|
@@ -254,6 +275,11 @@ export declare function parcelEndpointSamples(endpoint: Pick<EndpointRecord, "ur
|
|
|
254
275
|
atlas: string | null;
|
|
255
276
|
owner: string | null;
|
|
256
277
|
};
|
|
278
|
+
/**
|
|
279
|
+
* The build_owner_query notes a query against an owner table adds: what its
|
|
280
|
+
* rows are and how to read them (./owner-join.ts). None on a plain layer.
|
|
281
|
+
*/
|
|
282
|
+
export declare function ownerTableNotes(owner: OwnerSearchPolicy, endpoint: Pick<EndpointRecord, "url">): string[];
|
|
257
283
|
/** The build_owner_query note on how many rows the query returns. */
|
|
258
284
|
export declare function ownerQueryRowsNote(endpoint: Pick<EndpointRecord, "supportsPagination" | "maxRecordCount">): string;
|
|
259
285
|
export {};
|
package/dist/search-policy.js
CHANGED
|
@@ -28,7 +28,13 @@
|
|
|
28
28
|
* out the confidential owners the flag exists to keep out.
|
|
29
29
|
* 5. offered: the first owner-name column that is searchable (the column
|
|
30
30
|
* test is the UKS classifier's; see OWNER_RE below).
|
|
31
|
-
* 6.
|
|
31
|
+
* 6. the owner table: the layer documents no owner column, but the endpoint
|
|
32
|
+
* carries a usable `ownerJoin` (atlas 0.9.0; ./owner-join.ts decides
|
|
33
|
+
* "usable"). The same column test runs on the table's fields: offered
|
|
34
|
+
* with `join` set, so the query goes to the table, or owner_unsearchable
|
|
35
|
+
* when the table marks every owner column unsearchable. A join that may
|
|
36
|
+
* not be used is ignored, and the record is its plain layer.
|
|
37
|
+
* 7. no_owner_column: neither the layer nor a usable table documents one.
|
|
32
38
|
*
|
|
33
39
|
* Separately from the branch, `scopeWhere` is returned whenever the registry
|
|
34
40
|
* carries one. A shared statewide or regional layer holds every county's rows
|
|
@@ -38,11 +44,12 @@
|
|
|
38
44
|
* Likewise `confidential` is returned whenever the endpoint carries the
|
|
39
45
|
* atlas's `confidentialFlag` (0.6.43): the county's own column marking an
|
|
40
46
|
* owner whose record must not be shown (Texas Tax Code §25.025; Harris,
|
|
41
|
-
* Collin and Ector). ownerWhereClause ANDs its exclusion after the owner
|
|
47
|
+
* Collin and Ector, and since atlas 0.8.0 Brown WI). ownerWhereClause ANDs its exclusion after the owner
|
|
42
48
|
* match, and buildArcgisOwnerQuery requests the column. A flag that is
|
|
43
49
|
* present but malformed comes back as `{ kind: "incomplete" }`, never null.
|
|
44
50
|
*/
|
|
45
|
-
import { isReviewedUnservable, offersPagination, reviewedCapability } from "@urbankitstudio/atlas";
|
|
51
|
+
import { isReviewedUnservable, offersPagination, queryFieldName, reviewedCapability } from "@urbankitstudio/atlas";
|
|
52
|
+
import { ownerJoinNotes, ownerJoinOutFields, ownerJoinTableUrl, usableOwnerJoin } from "./owner-join.js";
|
|
46
53
|
// A bare column identifier: the field is written into the SQL unquoted, so
|
|
47
54
|
// nothing else may pass. A dotted (joined-layer) name is refused too, which
|
|
48
55
|
// fails closed.
|
|
@@ -251,12 +258,13 @@ export const OWNER_UNSEARCHABLE_REASON = "the owner column exists but the county
|
|
|
251
258
|
export function ownerSearchPolicy(county, endpoint) {
|
|
252
259
|
const scopeWhere = endpoint.scopeWhere?.trim() || null;
|
|
253
260
|
const confidential = confidentialExclusion(endpoint.confidentialFlag);
|
|
254
|
-
const refuse = (kind, reason) => ({
|
|
261
|
+
const refuse = (kind, reason, join = null) => ({
|
|
255
262
|
kind,
|
|
256
263
|
field: null,
|
|
257
264
|
reason,
|
|
258
265
|
scopeWhere,
|
|
259
266
|
confidential,
|
|
267
|
+
join,
|
|
260
268
|
});
|
|
261
269
|
if (isReviewedUnservable(county, "owner_name")) {
|
|
262
270
|
return refuse("reviewed_unservable", reviewedCapability(county, "owner_name")?.basis?.note ??
|
|
@@ -270,10 +278,23 @@ export function ownerSearchPolicy(county, endpoint) {
|
|
|
270
278
|
if (usable && confidential?.kind === "incomplete") {
|
|
271
279
|
return refuse("confidential_flag_incomplete", incompleteFlagReason(confidential));
|
|
272
280
|
}
|
|
281
|
+
// The column to SEND: the atlas's queryFieldName, which is `name` on every
|
|
282
|
+
// record today and the qualified `wireName` once a record carries one.
|
|
273
283
|
if (usable)
|
|
274
|
-
return { kind: "offered", field: usable
|
|
284
|
+
return { kind: "offered", field: queryFieldName(usable), reason: null, scopeWhere, confidential, join: null };
|
|
275
285
|
if (named.length > 0)
|
|
276
286
|
return refuse("owner_unsearchable", OWNER_UNSEARCHABLE_REASON);
|
|
287
|
+
// The layer documents no owner column. Its owners may be one table away: a
|
|
288
|
+
// usable join carries no scope and no flag, so both are null from here on.
|
|
289
|
+
const join = usableOwnerJoin(county, endpoint);
|
|
290
|
+
if (join) {
|
|
291
|
+
const onTable = join.fields.filter(isOwnerNameColumn);
|
|
292
|
+
const searchable = onTable.find((sf) => sf.searchable !== false);
|
|
293
|
+
if (searchable)
|
|
294
|
+
return { kind: "offered", field: searchable.name, reason: null, scopeWhere, confidential, join };
|
|
295
|
+
if (onTable.length > 0)
|
|
296
|
+
return refuse("owner_unsearchable", OWNER_UNSEARCHABLE_REASON, join);
|
|
297
|
+
}
|
|
277
298
|
return refuse("no_owner_column", null);
|
|
278
299
|
}
|
|
279
300
|
/**
|
|
@@ -353,12 +374,30 @@ export function ownerCoverageLabel(county) {
|
|
|
353
374
|
* layer flagged `supportsPagination: false` answers that parameter with HTTP 200
|
|
354
375
|
* and a 400 error body instead of rows. The rule is the package's
|
|
355
376
|
* `offersPagination`, read here, never re-derived.
|
|
377
|
+
*
|
|
378
|
+
* When the owner column is on the county's owner table (`owner.join`), the
|
|
379
|
+
* query goes to the TABLE, never to the layer, which has no such column. It is
|
|
380
|
+
* an attribute query and nothing else: the where clause, the parcel key and
|
|
381
|
+
* the table's content columns, and no geometry parameter, which a table
|
|
382
|
+
* ignores. `orderByFields` rides on the first page too, so a caller who adds
|
|
383
|
+
* `resultOffset` reads the pages in one order.
|
|
356
384
|
*/
|
|
357
385
|
export function buildArcgisOwnerQuery(endpoint, owner, ownerQuery) {
|
|
358
386
|
if (!owner.field)
|
|
359
387
|
return "";
|
|
360
388
|
const where = encodeURIComponent(ownerWhereClause(owner.field, owner.scopeWhere, ownerQuery, owner.confidential));
|
|
361
|
-
|
|
389
|
+
if (owner.join) {
|
|
390
|
+
// ANCHOR owner-join-table-url
|
|
391
|
+
const table = ownerJoinTableUrl(owner.join);
|
|
392
|
+
return (`${table}/query` +
|
|
393
|
+
`?where=${where}` +
|
|
394
|
+
`&outFields=${ownerJoinOutFields(owner.join, owner.field).join(",")}` +
|
|
395
|
+
`&orderByFields=${encodeURIComponent(owner.join.orderField)}` +
|
|
396
|
+
`&returnGeometry=false` +
|
|
397
|
+
`&f=json` +
|
|
398
|
+
(offersPagination(endpoint) ? `&resultRecordCount=25` : ""));
|
|
399
|
+
}
|
|
400
|
+
const fields = endpoint.searchFields.filter((sf) => sf.searchable).map(queryFieldName);
|
|
362
401
|
// The flag column comes back with the owner, as the atlas asks, so whoever
|
|
363
402
|
// reads the rows can drop a flagged one as well.
|
|
364
403
|
if (owner.confidential?.kind === "exclude" && !fields.includes(owner.confidential.field)) {
|
|
@@ -378,8 +417,16 @@ export function buildArcgisOwnerQuery(endpoint, owner, ownerQuery) {
|
|
|
378
417
|
* incomplete flag, gives way to "do not read owner fields here".
|
|
379
418
|
*/
|
|
380
419
|
export function ownerLine(owner) {
|
|
420
|
+
// On an owner table the column is not on the layer whose URL is printed
|
|
421
|
+
// above this line, so the line says where it is and how the two tie.
|
|
422
|
+
if (owner.field && owner.join) {
|
|
423
|
+
return `Owner field: ${owner.field} (in the county's owner table ${ownerJoinTableUrl(owner.join)}, not on this layer; the table's ${owner.join.key} is this layer's ${owner.join.parcelKey})`;
|
|
424
|
+
}
|
|
381
425
|
if (owner.field)
|
|
382
426
|
return `Owner field: ${owner.field}`;
|
|
427
|
+
if (owner.kind === "owner_unsearchable" && owner.join) {
|
|
428
|
+
return "Owner field: not searchable by name (column exists in the county's owner table, not on this layer; a parcel-id or location query here returns no owner)";
|
|
429
|
+
}
|
|
383
430
|
const c = owner.confidential;
|
|
384
431
|
if (owner.kind === "attribute_search_unsupported") {
|
|
385
432
|
const base = `Attribute search: not offered (location queries only) - ${owner.reason}`;
|
|
@@ -426,6 +473,13 @@ export function ownerRefusal(owner, place) {
|
|
|
426
473
|
}
|
|
427
474
|
case "owner_unsearchable": {
|
|
428
475
|
// The owner IS published; only a name search on it is unsupported.
|
|
476
|
+
if (owner.join) {
|
|
477
|
+
// The column is on the owner table, so the parcel-id and location
|
|
478
|
+
// reads the plain advice names would return no owner there. No other
|
|
479
|
+
// read is advised.
|
|
480
|
+
refusal = `OWNER COLUMN NOT SEARCHABLE BY NAME for ${place}: ${owner.reason}\nThe owner column is in the county's owner table (${ownerJoinTableUrl(owner.join)}), not on the parcel layer, so a parcel-id or location query on the layer returns no owner. No owner query is offered here.`;
|
|
481
|
+
break;
|
|
482
|
+
}
|
|
429
483
|
const advice = !c
|
|
430
484
|
? "Use a parcel-id or location query instead; either returns the owner of the matching parcel."
|
|
431
485
|
: c.kind === "incomplete"
|
|
@@ -459,6 +513,13 @@ export function parcelEndpointSamples(endpoint, owner) {
|
|
|
459
513
|
owner: owner.field ? buildArcgisOwnerQuery(endpoint, owner, "SMITH") : null,
|
|
460
514
|
};
|
|
461
515
|
}
|
|
516
|
+
/**
|
|
517
|
+
* The build_owner_query notes a query against an owner table adds: what its
|
|
518
|
+
* rows are and how to read them (./owner-join.ts). None on a plain layer.
|
|
519
|
+
*/
|
|
520
|
+
export function ownerTableNotes(owner, endpoint) {
|
|
521
|
+
return owner.field && owner.join ? ownerJoinNotes(owner.join, owner.field, endpoint.url) : [];
|
|
522
|
+
}
|
|
462
523
|
/** The build_owner_query note on how many rows the query returns. */
|
|
463
524
|
export function ownerQueryRowsNote(endpoint) {
|
|
464
525
|
if (offersPagination(endpoint))
|
package/dist/server.js
CHANGED
|
@@ -19,8 +19,8 @@ import { z } from "zod/v3";
|
|
|
19
19
|
import { readFileSync } from "node:fs";
|
|
20
20
|
import { fileURLToPath } from "node:url";
|
|
21
21
|
import { resolve, dirname } from "node:path";
|
|
22
|
-
import { atlas, atlasIndex, slugify, countySlugFromName, countyHasEndpoint, coverageAnswer, coverageAnswerText, } from "@urbankitstudio/atlas";
|
|
23
|
-
import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, escapeSqlLiteral, confidentialLine, parcelEndpointSamples, ownerRefusal, ownerLine, } from "./search-policy.js";
|
|
22
|
+
import { atlas, atlasIndex, slugify, countySlugFromName, countyHasEndpoint, coverageAnswer, coverageAnswerText, queryFieldName, } from "@urbankitstudio/atlas";
|
|
23
|
+
import { ownerSearchPolicy, ownerWhereClause, ownerCoverageLabel, buildArcgisOwnerQuery, ownerQueryRowsNote, ownerTableNotes, escapeSqlLiteral, confidentialLine, parcelEndpointSamples, ownerRefusal, ownerLine, } from "./search-policy.js";
|
|
24
24
|
import { freeText } from "./tool-input.js";
|
|
25
25
|
import { getCityDatasets, CITY_REF_MAX_LEN, CITY_STATE_MAX_LEN, CITY_STREET_MAX_LEN, } from "./city-datasets.js";
|
|
26
26
|
// Re-exported so the package's public surface is unchanged by the move.
|
|
@@ -92,7 +92,7 @@ function formatCountySummary(c) {
|
|
|
92
92
|
const owner = ownerSearchPolicy(c, ep);
|
|
93
93
|
const searchable = ep.searchFields
|
|
94
94
|
.filter((sf) => sf.searchable)
|
|
95
|
-
.map((sf) => `${sf
|
|
95
|
+
.map((sf) => `${queryFieldName(sf)} (${sf.label})`)
|
|
96
96
|
.join(", ");
|
|
97
97
|
const scope = scopeLine(owner);
|
|
98
98
|
const confidential = confidentialLine(owner);
|
|
@@ -354,7 +354,7 @@ server.registerTool("get_parcel_endpoint", {
|
|
|
354
354
|
lines.push(" Searchable fields:");
|
|
355
355
|
ep.searchFields
|
|
356
356
|
.filter((sf) => sf.searchable)
|
|
357
|
-
.forEach((sf) => lines.push(` ${sf.
|
|
357
|
+
.forEach((sf) => lines.push(` ${queryFieldName(sf).padEnd(20)} – ${sf.label}`));
|
|
358
358
|
lines.push("");
|
|
359
359
|
lines.push(` ${ownerLine(owner)}`);
|
|
360
360
|
// parcelEndpointSamples withholds the atlas's sample on any flagged
|
|
@@ -370,7 +370,9 @@ server.registerTool("get_parcel_endpoint", {
|
|
|
370
370
|
lines.push(` ${samples.owner}`);
|
|
371
371
|
}
|
|
372
372
|
lines.push("");
|
|
373
|
-
|
|
373
|
+
// The link opens the LAYER. An owner column that sits on the county's
|
|
374
|
+
// owner table is no column of it, so it is not passed as the hint.
|
|
375
|
+
lines.push(` UrbanKit deep-link: https://urbankitstudio.com/tools/parcel-lookup?endpoint=${encodeURIComponent(ep.url)}${ownerField && !owner.join ? `&fieldHint=${ownerField}` : ""}`);
|
|
374
376
|
if (i < countyRecord.endpoints.length - 1)
|
|
375
377
|
lines.push("\n" + "-".repeat(40));
|
|
376
378
|
});
|
|
@@ -448,7 +450,8 @@ server.registerTool("build_owner_query", {
|
|
|
448
450
|
const confidential = confidentialLine(owner);
|
|
449
451
|
results.push([
|
|
450
452
|
`County: ${countyRecord.county}, ${countyRecord.stateName}`,
|
|
451
|
-
|
|
453
|
+
// "Owner field: <column>", and on an owner table where that column is.
|
|
454
|
+
ownerLine(owner),
|
|
452
455
|
...(scope ? [scope] : []),
|
|
453
456
|
...(confidential ? [confidential] : []),
|
|
454
457
|
`WHERE clause: ${where}`,
|
|
@@ -458,6 +461,9 @@ server.registerTool("build_owner_query", {
|
|
|
458
461
|
``,
|
|
459
462
|
`Notes:`,
|
|
460
463
|
` - ${ownerQueryRowsNote(ep)}`,
|
|
464
|
+
// On an owner table: what the rows are and how to read them. The
|
|
465
|
+
// caller fetches the URL, so the reading rules travel with it.
|
|
466
|
+
...ownerTableNotes(owner, ep).map((note) => ` - ${note}`),
|
|
461
467
|
...(owner.confidential?.kind === "exclude"
|
|
462
468
|
? [
|
|
463
469
|
` - 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`,
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@urbankitstudio/mcp-atlas",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
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 539 counties across 51 US states (50 states plus DC), 522 endpoints total, for owner, APN and address lookup via the Model Context Protocol (MCP), plus verified city code-violation, building-permit and zoning-case datasets.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"mcp",
|
|
8
8
|
"mcp-server",
|
|
@@ -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 test/confirm-registry.test.mjs test/coverage-claims.test.mjs test/tool-input.test.mjs test/log-hygiene.test.mjs",
|
|
49
|
+
"test:policy": "node --test test/search-policy.test.mjs test/owner-join.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.9.1"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@types/node": "^26.0.0",
|