@urbankitstudio/mcp-atlas 0.2.1 → 0.2.2

package/README.md

@@ -1,5 +1,8 @@
 # @urbankitstudio/mcp-atlas
 
+[![mcp-atlas MCP server](https://glama.ai/mcp/servers/LEOyrh/mcp-atlas/badges/card.svg)](https://glama.ai/mcp/servers/LEOyrh/mcp-atlas)
+[![Socket Badge](https://badge.socket.dev/npm/package/@urbankitstudio/mcp-atlas)](https://socket.dev/npm/package/@urbankitstudio/mcp-atlas)
+
 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.
@@ -52,9 +55,29 @@ Then use `mcp-atlas` as the command instead of `npx -y @urbankitstudio/mcp-atlas
 
 ## Tools
 
+The four tools are one pipeline, and what separates them is how precisely you
+can already name the county:
+
+| You have | Use | You get |
+|---|---|---|
+| A state, or nothing | `list_counties` | Which counties are covered, and whether owner search works there. No URLs. |
+| A vague, misspelled or FIPS reference | `find_county` | Every county that reference matches, named, each with its record |
+| An exact state and county | `get_parcel_endpoint` | That one county's endpoint URL, layer, fields and sample query |
+| A county and an owner's name | `build_owner_query` | A runnable URL that searches for that name |
+
+`find_county` and `get_parcel_endpoint` return the same per-county record. They
+differ in how you address the county: `find_county` accepts an uncertain
+reference and may come back with several candidates, `get_parcel_endpoint`
+takes an exact pair and answers about one. If you already know the county, skip
+`find_county`.
+
+This server never executes a query and returns no parcel records. It tells you
+the URL to fetch; fetching it is yours to do.
+
 ### `list_counties`
 
-Lists all counties with a verified parcel REST endpoint.
+Browse coverage. Answers "is this county covered?" and "what can I search
+there?" — one line per county, with no endpoint URLs or field names.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -76,7 +99,11 @@ IL | DuPage               | dupage-county            | owner+APN
 
 ### `find_county`
 
-Fuzzy-matches a county by name or 5-digit FIPS code. Returns endpoint URLs, searchable field names, owner field, sample query, and license info.
+Resolves a reference you cannot state exactly. Fuzzy-matches a partial or
+misspelled name, a "County State" phrase, 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. Each match carries that county's record:
+endpoint URLs, searchable field names, owner field, sample query, license.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -88,7 +115,10 @@ Fuzzy-matches a county by name or 5-digit FIPS code. Returns endpoint URLs, sear
 
 ### `get_parcel_endpoint`
 
-Returns the full ArcGIS REST URL, layer index, searchable fields, owner field, and a ready sample `?where=…&f=json` query for a specific county.
+The default lookup once the county is known. Returns the full ArcGIS REST URL,
+layer index, searchable fields, owner field, a generic sample `?where=…&f=json`
+query and the UrbanKit deep-link for one county. For a named owner, use
+`build_owner_query` rather than editing the sample query by hand.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -101,7 +131,11 @@ Returns the full ArcGIS REST URL, layer index, searchable fields, owner field, a
 
 ### `build_owner_query`
 
-Constructs the exact ArcGIS REST query URL using the county's verified owner/taxpayer field. Uses `UPPER(field) LIKE UPPER('%NAME%')` — case-insensitive partial match.
+The only tool that searches for a named owner. Fills a person or company name
+into the 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. A county that publishes no owner name is
+refused here, with the reason, rather than handed a query that finds nothing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -151,6 +185,29 @@ Atlas data is embedded in the package (no network calls at startup). The underly
 
 ---
 
+## What Socket flags, and how much of it is ours
+
+[Socket](https://socket.dev/npm/package/@urbankitstudio/mcp-atlas)'s supply-chain scanner
+rates this package in the mid-70s. Clicking through shows a long alert list. Each alert,
+checked rather than waved away:
+
+| Alert | Whose | What it is |
+|---|---|---|
+| `usesEval` | Not ours | No `eval` or `new Function` anywhere in `src/`. It comes from a dependency. |
+| `unmaintained` (21) | Not ours | Transitive dependencies last published 2017–2021. |
+| `mixedLicense` | Not ours | A dependency published as `BSD-3-Clause AND ISC`. |
+| `noTests` | Ours, by design | `files` ships `dist` only. The suite lives in `test/` and runs in CI. Shipping tests inside the tarball would be the defect. |
+| `networkAccess`, `filesystemAccess`, `envVars`, `shellAccess` | Ours | An MCP server talks to a client over stdio and reads its own config. A server without these could not do the job. |
+| `unpopularPackage`, `noV1` | Ours | Download count and a `0.x` version. Both resolve with time, neither is a code issue. |
+
+Vulnerability and license both come back at **100**, quality at **99**. The number the
+badge shows is the *supply-chain* sub-score, and its single largest deduction is download
+count, a popularity measure wearing a security badge's clothes. Judge the list above, not
+the digit.
+
+The four access alerts are what let the server read its own config and talk to a client
+over stdio, nothing more. It still never executes a query or returns a parcel record.
+
 ## License
 
 MIT — © 2026 UrbanKit Studio

package/dist/server.d.ts

@@ -11,4 +11,15 @@
  *   get_parcel_endpoint – return the full REST service URL + ready sample query
  *   build_owner_query   – construct exact ArcGIS REST query for an owner name
  */
-export {};
+/**
+ * An ArcGIS `where` is SQL, and a single quote closes the string literal.
+ * encodeURIComponent does not help: `'` and `)` are both in its unreserved set, so
+ * `A') OR 1=1 --` passes through encoding intact and lands OUTSIDE the quotes as a
+ * live predicate against a county's server. Doubling the quote is the SQL-standard
+ * escape and keeps the whole input inside the literal where it belongs.
+ *
+ * Every caller that puts user text in a `where` goes through this, including the
+ * clause rendered for a human to copy: escaping only the URL would leave the same
+ * payload one paste away from running.
+ */
+export declare function escapeSqlLiteral(value: string): string;

package/dist/server.js

@@ -49,11 +49,25 @@ function ownerFieldFor(county, endpoint) {
 function ownerFieldFrom(county, endpoint) {
     return ownerFieldFor(county, endpoint).field;
 }
+/**
+ * An ArcGIS `where` is SQL, and a single quote closes the string literal.
+ * encodeURIComponent does not help: `'` and `)` are both in its unreserved set, so
+ * `A') OR 1=1 --` passes through encoding intact and lands OUTSIDE the quotes as a
+ * live predicate against a county's server. Doubling the quote is the SQL-standard
+ * escape and keeps the whole input inside the literal where it belongs.
+ *
+ * Every caller that puts user text in a `where` goes through this, including the
+ * clause rendered for a human to copy: escaping only the URL would leave the same
+ * payload one paste away from running.
+ */
+export function escapeSqlLiteral(value) {
+    return value.replace(/'/g, "''");
+}
 function buildArcgisOwnerQuery(county, endpoint, ownerQuery) {
     const field = ownerFieldFrom(county, endpoint);
     if (!field)
         return "";
-    const where = `UPPER(${field}) LIKE UPPER('%25${encodeURIComponent(ownerQuery)}%25')`;
+    const where = `UPPER(${field}) LIKE UPPER('%25${encodeURIComponent(escapeSqlLiteral(ownerQuery))}%25')`;
     const liveFields = endpoint.searchFields
         .filter((sf) => sf.searchable)
         .map((sf) => sf.name)
@@ -113,7 +127,7 @@ const server = new McpServer(
 // ---------------------------------------------------------------------------
 server.registerTool("list_counties", {
     title: "List covered counties",
-    description: `Returns all counties in the UrbanKit Atlas that have a verified ArcGIS REST parcel endpoint. Pass a state abbreviation (e.g. 'IL') or state name (e.g. 'Illinois') to filter by state. Omit state to list all ~${atlas.totals.counties} counties.`,
+    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.`,
     inputSchema: {
         state: z
             .string()
@@ -181,8 +195,8 @@ server.registerTool("list_counties", {
 // Tool: find_county
 // ---------------------------------------------------------------------------
 server.registerTool("find_county", {
-    title: "Find a county by name or FIPS",
-    description: "Fuzzy-matches a county by name (e.g. 'Kane', 'Cook County', 'Cook County IL') or by 5-digit FIPS code. Returns endpoint URLs, searchable field names, owner field, sample query URL, and license info.",
+    title: "Resolve an uncertain county reference",
+    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.",
     inputSchema: {
         query: z
             .string()
@@ -257,8 +271,8 @@ server.registerTool("find_county", {
 // Tool: get_parcel_endpoint
 // ---------------------------------------------------------------------------
 server.registerTool("get_parcel_endpoint", {
-    title: "Get parcel ArcGIS REST endpoint",
-    description: "Returns the full ArcGIS REST service URL, layer index, searchable field names, owner field, a ready sample ?where=…&f=json query, and the UrbanKit deep-link for a specific county.",
+    title: "Get one county's parcel endpoint record",
+    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, 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.",
     inputSchema: {
         state: z
             .string()
@@ -360,8 +374,8 @@ server.registerTool("get_parcel_endpoint", {
 // Tool: build_owner_query
 // ---------------------------------------------------------------------------
 server.registerTool("build_owner_query", {
-    title: "Build ArcGIS owner name query URL",
-    description: "Constructs the exact ArcGIS REST query URL using that county's verified owner/taxpayer field. Returns a URL you can open in a browser or fetch directly. The query uses UPPER(field) LIKE UPPER('%NAME%') — case-insensitive partial match.",
+    title: "Build an owner-name search URL for one county",
+    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. 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. Counties that publish no owner name are refused here with that reason.",
     inputSchema: {
         state: z
             .string()
@@ -417,7 +431,7 @@ server.registerTool("build_owner_query", {
             continue;
         }
         const queryUrl = buildArcgisOwnerQuery(countyRecord, ep, owner_name);
-        const where = `UPPER(${ownerField}) LIKE UPPER('%${owner_name}%')`;
+        const where = `UPPER(${ownerField}) LIKE UPPER('%${escapeSqlLiteral(owner_name)}%')`;
         results.push([
             `County:      ${countyRecord.county}, ${countyRecord.stateName}`,
             `Owner field: ${ownerField}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbankitstudio/mcp-atlas",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",