@urbankitstudio/mcp-atlas 0.1.6 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Leo Yong
+Copyright (c) 2026 UrbanKit Studio
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 # @urbankitstudio/mcp-atlas
 
-Query 155 verified US county parcel ArcGIS REST endpoints for owner, APN, and address lookup via the Model Context Protocol (MCP).
+Query the verified parcel ArcGIS REST endpoints of 171 counties across all 50 US states (174 layers) for owner, APN and address lookup via the Model Context Protocol (MCP).
 
 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.
 
-**Coverage:** 155 counties across all 50 US states.
+**Coverage:** 171 counties across all 50 US states, 174 verified endpoints (atlas 0.6.2).
 
 ---
 
@@ -153,4 +153,4 @@ Atlas data is embedded in the package (no network calls at startup). The underly
 
 ## License
 
-MIT — © Leo Yong / UrbanKit Studio
+MIT — © 2026 UrbanKit Studio

package/dist/server.js

@@ -14,16 +14,43 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod/v3";
-import { atlas, atlasIndex, slugify, countySlugFromName, } from "@urbankitstudio/atlas";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve, dirname } from "node:path";
+import { atlas, atlasIndex, slugify, countySlugFromName, isReviewedUnservable, reviewedCapability, } from "@urbankitstudio/atlas";
+const PKG_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")).version;
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function ownerFieldFrom(endpoint) {
+/**
+ * The owner column a caller can actually USE, or null with a reason.
+ *
+ * Matching the column name is not enough, and that gap cost a real trial user:
+ * they paid for owner data, ran Los Angeles County, got nothing back, and the
+ * atlas had said the field was there the whole time. Fourteen counties in the
+ * registry document an owner column that is present and empty on every row -
+ * New Jersey's statewide layer publishes OWNER_NAME blank across 3,481,240
+ * rows, New York's across 3,827,530 - and a reviewed capability record says so.
+ * Consult it BEFORE promising the field.
+ */
+function ownerFieldFor(county, endpoint) {
+    if (isReviewedUnservable(county, "owner_name")) {
+        const reviewed = reviewedCapability(county, "owner_name");
+        return {
+            field: null,
+            unavailableReason: reviewed?.basis?.note ??
+                "this county publishes no usable owner name on its public endpoint",
+        };
+    }
     const f = endpoint.searchFields.find((sf) => /owner|taxpayer|taxname/i.test(sf.name));
-    return f?.name ?? null;
+    return { field: f?.name ?? null, unavailableReason: null };
+}
+/** Back-compat shim for call sites that only need the column. */
+function ownerFieldFrom(county, endpoint) {
+    return ownerFieldFor(county, endpoint).field;
 }
-function buildArcgisOwnerQuery(endpoint, ownerQuery) {
-    const field = ownerFieldFrom(endpoint);
+function buildArcgisOwnerQuery(county, endpoint, ownerQuery) {
+    const field = ownerFieldFrom(county, endpoint);
     if (!field)
         return "";
     const where = `UPPER(${field}) LIKE UPPER('%25${encodeURIComponent(ownerQuery)}%25')`;
@@ -43,7 +70,7 @@ function formatCountySummary(c) {
         ? "no REST endpoint mapped"
         : c.endpoints
             .map((ep) => {
-            const ownerField = ownerFieldFrom(ep);
+            const owner = ownerFieldFor(c, ep);
             const searchable = ep.searchFields
                 .filter((sf) => sf.searchable)
                 .map((sf) => `${sf.name} (${sf.label})`)
@@ -53,7 +80,10 @@ function formatCountySummary(c) {
                 `  Service: ${ep.serviceType}/layer ${ep.layerIndex}`,
                 `  Status: ${ep.status} (verified ${ep.lastVerified})`,
                 `  Searchable fields: ${searchable || "none"}`,
-                `  Owner field: ${ownerField ?? "none (PIN-only county)"}`,
+                `  Owner field: ${owner.field ??
+                    (owner.unavailableReason
+                        ? `NOT AVAILABLE - ${owner.unavailableReason}`
+                        : "none (this layer publishes no owner column)")}`,
                 `  License: ${ep.license}`,
             ].join("\n");
         })
@@ -71,7 +101,11 @@ function formatCountySummary(c) {
 // ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
-const server = new McpServer({ name: "mcp-atlas", version: "0.1.0" }, {
+const server = new McpServer(
+// Read from package.json rather than restated here. This line said 0.1.0
+// while the package was 0.1.6 - six releases of drift, and every MCP client
+// that asked the server its version got the wrong answer.
+{ name: "mcp-atlas", version: PKG_VERSION }, {
     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.",
 });
 // ---------------------------------------------------------------------------
@@ -105,9 +139,17 @@ server.registerTool("list_counties", {
             continue;
         const covered = stateFile.counties.filter((c) => c.endpoints.length > 0);
         for (const c of covered) {
-            const ownerCoverage = c.endpoints.some((ep) => ownerFieldFrom(ep))
+            // "APN only" is not the same claim as "owner+APN minus the owner".
+            // A caller scanning this column is deciding whether to spend a request,
+            // so a county whose owner column exists and is empty must not read as
+            // though owners are simply absent from the schema.
+            const anyOwner = c.endpoints.some((ep) => ownerFieldFor(c, ep).field);
+            const ownerWithheld = c.endpoints.some((ep) => ownerFieldFor(c, ep).unavailableReason);
+            const ownerCoverage = anyOwner
                 ? "owner+APN"
-                : "APN only";
+                : ownerWithheld
+                    ? "APN only (county publishes no owner name)"
+                    : "APN only";
             rows.push(`${c.state} | ${c.county.padEnd(20)} | ${c.countySlug.padEnd(24)} | ${ownerCoverage}`);
         }
     }
@@ -272,9 +314,10 @@ server.registerTool("get_parcel_endpoint", {
         "",
     ];
     countyRecord.endpoints.forEach((ep, i) => {
-        const ownerField = ownerFieldFrom(ep);
+        const owner = ownerFieldFor(countyRecord, ep);
+        const ownerField = owner.field;
         const sampleOwnerUrl = ownerField
-            ? buildArcgisOwnerQuery(ep, "SMITH")
+            ? buildArcgisOwnerQuery(countyRecord, ep, "SMITH")
             : null;
         lines.push(`Endpoint ${i + 1}:`);
         lines.push(`  URL:         ${ep.url}`);
@@ -290,7 +333,10 @@ server.registerTool("get_parcel_endpoint", {
             .filter((sf) => sf.searchable)
             .forEach((sf) => lines.push(`    ${sf.name.padEnd(20)} – ${sf.label}`));
         lines.push("");
-        lines.push(`  Owner field: ${ownerField ?? "NONE — PIN-only county"}`);
+        lines.push(`  Owner field: ${ownerField ??
+            (owner.unavailableReason
+                ? `NOT AVAILABLE - ${owner.unavailableReason}`
+                : "NONE - this layer publishes no owner column")}`);
         if (ep.sampleQuery) {
             lines.push("");
             lines.push("  Sample query (from atlas):");
@@ -359,12 +405,18 @@ server.registerTool("build_owner_query", {
     }
     const results = [];
     for (const ep of countyRecord.endpoints) {
-        const ownerField = ownerFieldFrom(ep);
+        const owner = ownerFieldFor(countyRecord, ep);
+        const ownerField = owner.field;
         if (!ownerField) {
-            results.push(`Endpoint: ${ep.url}\nNote: No owner/taxpayer field available in this county — PIN-only lookup. Try searching by parcel number instead.`);
+            // Refusing with the reason beats handing back a query that returns zero
+            // rows forever. The caller can then choose a different county or a
+            // different field instead of concluding the owner simply is not there.
+            results.push(owner.unavailableReason
+                ? `Endpoint: ${ep.url}\nOWNER NAME NOT AVAILABLE for ${countyRecord.county}, ${countyRecord.stateName}: ${owner.unavailableReason}\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.`
+                : `Endpoint: ${ep.url}\nNote: this layer publishes no owner or taxpayer column - PIN-only lookup. Try searching by parcel number instead.`);
             continue;
         }
-        const queryUrl = buildArcgisOwnerQuery(ep, owner_name);
+        const queryUrl = buildArcgisOwnerQuery(countyRecord, ep, owner_name);
         const where = `UPPER(${ownerField}) LIKE UPPER('%${owner_name}%')`;
         results.push([
             `County:      ${countyRecord.county}, ${countyRecord.stateName}`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@urbankitstudio/mcp-atlas",
-  "version": "0.1.6",
-  "description": "Query 155 verified US county parcel ArcGIS REST endpoints for owner, APN, and address lookup via the Model Context Protocol (MCP).",
+  "version": "0.2.1",
+  "description": "Query the verified parcel ArcGIS REST endpoints of 171 counties across all 50 US states (174 layers) for owner, APN and address lookup via the Model Context Protocol (MCP).",
   "keywords": [
     "mcp",
     "mcp-server",
@@ -24,7 +24,7 @@
   "bugs": {
     "url": "https://github.com/LEOyrh/urbankitstudio/issues"
   },
-  "author": "Leo Yong <leoyrhbiz@gmail.com>",
+  "author": "UrbanKit Studio <urbankitstudio@gmail.com>",
   "license": "MIT",
   "type": "module",
   "main": "./dist/server.js",
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@urbankitstudio/atlas": "^0.5.1"
+    "@urbankitstudio/atlas": "^0.6.2"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",