nyrezone-mcp 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.2.0 - 2026-10-29 (unpublished)
+
+- Remove the prior FAR-times-lot-area-minus-gross-building-area calculation for
+  every parcel. Recorded MapPLUTO FAR, area and district facts remain available;
+  they do not establish parcel capacity, unused development rights or compliance.
+- Retain deprecated `unused_floor_area.estimate_sqft`, `allowed_floor_area_sqft`,
+  `governing_far` and `overbuilt` keys as null, with basis
+  `not determined from recorded parcel data` and explicit limitations. The tool
+  output schema now declares these keys null; consumers must accept null.
+- Remove calculated capacity and compliance inferences from lot prose, tool
+  descriptions, server instructions and package/registry descriptions.
+- Label the public map link `Public lot map`; preserve `full_report_url` as a
+  documented legacy field name that does not provide paid report data.
+- Identify district output as scraped NYRezone HTML summaries, without claiming
+  direct verification against the NYC Zoning Resolution.
+- Identify release labels and check stamps as site-reported, not independently
+  validated for each result; use unknown when the release stamp is missing or
+  unavailable. Align package, lockfile, runtime and registry manifest at 0.2.0.
+- Expand existing fixture and real stdio tests for the former 16,094 sq ft example,
+  the formerly flagged Empire State Building, false split flags with multiple
+  districts, unknown source labels, null compatibility and owner-field exclusion.
+- Update existing exact dependency pins to MCP server/client SDK 2.4.0 and Zod
+  4.6.7 to resolve native npm audit advisories affecting the previous pins.
+- Reuse the existing SDK, test suite and documentation; no new service, framework,
+  schedule or publishing-trust change.
+
+## 2026-10-28 — Documentation accuracy
+
+Clarify that the published 0.1.0 stdio package is separate from the hosted ChatGPT
+facts app. Recorded FAR fields, calculated screening outputs and district summaries
+parsed from NYRezone are distinguished from parcel-specific legal capacity. The
+README now documents the separate residential-estimate/highest-FAR flag behavior,
+the legacy `allowed_floor_area_sqft`/`sq ft allowed` wording, split-lot limits and
+the public map destination of the `Full report` link. No runtime, version or
+dependency changed; these disclosures do not certify capacity or all district rules.
+
+Verification: 39 existing fixture/stdio tests passed. Published npm JavaScript
+matches the fresh source build. Three public BBL examples matched selected city
+record fields, and the city records' 26v2 version matched the package's methodology
+label on October 28. These observations establish neither legal allowance nor
+exhaustive API/district correctness.
+
+## 0.1.1 - planned
+
+- Optional packaging: MCPB bundle and Smithery listing (removed from 0.1.0 until they can be built, signed and checksummed for real).
+
+## 0.1.0 - 2026-10-15
+
+Initial build; version 0.1.0 was subsequently published to npm and the official MCP
+registry on October 16, 2026.
+
+- Tools: `lookup_lot`, `get_zoning_district`, `list_zoning_districts`.
+- Lot data from NYRezone `/api/pluto`; owner name/type and assessed values are dropped before any result is returned.
+- Address lookup resolves through NYC Planning Labs Geosearch (NYRezone has no address endpoint) and errors on ambiguous or unknown addresses.
+- District rules parsed from the server-rendered nyrezone.com district pages; parsers fail loudly if the page format changes.
+- Client: descriptive User-Agent, 1 h cache, serialized requests, 20 req/min cap, 10 s timeout, 2 MB cap.
+- Tests: node:test with recorded fixtures, malformed-input cases, and a stdio end-to-end test against a local fixture server.
+- Skipped: borough-level underbuilt summary (no public data endpoint).
+- Review fixes: borough hint read only from the parsed locality and text after the first comma; governing FAR is the highest of residential/commercial/community-facility, and gross building area is no longer presented as evidence of non-compliance; error and empty 200 bodies rejected; district links filtered against the live index; cache bounded at 500 entries; off-origin redirects rejected; publish workflow pins npm and actions by SHA; server.json gets runtimeHint npx.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giani Brussich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# nyrezone-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read-only [MCP](https://modelcontextprotocol.io) server that gives AI assistants recorded NYC lot fields from public [NYRezone](https://nyrezone.com) pages and APIs: zoning districts, MapPLUTO FAR fields, lot and gross building area, and district summaries as published by NYRezone.
+
+The legacy stdio package is separate from NYRezone's hosted ChatGPT facts app.
+Version 0.2.0 removes the previous floor-area calculations. Recorded parcel data
+and scraped district summaries do not determine parcel-specific legal capacity,
+unused development rights or zoning compliance, or certify that every district
+rule is current.
+
+It exposes only data that is already public and unauthenticated. No owner names, no assessed values, no paid report data, no account access.
+
+## Install
+
+Requires Node 20+.
+
+```bash
+npx -y nyrezone-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nyrezone": { "command": "npx", "args": ["-y", "nyrezone-mcp"] }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add nyrezone -- npx -y nyrezone-mcp
+```
+
+## Tools
+
+All tools are read-only (`readOnlyHint: true`).
+
+| Tool | Input | Returns |
+|---|---|---|
+| `lookup_lot` | `address` (starts with a house number, include the borough) **or** `bbl` (10-digit borough-block-lot) | Recorded zoning district(s), overlays, special districts and FAR fields, lot/gross building area, year built and land use. Deprecated capacity calculation fields are retained as null. Ambiguous or unknown address matches return an error. |
+| `get_zoning_district` | `code`, e.g. `R6A`, `C4-2`, `M1-2/R6A` | FAR, height rules and bonuses as NYRezone publishes them, citywide lot counts, average built FAR. Unknown code returns the list of valid codes. |
+| `list_zoning_districts` | optional `family`, e.g. `R6` | The 51 districts NYRezone documents, each with its district-family description. |
+
+Every successful result includes a source line and disclaimer. The MapPLUTO release
+label for lot lookups is reported by NYRezone's methodology page; district lookups
+use the label on the district page. Neither is independently validated for the
+returned parcel or result. A missing or unavailable release stamp is `unknown`. District rules are parsed from NYRezone's pages, not fetched directly
+from the Zoning Resolution. The visible `Public lot map` link and legacy `full_report_url` field both open
+the public lot map; neither returns paid report data.
+
+Not included: a borough-level "underbuilt" summary. NYRezone publishes that only as web pages, not as a data endpoint.
+
+### Example
+
+`lookup_lot` with `bbl: "3052410015"` returns, in part: recorded zoning R7A,
+lot area 4,675 sq ft, gross building area 2,606 sq ft, built FAR 0.56 and a
+MapPLUTO residential FAR field of 4.0. It does not calculate capacity from those
+fields. Its `unused_floor_area` compatibility object includes:
+
+```json
+{
+  "estimate_sqft": null,
+  "allowed_floor_area_sqft": null,
+  "governing_far": null,
+  "overbuilt": null,
+  "basis": "not determined from recorded parcel data"
+}
+```
+
+The object also includes `caveats` describing the limits below.
+
+## Capacity is not determined
+
+The previous release multiplied recorded FAR by lot area and subtracted gross
+building area. Version 0.2.0 removes that arithmetic for every lot, including
+split-zoned lots and records with multiple districts but no split-zone flag.
+The four deprecated fields above remain present and always null; their output
+schema accepts null. Consumers that assumed a numeric estimate or boolean flag
+must handle null.
+
+Gross building area is not zoning floor area. Recorded FAR fields alone do not
+establish applicable FAR or legally permitted floor area. District boundaries,
+split-zone geometry, applicable uses, special districts, overlays, bonuses,
+zoning-lot history and current rules require separate verification. The tool
+returns the recorded district and FAR facts without deciding capacity, unused
+development rights or compliance.
+
+## Data sources and what leaves your machine
+
+- **nyrezone.com** (`/api/pluto`, `/zoning`, `/zoning/<code>`, `/methodology`): lot data and district pages. The lot endpoint supplies MapPLUTO fields; HTML district summaries are NYRezone's presentation, not direct Zoning Resolution verification. Release labels and check stamps are reported by the site, not independently validated for each returned parcel.
+- **NYC Planning Labs Geosearch** (`geosearch.planninglabs.nyc`): used only to turn a street address into a BBL, because NYRezone has no address endpoint. This is the one third-party host; the address you ask about is sent to it. BBL lookups and district lookups never contact it.
+
+The owner name and owner type that NYRezone's lot API returns are dropped in this server and never appear in a tool result.
+
+## Limits and politeness
+
+- Descriptive `User-Agent` (`nyrezone-mcp/<version> (+repo URL)`).
+- Requests are serialized, at least 1 second apart, capped at 20 upstream requests per minute, with a 10 second timeout and a 2 MB response cap.
+- Responses are cached in memory for 1 hour (not persisted).
+- Input is validated before any request: addresses 5-150 characters starting with a house number; BBLs must be 10 digits starting 1-5. Everything sent upstream is URL-encoded.
+
+## Disclaimer
+
+Informational only. Not legal, architectural, or zoning-compliance advice. Confirm with the NYC Department of City Planning or a licensed professional before relying on it. Not affiliated with the City of New York.
+
+## Development
+
+```bash
+npm install
+npm test        # builds, then runs node:test against recorded fixtures (no live network)
+```
+
+Fixtures in `fixtures/` are recorded public responses; the lot fixtures keep the raw owner fields on purpose so the tests prove they are dropped. Environment variables `NYREZONE_MCP_BASE_URL`, `NYREZONE_MCP_GEOSEARCH_URL` and `NYREZONE_MCP_MIN_INTERVAL_MS` exist for the end-to-end test only.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { createServer } from './server.js';
+import { VERSION } from './client.js';
+if (process.argv.includes('--version')) {
+    console.log(VERSION);
+}
+else if (process.argv.includes('--help')) {
+    console.error('nyrezone-mcp: MCP server (stdio) for public NYC zoning data via nyrezone.com. No flags; configure it in your MCP client.');
+}
+else {
+    // Test-only overrides so the end-to-end test can point at a local fixture server.
+    const intervalEnv = Number(process.env.NYREZONE_MCP_MIN_INTERVAL_MS);
+    serveStdio(() => createServer({
+        nyrezoneBase: process.env.NYREZONE_MCP_BASE_URL || undefined,
+        geosearchBase: process.env.NYREZONE_MCP_GEOSEARCH_URL || undefined,
+        minIntervalMs: Number.isFinite(intervalEnv) && process.env.NYREZONE_MCP_MIN_INTERVAL_MS ? intervalEnv : undefined,
+    }));
+}

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+export declare const VERSION = "0.2.0";
+export declare const REPO_URL = "https://github.com/gbrussich52/nyrezone-mcp";
+export type UpstreamKind = 'timeout' | 'http' | 'network' | 'rate_limited' | 'too_large' | 'parse';
+export declare class UpstreamError extends Error {
+    readonly kind: UpstreamKind;
+    readonly status?: number | undefined;
+    constructor(kind: UpstreamKind, message: string, status?: number | undefined);
+}
+export interface ClientOptions {
+    fetchImpl?: typeof fetch;
+    /** Origin serving /api/pluto and /zoning pages. Overridable for tests only. */
+    nyrezoneBase?: string;
+    /** Origin serving the NYC Planning Labs Geosearch API. Overridable for tests only. */
+    geosearchBase?: string;
+    minIntervalMs?: number;
+    timeoutMs?: number;
+    cacheTtlMs?: number;
+    maxRequestsPerMinute?: number;
+    maxBytes?: number;
+    now?: () => number;
+}
+export interface FetchedText {
+    status: number;
+    body: string;
+}
+export declare class HttpClient {
+    readonly nyrezoneBase: string;
+    readonly geosearchBase: string;
+    private readonly fetchImpl;
+    private readonly minIntervalMs;
+    private readonly timeoutMs;
+    private readonly cacheTtlMs;
+    private readonly maxPerMinute;
+    private readonly maxBytes;
+    private readonly now;
+    private readonly cache;
+    private readonly sent;
+    private queue;
+    private lastSentAt;
+    constructor(opts?: ClientOptions);
+    /** GET a URL (cached). 404 is returned as a value, not thrown; other non-2xx throw. */
+    getText(url: string, accept: string): Promise<FetchedText>;
+    private fetchOnce;
+    /** Bound memory: past MAX_CACHE entries drop expired ones first, then the oldest. */
+    private evict;
+    get cacheSize(): number;
+    private readCapped;
+}

package/dist/client.js

@@ -0,0 +1,152 @@
+// HTTP access for the two public hosts this server reads. Everything that touches
+// the network goes through here so the politeness rules (User-Agent, cache,
+// serialized requests, request cap, timeout, size cap) live in one place.
+export const VERSION = '0.2.0';
+export const REPO_URL = 'https://github.com/gbrussich52/nyrezone-mcp';
+export class UpstreamError extends Error {
+    kind;
+    status;
+    constructor(kind, message, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'UpstreamError';
+    }
+}
+const MAX_CACHE = 500;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class HttpClient {
+    nyrezoneBase;
+    geosearchBase;
+    fetchImpl;
+    minIntervalMs;
+    timeoutMs;
+    cacheTtlMs;
+    maxPerMinute;
+    maxBytes;
+    now;
+    cache = new Map();
+    sent = [];
+    queue = Promise.resolve();
+    lastSentAt = 0;
+    constructor(opts = {}) {
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.nyrezoneBase = (opts.nyrezoneBase ?? 'https://nyrezone.com').replace(/\/+$/, '');
+        this.geosearchBase = (opts.geosearchBase ?? 'https://geosearch.planninglabs.nyc').replace(/\/+$/, '');
+        this.minIntervalMs = opts.minIntervalMs ?? 1000;
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+        this.cacheTtlMs = opts.cacheTtlMs ?? 60 * 60 * 1000;
+        this.maxPerMinute = opts.maxRequestsPerMinute ?? 20;
+        this.maxBytes = opts.maxBytes ?? 2 * 1024 * 1024;
+        this.now = opts.now ?? Date.now;
+    }
+    /** GET a URL (cached). 404 is returned as a value, not thrown; other non-2xx throw. */
+    getText(url, accept) {
+        const hit = this.cache.get(url);
+        if (hit && this.now() - hit.at < this.cacheTtlMs)
+            return Promise.resolve(hit.value);
+        // Serialize so concurrent tool calls never burst the upstream hosts.
+        const run = this.queue.then(() => this.fetchOnce(url, accept));
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    async fetchOnce(url, accept) {
+        const cached = this.cache.get(url);
+        if (cached && this.now() - cached.at < this.cacheTtlMs)
+            return cached.value;
+        const t = this.now();
+        while (this.sent.length && t - this.sent[0] > 60_000)
+            this.sent.shift();
+        if (this.sent.length >= this.maxPerMinute) {
+            throw new UpstreamError('rate_limited', `nyrezone-mcp is limiting itself to ${this.maxPerMinute} upstream requests per minute; try again shortly.`);
+        }
+        const wait = this.lastSentAt + this.minIntervalMs - t;
+        if (wait > 0)
+            await sleep(wait);
+        this.lastSentAt = this.now();
+        this.sent.push(this.lastSentAt);
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(url, {
+                headers: {
+                    'user-agent': `nyrezone-mcp/${VERSION} (+${REPO_URL}; read-only MCP client)`,
+                    accept,
+                },
+                signal: ctrl.signal,
+            });
+            if (res.status === 429) {
+                throw new UpstreamError('rate_limited', 'The upstream service asked us to slow down (HTTP 429); try again in a minute.', 429);
+            }
+            // A redirect must not carry us (and our User-Agent) off the two hosts we were pointed at.
+            if (res.url) {
+                let origin = '';
+                try {
+                    origin = new URL(res.url).origin;
+                }
+                catch { /* handled below */ }
+                const allowed = [this.nyrezoneBase, this.geosearchBase].map((b) => new URL(b).origin);
+                if (!allowed.includes(origin))
+                    throw new UpstreamError('http', 'Upstream redirected to an unexpected host; response rejected.');
+            }
+            const body = await this.readCapped(res);
+            if (res.status !== 404 && !res.ok) {
+                throw new UpstreamError('http', `Upstream returned HTTP ${res.status}.`, res.status);
+            }
+            const value = { status: res.status, body };
+            this.cache.set(url, { at: this.now(), value });
+            this.evict();
+            return value;
+        }
+        catch (err) {
+            if (err instanceof UpstreamError)
+                throw err;
+            if (ctrl.signal.aborted)
+                throw new UpstreamError('timeout', `Upstream did not answer within ${this.timeoutMs / 1000}s.`);
+            throw new UpstreamError('network', 'Could not reach the upstream service.');
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Bound memory: past MAX_CACHE entries drop expired ones first, then the oldest. */
+    evict() {
+        if (this.cache.size <= MAX_CACHE)
+            return;
+        const t = this.now();
+        for (const [k, v] of this.cache)
+            if (t - v.at >= this.cacheTtlMs)
+                this.cache.delete(k);
+        while (this.cache.size > MAX_CACHE) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.cache.delete(oldest);
+        }
+    }
+    get cacheSize() {
+        return this.cache.size;
+    }
+    async readCapped(res) {
+        const declared = Number(res.headers.get('content-length') ?? '0');
+        if (declared > this.maxBytes)
+            throw new UpstreamError('too_large', 'Upstream response is larger than the safety cap.');
+        if (!res.body)
+            return '';
+        const reader = res.body.getReader();
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > this.maxBytes) {
+                await reader.cancel();
+                throw new UpstreamError('too_large', 'Upstream response is larger than the safety cap.');
+            }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+    }
+}

package/dist/geocode.d.ts

@@ -0,0 +1,16 @@
+import { HttpClient } from './client.js';
+export interface Candidate {
+    label: string;
+    bbl: string;
+}
+export declare class AmbiguousAddressError extends Error {
+    readonly candidates: Candidate[];
+    constructor(candidates: Candidate[]);
+}
+export declare class AddressNotFoundError extends Error {
+    constructor();
+}
+export declare function normalizeStreet(s: string): string;
+/** Validates raw address input. Everything later is URL-encoded, so this is about clear errors, not safety. */
+export declare function validateAddress(input: string): string;
+export declare function resolveAddress(client: HttpClient, rawAddress: string): Promise<Candidate>;

package/dist/geocode.js

@@ -0,0 +1,107 @@
+// Address -> BBL via NYC Planning Labs Geosearch (public, no key). NYRezone exposes no
+// address endpoint of its own; its browser search uses this same service. We never guess:
+// anything other than exactly one distinct BBL for the same house number and street is an error.
+import { UpstreamError } from './client.js';
+import { InputError } from './lot.js';
+export class AmbiguousAddressError extends Error {
+    candidates;
+    constructor(candidates) {
+        super('Address matches more than one tax lot.');
+        this.candidates = candidates;
+        this.name = 'AmbiguousAddressError';
+    }
+}
+export class AddressNotFoundError extends Error {
+    constructor() {
+        super('No tax lot found for that address.');
+        this.name = 'AddressNotFoundError';
+    }
+}
+const SUFFIX = {
+    AVENUE: 'AVE', AV: 'AVE', STREET: 'ST', BOULEVARD: 'BLVD', ROAD: 'RD', DRIVE: 'DR', PLACE: 'PL', LANE: 'LN',
+    COURT: 'CT', PARKWAY: 'PKWY', TERRACE: 'TER', EAST: 'E', WEST: 'W', NORTH: 'N', SOUTH: 'S',
+};
+export function normalizeStreet(s) {
+    return s
+        .toUpperCase()
+        .replace(/[^A-Z0-9 ]+/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((t) => {
+        const ord = t.match(/^(\d+)(ST|ND|RD|TH)$/);
+        return ord ? ord[1] : (SUFFIX[t] ?? t);
+    })
+        .join(' ');
+}
+const BOROUGH_WORDS = {
+    MANHATTAN: 'Manhattan', BROOKLYN: 'Brooklyn', BRONX: 'Bronx', 'THE BRONX': 'Bronx',
+    QUEENS: 'Queens', 'STATEN ISLAND': 'Staten Island',
+};
+const CTRL = /[\u0000-\u001f\u007f]/;
+/** Validates raw address input. Everything later is URL-encoded, so this is about clear errors, not safety. */
+export function validateAddress(input) {
+    const a = input.replace(/\s+/g, ' ').trim();
+    if (a.length === 0)
+        throw new InputError('address is empty. Provide a street address with a house number, e.g. "1187 Ocean Ave, Brooklyn".');
+    if (a.length < 5 || a.length > 150)
+        throw new InputError('address must be between 5 and 150 characters.');
+    if (CTRL.test(a))
+        throw new InputError('address contains control characters.');
+    if (!/^\d+[A-Za-z]?(-\d+)?\s+\S/.test(a)) {
+        throw new InputError('address must start with a house number followed by a street name, e.g. "1187 Ocean Ave, Brooklyn". For a block/lot, pass bbl instead.');
+    }
+    return a;
+}
+export async function resolveAddress(client, rawAddress) {
+    const address = validateAddress(rawAddress);
+    const url = `${client.geosearchBase}/v2/search?text=${encodeURIComponent(address)}&size=10`;
+    const res = await client.getText(url, 'application/json');
+    if (res.status !== 200)
+        throw new UpstreamError('http', `Address search returned HTTP ${res.status}.`, res.status);
+    let data;
+    try {
+        data = JSON.parse(res.body);
+    }
+    catch {
+        throw new UpstreamError('parse', 'Address search returned an unreadable response.');
+    }
+    const features = Array.isArray(data.features) ? data.features : [];
+    const parsed = data.geocoding?.query?.parsed_text ?? {};
+    const fallback = address.match(/^(\S+)\s+([^,]+)/);
+    const house = (parsed.housenumber ?? fallback?.[1] ?? '').toUpperCase();
+    const street = normalizeStreet(parsed.street ?? fallback?.[2] ?? '');
+    if (!house || !street)
+        throw new AddressNotFoundError();
+    // Borough hint only from Pelias' parsed locality/admin and the text after the first comma.
+    // Scanning the whole string would read "Manhattan" in "100 Manhattan Ave, Brooklyn" as the borough.
+    const tail = address.split(',').slice(1).join(' ');
+    const hintText = `${parsed.locality ?? ''} ${parsed.admin ?? ''} ${tail}`.toUpperCase();
+    let boroughHint = null;
+    for (const [word, name] of Object.entries(BOROUGH_WORDS)) {
+        if (new RegExp(`(^|[^A-Z])${word}([^A-Z]|$)`).test(hintText)) {
+            boroughHint = name;
+            break;
+        }
+    }
+    const byBbl = new Map();
+    for (const f of features) {
+        const p = f.properties;
+        const bbl = p?.addendum?.pad?.bbl;
+        if (!p || !bbl || !/^[1-5]\d{9}$/.test(bbl))
+            continue;
+        if ((p.housenumber ?? '').toUpperCase() !== house)
+            continue;
+        if (normalizeStreet(p.street ?? '') !== street)
+            continue;
+        if (boroughHint && p.borough && p.borough !== boroughHint)
+            continue;
+        if (!byBbl.has(bbl))
+            byBbl.set(bbl, { label: p.label ?? `${p.housenumber} ${p.street}`, bbl });
+    }
+    const found = [...byBbl.values()];
+    if (found.length === 0)
+        throw new AddressNotFoundError();
+    if (found.length > 1)
+        throw new AmbiguousAddressError(found.slice(0, 5));
+    return found[0];
+}

package/dist/lot.d.ts

@@ -0,0 +1,48 @@
+export declare class InputError extends Error {
+    constructor(message: string);
+}
+/** Accepts "3052410015", "3-05241-0015", "3/5241/15" style input and a trailing ".0". */
+export declare function parseBbl(input: string): string;
+export declare const LAND_USE: Record<string, string>;
+export interface LotRecord {
+    bbl: string;
+    address: string | null;
+    borough: string | null;
+    zip: string | null;
+    community_district: string | null;
+    zoning_districts: string[];
+    commercial_overlays: string[];
+    special_districts: string[];
+    split_zone: boolean;
+    historic_district: string | null;
+    landmark: string | null;
+    land_use: {
+        code: string;
+        label: string;
+    } | null;
+    building_class: string | null;
+    lot_area_sqft: number | null;
+    building_area_sqft: number | null;
+    residential_units: number | null;
+    total_units: number | null;
+    num_floors: number | null;
+    year_built: number | null;
+    built_far: number | null;
+    max_far: {
+        residential: number | null;
+        commercial: number | null;
+        community_facility: number | null;
+    };
+    unused_floor_area: UnusedFloorArea;
+}
+export interface UnusedFloorArea {
+    /** Deprecated compatibility fields: recorded parcel data does not determine capacity. */
+    estimate_sqft: null;
+    overbuilt: null;
+    allowed_floor_area_sqft: null;
+    governing_far: null;
+    basis: string;
+    caveats: string[];
+}
+/** Allow-list mapping from the raw API row. Throws InputError-free; callers validate the BBL first. */
+export declare function mapPlutoRow(raw: unknown, bbl: string): LotRecord;

package/dist/lot.js

@@ -0,0 +1,129 @@
+// BBL handling and the mapping from NYRezone's raw /api/pluto row to the small,
+// PII-free lot record this server returns. The mapping is an allow-list: any field
+// not named here (owner name/type, assessed values, ...) can never reach a tool result.
+export class InputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InputError';
+    }
+}
+/** Accepts "3052410015", "3-05241-0015", "3/5241/15" style input and a trailing ".0". */
+export function parseBbl(input) {
+    const raw = input.trim();
+    if (raw.length === 0 || raw.length > 40)
+        throw new InputError('bbl must be a 10-digit NYC borough-block-lot number, e.g. 3052410015.');
+    const dotted = raw.replace(/\.0+$/, '');
+    const parts = dotted.split(/[-/\s]+/);
+    let digits;
+    if (parts.length === 3 && parts.every((p) => /^\d+$/.test(p))) {
+        const [b, block, lot] = parts;
+        if (b.length !== 1 || block.length > 5 || lot.length > 4)
+            throw new InputError('bbl parts must be borough (1 digit), block (up to 5), lot (up to 4).');
+        digits = b + block.padStart(5, '0') + lot.padStart(4, '0');
+    }
+    else if (/^\d{10}$/.test(dotted)) {
+        digits = dotted;
+    }
+    else {
+        throw new InputError('bbl must be a 10-digit NYC borough-block-lot number, e.g. 3052410015 (or borough-block-lot like 3-05241-0015).');
+    }
+    if (!/^[1-5]/.test(digits))
+        throw new InputError('bbl must start with a borough digit 1-5 (1 Manhattan, 2 Bronx, 3 Brooklyn, 4 Queens, 5 Staten Island).');
+    return digits;
+}
+const BOROUGHS = { MN: 'Manhattan', BX: 'Bronx', BK: 'Brooklyn', QN: 'Queens', SI: 'Staten Island' };
+export const LAND_USE = {
+    '01': 'One & Two Family Buildings',
+    '02': 'Multi-Family Walk-Up Buildings',
+    '03': 'Multi-Family Elevator Buildings',
+    '04': 'Mixed Residential & Commercial Buildings',
+    '05': 'Commercial & Office Buildings',
+    '06': 'Industrial & Manufacturing',
+    '07': 'Transportation & Utility',
+    '08': 'Public Facilities & Institutions',
+    '09': 'Open Space & Outdoor Recreation',
+    '10': 'Parking Facilities',
+    '11': 'Vacant Land',
+};
+function num(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : null;
+    if (typeof v !== 'string' || v.trim() === '')
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+function str(v) {
+    if (typeof v !== 'string')
+        return null;
+    const s = v.trim();
+    return s === '' ? null : s;
+}
+const round = (n, places) => Math.round(n * 10 ** places) / 10 ** places;
+function undeterminedFloorArea() {
+    return {
+        estimate_sqft: null,
+        overbuilt: null,
+        allowed_floor_area_sqft: null,
+        governing_far: null,
+        basis: 'not determined from recorded parcel data',
+        caveats: [
+            'MapPLUTO building area is gross building area, not zoning floor area.',
+            'Recorded FAR fields do not establish an applicable FAR or legally permitted floor area for this parcel.',
+            'District boundaries and split-zone geometry, applicable uses, special districts, overlays, bonuses, zoning-lot history and current rules require separate verification.',
+            'Unused development rights, development capacity and zoning compliance are not determined by this tool.',
+        ],
+    };
+}
+/** Allow-list mapping from the raw API row. Throws InputError-free; callers validate the BBL first. */
+export function mapPlutoRow(raw, bbl) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw new InputError('Unexpected lot data format from upstream.');
+    const r = raw;
+    const zoning = ['zonedist1', 'zonedist2', 'zonedist3', 'zonedist4'].map((k) => str(r[k])).filter((v) => v !== null);
+    const overlays = ['overlay1', 'overlay2'].map((k) => str(r[k])).filter((v) => v !== null);
+    const special = ['spdist1', 'spdist2', 'spdist3'].map((k) => str(r[k])).filter((v) => v !== null);
+    const luRaw = str(r.landuse);
+    const luCode = luRaw && /^\d{1,2}$/.test(luRaw) ? luRaw.padStart(2, '0') : null;
+    const yearBuilt = num(r.yearbuilt);
+    const splitZone = r.splitzone === true || r.splitzone === 'true';
+    const lotArea = num(r.lotarea);
+    const buildingArea = num(r.bldgarea);
+    const far = {
+        residential: num(r.residfar),
+        commercial: num(r.commfar),
+        community_facility: num(r.facilfar),
+    };
+    const farRounded = {
+        residential: far.residential === null ? null : round(far.residential, 2),
+        commercial: far.commercial === null ? null : round(far.commercial, 2),
+        community_facility: far.community_facility === null ? null : round(far.community_facility, 2),
+    };
+    const builtFar = num(r.builtfar);
+    const boroCode = str(r.borough);
+    return {
+        bbl,
+        address: str(r.address),
+        borough: boroCode ? (BOROUGHS[boroCode.toUpperCase()] ?? boroCode) : null,
+        zip: str(r.zipcode),
+        community_district: str(r.cd),
+        zoning_districts: zoning,
+        commercial_overlays: overlays,
+        special_districts: special,
+        split_zone: splitZone,
+        historic_district: str(r.histdist),
+        landmark: str(r.landmark),
+        land_use: luCode ? { code: luCode, label: LAND_USE[luCode] ?? 'Unknown land use code' } : null,
+        building_class: str(r.bldgclass),
+        lot_area_sqft: lotArea,
+        building_area_sqft: buildingArea,
+        residential_units: num(r.unitsres),
+        total_units: num(r.unitstotal),
+        num_floors: num(r.numfloors) === null ? null : round(num(r.numfloors), 1),
+        // MapPLUTO uses 0 for "unknown".
+        year_built: yearBuilt && yearBuilt > 0 ? yearBuilt : null,
+        built_far: builtFar === null ? null : round(builtFar, 2),
+        max_far: farRounded,
+        unused_floor_area: undeterminedFloorArea(),
+    };
+}

package/dist/parse.d.ts

@@ -0,0 +1,36 @@
+export declare class ParseError extends Error {
+    constructor(message: string);
+}
+export declare function decodeText(html: string): string;
+export interface DistrictIndexEntry {
+    code: string;
+    slug: string;
+    family: string;
+    familyLabel: string;
+}
+/** Parses https://nyrezone.com/zoning: family headings, each followed by its district links. */
+export declare function parseZoningIndex(html: string): DistrictIndexEntry[];
+export interface RuleRow {
+    rule: string;
+    value: string;
+    note: string;
+}
+export interface DistrictPage {
+    code: string;
+    summary: string;
+    rules: RuleRow[];
+    stats: Record<string, string>;
+    boroughs: {
+        borough: string;
+        parcels: string;
+    }[];
+    dataVintage: string | null;
+    dataCheckedOn: string | null;
+}
+/** Parses https://nyrezone.com/zoning/<slug>. Not every district has a rules table. */
+export declare function parseDistrictPage(html: string): DistrictPage;
+/** Extracts "MapPLUTO 26v2" and the "checked <date>" stamp from a nyrezone page, if present. */
+export declare function parseVintage(html: string): {
+    release: string | null;
+    checkedOn: string | null;
+};

package/dist/parse.js

@@ -0,0 +1,80 @@
+// Parsers for the server-rendered nyrezone.com pages. They fail loudly (ParseError)
+// when the markup no longer has the expected landmarks, so a site redesign surfaces
+// as a clear error instead of silently wrong zoning numbers.
+export class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+    }
+}
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+export function decodeText(html) {
+    return html
+        .replace(/<!--.*?-->/gs, '')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+        if (e[0] === '#') {
+            const code = e[1].toLowerCase() === 'x' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code < 0x110000 ? String.fromCodePoint(code) : m;
+        }
+        return ENTITIES[e.toLowerCase()] ?? m;
+    })
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Parses https://nyrezone.com/zoning: family headings, each followed by its district links. */
+export function parseZoningIndex(html) {
+    const out = [];
+    const re = /<h2[^>]*>(.*?)<\/h2>\s*<p[^>]*>(.*?)<\/p>/gs;
+    for (const m of html.matchAll(re)) {
+        const heading = decodeText(m[1]);
+        const parts = heading.split(/\s+[—–-]\s+/);
+        if (parts.length < 2)
+            continue;
+        const links = [...m[2].matchAll(/<a[^>]*href="\/zoning\/([a-z0-9-]+)"[^>]*>(.*?)<\/a>/gs)];
+        for (const l of links) {
+            out.push({ code: decodeText(l[2]), slug: l[1], family: parts[0], familyLabel: parts.slice(1).join(' - ') });
+        }
+    }
+    if (out.length === 0)
+        throw new ParseError('The NYRezone zoning index no longer has the expected structure.');
+    return out;
+}
+const STAT_LABELS = ['Parcels citywide', 'High-opportunity lots', 'Avg built FAR', 'Avg max resid. FAR'];
+/** Parses https://nyrezone.com/zoning/<slug>. Not every district has a rules table. */
+export function parseDistrictPage(html) {
+    const h1 = html.match(/<h1[^>]*>(.*?)<\/h1>/s);
+    if (!h1)
+        throw new ParseError('District page has no heading; the page format may have changed.');
+    const code = decodeText(h1[1]).replace(/\s+Zoning in NYC\s*$/i, '').trim();
+    const after = html.slice(h1.index + h1[0].length);
+    const intro = after.match(/<p[^>]*>(.*?)<\/p>/s);
+    if (!code || !intro)
+        throw new ParseError('District page is missing its summary; the page format may have changed.');
+    const rules = [];
+    const table = html.match(/<table[\s\S]*?<\/table>/);
+    if (table) {
+        for (const row of table[0].matchAll(/<tr[^>]*>\s*<th[^>]*scope="row"[^>]*>(.*?)<\/th>\s*<td[^>]*>(.*?)<\/td>\s*<td[^>]*>(.*?)<\/td>\s*<\/tr>/gs)) {
+            rules.push({ rule: decodeText(row[1]), value: decodeText(row[2]), note: decodeText(row[3]) });
+        }
+    }
+    const stats = {};
+    for (const m of html.matchAll(/<div[^>]*>([^<]{1,20})<\/div><div[^>]*>([^<]{1,40})<\/div>/g)) {
+        const label = decodeText(m[2]);
+        if (STAT_LABELS.includes(label))
+            stats[label] = decodeText(m[1]);
+    }
+    const boroughs = [];
+    for (const m of html.matchAll(/<li><a[^>]*href="\/boroughs\/[a-z-]+"[^>]*>(.*?)<\/a>:\s*(?:<!-- -->)?([\d,]+)(?:<!-- -->)?\s*parcels<\/li>/gs)) {
+        boroughs.push({ borough: decodeText(m[1]), parcels: m[2] });
+    }
+    const vintage = parseVintage(html);
+    return { code, summary: decodeText(intro[1]), rules, stats, boroughs, dataVintage: vintage.release, dataCheckedOn: vintage.checkedOn };
+}
+/** Extracts "MapPLUTO 26v2" and the "checked <date>" stamp from a nyrezone page, if present. */
+export function parseVintage(html) {
+    const text = decodeText(html.replace(/<script[\s\S]*?<\/script>/g, ''));
+    const rel = text.match(/MapPLUTO\s+(\d\d[vV]\d)/);
+    const checked = text.match(/MapPLUTO\s+\d\d[vV]\d\s*\(checked\s+([^)]{3,30})\)/);
+    return { release: rel ? `MapPLUTO ${rel[1]}` : null, checkedOn: checked ? checked[1].trim() : null };
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { type ClientOptions } from './client.js';
+export declare function createServer(clientOptions?: ClientOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/server';
+import { HttpClient, VERSION } from './client.js';
+import { getDistrict, listDistricts, lookupLot } from './service.js';
+const INSTRUCTIONS = [
+    'Read-only access to public NYC zoning data via NYRezone (nyrezone.com), which is built on NYC MapPLUTO.',
+    'Tools: lookup_lot (a tax lot by address or 10-digit BBL), get_zoning_district (NYRezone HTML summary for one zoning code), list_zoning_districts.',
+    'Report only what the tools return and always keep the source line and disclaimer with it.',
+    'Recorded FAR and gross building area do not determine development capacity, unused development rights or zoning compliance. Deprecated unused_floor_area calculation fields are always null.',
+    'If a tool reports an ambiguous or unknown input, ask the user to clarify rather than guessing.',
+].join(' ');
+// openWorldHint is true because every call reaches out to public web services.
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+function respond(o) {
+    if (!o.ok)
+        return { isError: true, content: [{ type: 'text', text: o.error }] };
+    return { content: [{ type: 'text', text: o.text }], structuredContent: o.data };
+}
+const lotSchema = z.object({
+    bbl: z.string(),
+    address: z.string().nullable(),
+    borough: z.string().nullable(),
+    zip: z.string().nullable(),
+    community_district: z.string().nullable(),
+    zoning_districts: z.array(z.string()),
+    commercial_overlays: z.array(z.string()),
+    special_districts: z.array(z.string()),
+    split_zone: z.boolean(),
+    historic_district: z.string().nullable(),
+    landmark: z.string().nullable(),
+    land_use: z.object({ code: z.string(), label: z.string() }).nullable(),
+    building_class: z.string().nullable(),
+    lot_area_sqft: z.number().nullable(),
+    building_area_sqft: z.number().nullable(),
+    residential_units: z.number().nullable(),
+    total_units: z.number().nullable(),
+    num_floors: z.number().nullable(),
+    year_built: z.number().nullable(),
+    built_far: z.number().nullable(),
+    max_far: z.object({ residential: z.number().nullable(), commercial: z.number().nullable(), community_facility: z.number().nullable() }),
+    unused_floor_area: z.object({
+        estimate_sqft: z.null().describe('Deprecated; capacity is not determined from recorded parcel data.'),
+        overbuilt: z.null().describe('Deprecated; zoning compliance is not determined from gross building area.'),
+        allowed_floor_area_sqft: z.null().describe('Deprecated; legally permitted floor area is not determined.'),
+        governing_far: z.null().describe('Deprecated; applicable FAR is not determined.'),
+        basis: z.string(),
+        caveats: z.array(z.string()),
+    }),
+});
+export function createServer(clientOptions = {}) {
+    const client = new HttpClient(clientOptions);
+    const server = new McpServer({ name: 'nyrezone-mcp', version: VERSION, title: 'NYRezone - NYC zoning lookups' }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    server.registerTool('lookup_lot', {
+        title: 'Look up an NYC tax lot',
+        description: 'Look up one NYC tax lot by street address OR 10-digit BBL (borough-block-lot). Returns recorded zoning district(s), MapPLUTO FAR fields, lot and gross building area, year built and land use via NYRezone. Does not determine development capacity, unused development rights, applicable FAR or zoning compliance; deprecated calculation fields are null. Provide exactly one of address or bbl. Addresses must start with a house number and should include the borough; an ambiguous or unknown address returns an error instead of a guess. Owner and assessment data are never returned.',
+        inputSchema: z.object({
+            address: z.string().optional().describe('Street address starting with a house number, e.g. "1187 Ocean Ave, Brooklyn".'),
+            bbl: z.string().optional().describe('10-digit BBL, e.g. 3052410015 (1 Manhattan, 2 Bronx, 3 Brooklyn, 4 Queens, 5 Staten Island).'),
+        }),
+        outputSchema: z.object({
+            lot: lotSchema,
+            resolved_from: z.enum(['bbl', 'address']),
+            matched_address: z.string().nullable(),
+            full_report_url: z.string().describe('Legacy field name: public lot map URL; no paid report data'),
+            district_pages: z.array(z.string()),
+            source: z.string(),
+        }),
+        annotations: { title: 'Look up an NYC tax lot', ...READ_ONLY },
+    }, async (args) => respond(await lookupLot(client, args)));
+    server.registerTool('get_zoning_district', {
+        title: 'Get an NYC zoning district',
+        description: 'Get the HTML district summary NYRezone publishes for one NYC zoning district code (e.g. R6A, C4-2, M1-2/R6A): max FAR, base and maximum height, bonuses, citywide lot counts and average built FAR. Values are scraped NYRezone summaries, not independently verified against the Zoning Resolution or applied to a parcel. An unknown code returns the list of valid codes.',
+        inputSchema: z.object({ code: z.string().describe('Zoning district code such as R6A, R7-2, C4-2 or M1-2/R6A (case-insensitive).') }),
+        outputSchema: z.object({
+            code: z.string(),
+            summary: z.string(),
+            rules: z.array(z.object({ rule: z.string(), value: z.string(), note: z.string() })),
+            rules_note: z.string().nullable(),
+            stats: z.record(z.string(), z.string()),
+            boroughs: z.array(z.object({ borough: z.string(), parcels: z.string() })),
+            dataVintage: z.string().nullable(),
+            dataCheckedOn: z.string().nullable(),
+            url: z.string(),
+            source: z.string(),
+        }),
+        annotations: { title: 'Get an NYC zoning district', ...READ_ONLY },
+    }, async ({ code }) => respond(await getDistrict(client, code)));
+    server.registerTool('list_zoning_districts', {
+        title: 'List NYC zoning districts',
+        description: 'List the NYC zoning district codes NYRezone documents, each with a one-line summary (its district family description). Optionally filter by family, e.g. R6 or C4.',
+        inputSchema: z.object({ family: z.string().optional().describe('Optional family filter such as R6, C4, M1.') }),
+        outputSchema: z.object({
+            count: z.number(),
+            districts: z.array(z.object({ code: z.string(), family: z.string(), summary: z.string(), url: z.string() })),
+            source: z.string(),
+        }),
+        annotations: { title: 'List NYC zoning districts', ...READ_ONLY },
+    }, async ({ family }) => respond(await listDistricts(client, family)));
+    return server;
+}

package/dist/service.d.ts

@@ -0,0 +1,44 @@
+import { HttpClient } from './client.js';
+import { type LotRecord } from './lot.js';
+import { type DistrictIndexEntry, type DistrictPage } from './parse.js';
+export declare const DISCLAIMER = "Informational only; not legal, architectural, or zoning-compliance advice. Confirm with NYC Department of City Planning / a licensed professional before relying on it.";
+export type Outcome<T> = {
+    ok: true;
+    text: string;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function loadIndex(client: HttpClient): Promise<DistrictIndexEntry[]>;
+export interface DistrictList {
+    count: number;
+    districts: {
+        code: string;
+        family: string;
+        summary: string;
+        url: string;
+    }[];
+    source: string;
+}
+export declare function listDistricts(client: HttpClient, family?: string): Promise<Outcome<DistrictList>>;
+export declare function normalizeCodeInput(code: string): string | null;
+export interface DistrictResult extends DistrictPage {
+    url: string;
+    rules_note: string | null;
+    source: string;
+}
+export declare function getDistrict(client: HttpClient, rawCode: string): Promise<Outcome<DistrictResult>>;
+export interface LotResult {
+    lot: LotRecord;
+    resolved_from: 'bbl' | 'address';
+    matched_address: string | null;
+    full_report_url: string;
+    district_pages: string[];
+    source: string;
+}
+export interface LotQuery {
+    bbl?: string;
+    address?: string;
+}
+export declare function lookupLot(client: HttpClient, q: LotQuery): Promise<Outcome<LotResult>>;

package/dist/service.js

@@ -0,0 +1,200 @@
+// Tool logic, free of MCP types so it can be tested directly with a fixture-backed client.
+// Each function returns { text, data } on success or { error } for a clear user-facing failure.
+import { UpstreamError } from './client.js';
+import { AddressNotFoundError, AmbiguousAddressError, resolveAddress } from './geocode.js';
+import { InputError, mapPlutoRow, parseBbl } from './lot.js';
+import { ParseError, parseDistrictPage, parseVintage, parseZoningIndex } from './parse.js';
+export const DISCLAIMER = 'Informational only; not legal, architectural, or zoning-compliance advice. Confirm with NYC Department of City Planning / a licensed professional before relying on it.';
+function reportedVintage(release, checkedOn) {
+    return `MapPLUTO release reported by NYRezone: ${release ?? 'unknown'}${checkedOn ? ` (site check stamp: ${checkedOn})` : ''}; not independently validated for this result`;
+}
+const fail = (error) => ({ ok: false, error });
+function upstreamMessage(err) {
+    if (err instanceof UpstreamError) {
+        switch (err.kind) {
+            case 'timeout': return `The data source timed out. Try again in a moment. (${err.message})`;
+            case 'rate_limited': return err.message;
+            case 'too_large': return 'The data source returned an unexpectedly large response, so it was rejected.';
+            case 'network': return 'Could not reach the data source (nyrezone.com or NYC Geosearch). Check connectivity and try again.';
+            case 'parse': return err.message;
+            default: return `The data source returned an error. ${err.message}`;
+        }
+    }
+    if (err instanceof ParseError)
+        return `NYRezone's page format looks different than expected, so nothing was returned rather than guessing. (${err.message})`;
+    if (err instanceof InputError)
+        return err.message;
+    return 'Unexpected error while fetching data.';
+}
+async function vintage(client) {
+    try {
+        const res = await client.getText(`${client.nyrezoneBase}/methodology`, 'text/html');
+        if (res.status === 200) {
+            const v = parseVintage(res.body);
+            return reportedVintage(v.release, v.checkedOn);
+        }
+    }
+    catch {
+        // Preserve the lookup, but explicitly report an unknown release when the source is unavailable.
+    }
+    return reportedVintage(null, null);
+}
+const districtUrl = (client, slug) => `${client.nyrezoneBase}/zoning/${slug}`;
+// ---------- districts ----------
+export async function loadIndex(client) {
+    const res = await client.getText(`${client.nyrezoneBase}/zoning`, 'text/html');
+    if (res.status !== 200)
+        throw new UpstreamError('http', `NYRezone zoning index returned HTTP ${res.status}.`, res.status);
+    return parseZoningIndex(res.body);
+}
+export async function listDistricts(client, family) {
+    try {
+        let wanted = null;
+        if (family !== undefined && family.trim() !== '') {
+            wanted = family.trim().toUpperCase();
+            if (!/^[A-Z][0-9]{0,2}$/.test(wanted))
+                return fail('family must be a district family like R6, C4, or M1.');
+        }
+        const index = await loadIndex(client);
+        const rows = index.filter((d) => wanted === null || d.family.toUpperCase() === wanted);
+        if (rows.length === 0) {
+            const families = [...new Set(index.map((d) => d.family))].join(', ');
+            return fail(`No districts in family "${wanted}". Available families: ${families}.`);
+        }
+        const districts = rows.map((d) => ({ code: d.code, family: d.family, summary: d.familyLabel, url: districtUrl(client, d.slug) }));
+        const source = `Source: NYRezone zoning index, ${client.nyrezoneBase}/zoning. ${DISCLAIMER}`;
+        const lines = districts.map((d) => `${d.code} - ${d.summary}`);
+        const text = `${districts.length} NYC zoning districts documented on NYRezone${wanted ? ` (family ${wanted})` : ''}. Summaries are the district family description; use get_zoning_district for a code's rules.\n\n${lines.join('\n')}\n\n${source}`;
+        return { ok: true, text, data: { count: districts.length, districts, source } };
+    }
+    catch (err) {
+        return fail(upstreamMessage(err));
+    }
+}
+export function normalizeCodeInput(code) {
+    const c = code.trim().toUpperCase().replace(/\s+/g, '').replace(/\//g, '-');
+    return /^[A-Z][A-Z0-9-]{0,14}$/.test(c) ? c : null;
+}
+export async function getDistrict(client, rawCode) {
+    try {
+        const norm = normalizeCodeInput(rawCode);
+        const index = await loadIndex(client);
+        const valid = () => index.map((d) => d.code).join(', ');
+        if (norm === null)
+            return fail(`"${rawCode.slice(0, 40)}" is not a valid district code. Valid codes: ${valid()}.`);
+        const entry = index.find((d) => d.slug === norm.toLowerCase());
+        if (!entry)
+            return fail(`Unknown zoning district "${norm}". NYRezone documents these ${index.length}: ${valid()}.`);
+        const url = districtUrl(client, entry.slug);
+        const res = await client.getText(url, 'text/html');
+        if (res.status === 404)
+            return fail(`NYRezone has no page for ${entry.code} right now.`);
+        const page = parseDistrictPage(res.body);
+        const rulesNote = page.rules.length === 0
+            ? 'NYRezone publishes parcel statistics but no bulk/height/setback rules table for this district; consult the Zoning Resolution.'
+            : null;
+        const vint = reportedVintage(page.dataVintage, page.dataCheckedOn);
+        const source = `Source: NYRezone HTML district summary, ${url}. ${vint}. Rule values are as published by NYRezone, not independently verified against the NYC Zoning Resolution. ${DISCLAIMER}`;
+        const out = [`${page.code} - ${page.summary}`, ''];
+        if (page.rules.length) {
+            out.push('Rules (as published by NYRezone):');
+            for (const r of page.rules)
+                out.push(`- ${r.rule}: ${r.value}${r.note ? ` - ${r.note}` : ''}`);
+        }
+        else {
+            out.push(rulesNote);
+        }
+        const statKeys = Object.keys(page.stats);
+        if (statKeys.length) {
+            out.push('', 'Citywide stats: ' + statKeys.map((k) => `${k} ${page.stats[k]}`).join('; '));
+        }
+        if (page.boroughs.length)
+            out.push('Lots by borough: ' + page.boroughs.map((b) => `${b.borough} ${b.parcels}`).join(', '));
+        out.push('', source);
+        return { ok: true, text: out.join('\n'), data: { ...page, url, rules_note: rulesNote, source } };
+    }
+    catch (err) {
+        return fail(upstreamMessage(err));
+    }
+}
+const fmt = (n, unit = '') => (n === null ? 'unknown' : `${n.toLocaleString('en-US')}${unit}`);
+export async function lookupLot(client, q) {
+    try {
+        const hasBbl = q.bbl !== undefined && q.bbl.trim() !== '';
+        const hasAddr = q.address !== undefined && q.address.trim() !== '';
+        if (hasBbl === hasAddr)
+            return fail('Provide exactly one of bbl (10-digit borough-block-lot) or address (street address with house number).');
+        let bbl;
+        let matched = null;
+        if (hasBbl) {
+            bbl = parseBbl(q.bbl);
+        }
+        else {
+            try {
+                const c = await resolveAddress(client, q.address);
+                bbl = c.bbl;
+                matched = c.label;
+            }
+            catch (err) {
+                if (err instanceof AmbiguousAddressError) {
+                    const list = err.candidates.map((c) => `${c.label} (BBL ${c.bbl})`).join('; ');
+                    return fail(`That address matches more than one tax lot, so no guess was made. Candidates: ${list}. Call again with the bbl you want.`);
+                }
+                if (err instanceof AddressNotFoundError) {
+                    return fail('No tax lot found for that address. Include the house number and street, and the borough (e.g. "1187 Ocean Ave, Brooklyn"), or pass a bbl.');
+                }
+                throw err;
+            }
+        }
+        const res = await client.getText(`${client.nyrezoneBase}/api/pluto?bbl=${encodeURIComponent(bbl)}`, 'application/json');
+        if (res.status === 404)
+            return fail(`No MapPLUTO record found for BBL ${bbl}. Check the borough, block and lot numbers.`);
+        let raw;
+        try {
+            raw = JSON.parse(res.body);
+        }
+        catch {
+            throw new UpstreamError('parse', 'Lot data came back in an unreadable format.');
+        }
+        // A 200 with an error body or an empty object must not render as a lot full of "unknown".
+        const rr = (typeof raw === 'object' && raw !== null ? raw : {});
+        const has = (k) => rr[k] !== undefined && rr[k] !== null && rr[k] !== '';
+        if (rr.error !== undefined || (!has('zonedist1') && !has('lotarea'))) {
+            return fail(`The data source returned no usable lot data for BBL ${bbl}.`);
+        }
+        const lot = mapPlutoRow(raw, bbl);
+        const vint = await vintage(client);
+        const reportUrl = `${client.nyrezoneBase}/map?bbl=${bbl}`;
+        // Only link district pages that exist; the index is a nicety, so its failure must not fail the lot.
+        let known = null;
+        try {
+            known = new Set((await loadIndex(client)).map((d) => d.slug));
+        }
+        catch {
+            known = null;
+        }
+        const slugs = lot.zoning_districts.map((z) => z.toLowerCase().replace(/\//g, '-')).filter((s) => known === null || known.has(s));
+        const pages = slugs.map((s) => districtUrl(client, s));
+        const source = `Source: NYRezone /api/pluto parcel records via ${client.nyrezoneBase}. ${vint}. District pages: ${pages.join(', ') || 'n/a'}. Public lot map: ${reportUrl}. ${DISCLAIMER}`;
+        const u = lot.unused_floor_area;
+        const lines = [
+            `BBL ${lot.bbl}${lot.address ? ` - ${lot.address}` : ''}${lot.borough ? `, ${lot.borough}` : ''}${lot.zip ? ` ${lot.zip}` : ''}`,
+            matched ? `Matched from your address to: ${matched}` : '',
+            `Zoning: ${lot.zoning_districts.join(' + ') || 'unknown'}${lot.split_zone ? ' (split-zoned lot)' : ''}${lot.commercial_overlays.length ? `; overlay ${lot.commercial_overlays.join(', ')}` : ''}${lot.special_districts.length ? `; special district ${lot.special_districts.join(', ')}` : ''}`,
+            lot.historic_district || lot.landmark ? `Historic: ${[lot.historic_district, lot.landmark].filter(Boolean).join('; ')}` : '',
+            `Land use: ${lot.land_use ? `${lot.land_use.code} ${lot.land_use.label}` : 'unknown'}${lot.building_class ? `; building class ${lot.building_class}` : ''}`,
+            `Lot area: ${fmt(lot.lot_area_sqft, ' sq ft')}; building area: ${fmt(lot.building_area_sqft, ' sq ft')}; floors: ${fmt(lot.num_floors)}; year built: ${lot.year_built ?? 'unknown'}; residential units: ${fmt(lot.residential_units)}`,
+            `Recorded MapPLUTO FAR - built: ${fmt(lot.built_far)}; residential: ${fmt(lot.max_far.residential)}; commercial: ${fmt(lot.max_far.commercial)}; community facility: ${fmt(lot.max_far.community_facility)}`,
+            `Unused floor area / development capacity: ${u.basis}.`,
+            `Caveat: ${u.caveats.join(' ')}`,
+            '',
+            source,
+        ];
+        // Optional lines are empty strings; drop them but keep the blank line before the source line.
+        const text = lines.filter((l, i) => l !== '' || i === lines.length - 2).join('\n');
+        return { ok: true, text, data: { lot, resolved_from: hasBbl ? 'bbl' : 'address', matched_address: matched, full_report_url: reportUrl, district_pages: pages, source } };
+    }
+    catch (err) {
+        return fail(upstreamMessage(err));
+    }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "nyrezone-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "NYRezone MCP - recorded NYC parcel and FAR fields plus NYRezone HTML district summaries",
+  "type": "module",
+  "bin": { "nyrezone-mcp": "./dist/cli.js" },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "files": ["dist", "!dist/test", "README.md", "LICENSE", "CHANGELOG.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "dev": "tsc -p tsconfig.json --watch",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.4.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.4.0",
+    "@types/node": "22.20.3",
+    "typescript": "7.0.2"
+  },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/gbrussich52/nyrezone-mcp.git" },
+  "homepage": "https://github.com/gbrussich52/nyrezone-mcp#readme",
+  "bugs": { "url": "https://github.com/gbrussich52/nyrezone-mcp/issues" },
+  "keywords": ["mcp", "model-context-protocol", "zoning", "nyc", "real-estate", "far", "mappluto", "ai-agent", "claude"],
+  "mcpName": "io.github.gbrussich52/nyrezone-mcp"
+}