nyrezone-mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 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 local build (not published).
+
+- 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,84 @@
-# 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 NYC zoning facts from the public data on [NYRezone](https://nyrezone.com): which zoning district a tax lot is in, built vs. allowed FAR, lot and building area, an estimated unused floor area, and the rules for each zoning district.
+
+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) | Zoning district(s), overlays and special districts, built FAR vs. maximum FAR, lot area, building area, estimated unused floor area, year built, land use. Ambiguous or unknown input returns an error, never a guess. |
+| `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 result ends with a source line (MapPLUTO release as stated by NYRezone, the matching nyrezone.com page, and for lots a `Full report` link) and a disclaimer.
+
+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: zoning R7A, lot area 4,675 sq ft, building area 2,606 sq ft, built FAR 0.56 against a 4.0 residential maximum, and an estimated 16,094 sq ft unused.
+
+## How the unused-floor-area estimate works
+
+`maximum FAR x lot area - existing building area`, using MapPLUTO's residential FAR (commercial or community-facility FAR if there is no residential FAR). It is a screening number only. It does not account for street width, special districts, overlays, split-zoned lots, mapped streets, or City of Yes / Universal Affordability Preference bonuses. If the building already exceeds the maximum, the tool reports 0 and says the lot is over-built.
+
+## Data sources and what leaves your machine
+
+- **nyrezone.com** (`/api/pluto`, `/zoning`, `/zoning/<code>`, `/methodology`): lot data and district pages. Data is NYC DCP MapPLUTO; the release is read from NYRezone's own methodology page.
+- **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.1.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.1.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,54 @@
+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 {
+    /** Estimated unused floor area in sq ft, or null when the inputs are missing. */
+    estimate_sqft: number | null;
+    /** True when existing building area already exceeds the FAR-based maximum. */
+    overbuilt: boolean;
+    allowed_floor_area_sqft: number | null;
+    governing_far: number | null;
+    basis: string;
+    caveats: string[];
+}
+export declare function computeUnusedFloorArea(lotArea: number | null, buildingArea: number | null, far: {
+    residential: number | null;
+    commercial: number | null;
+    community_facility: number | null;
+}, splitZone: boolean): UnusedFloorArea;
+/** 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,165 @@
+// 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;
+export function computeUnusedFloorArea(lotArea, buildingArea, far, splitZone) {
+    const caveats = [
+        'Simple MapPLUTO-based estimate: maximum FAR x lot area minus existing building area.',
+        'Building area is MapPLUTO gross area, which is larger than zoning floor area.',
+        'Ignores street width, special districts, overlays, lot splits, mapped streets, and City of Yes / Universal Affordability Preference bonuses, which can change the true maximum.',
+    ];
+    if (splitZone)
+        caveats.push('This lot spans more than one zoning district; MapPLUTO reports a single set of FAR values, so the estimate may be off.');
+    // Highest listed FAR governs: a commercial or community-facility FAR can exceed residential
+    // (e.g. C5-3 lists residential 10 but commercial 15), and using residential alone would
+    // wrongly flag such lots as overbuilt.
+    const candidates = [
+        ['residential', far.residential ?? 0],
+        ['commercial', far.commercial ?? 0],
+        ['community-facility', far.community_facility ?? 0],
+    ];
+    const top = Math.max(...candidates.map(([, v]) => v));
+    let governing = null;
+    let basis;
+    if (top > 0) {
+        governing = top;
+        const names = candidates.filter(([, v]) => v === top).map(([n]) => n).join(' / ');
+        basis = `Highest FAR MapPLUTO lists is ${top} (${names}).`;
+    }
+    else {
+        basis = 'MapPLUTO lists no maximum FAR for this lot, so no estimate is possible.';
+    }
+    if (governing === null || lotArea === null || lotArea <= 0 || buildingArea === null) {
+        if (governing !== null)
+            basis += ' Lot area or building area is missing, so no estimate is possible.';
+        return { estimate_sqft: null, overbuilt: false, allowed_floor_area_sqft: null, governing_far: governing, basis, caveats };
+    }
+    // Headline estimate uses residential FAR when listed (matches NYRezone's methodology); the
+    // overbuilt flag uses the highest FAR so community-facility or commercial uses never make a
+    // lot look non-compliant. Community-facility FAR alone must not inflate a residential lot's headroom.
+    const resid = far.residential ?? 0;
+    const estFar = resid > 0 ? resid : governing;
+    if (resid > 0 && resid < governing) {
+        basis = `Estimate uses residential FAR ${resid}; MapPLUTO also lists up to ${governing} for other uses (commercial / community-facility).`;
+    }
+    const allowed = estFar * lotArea;
+    const overbuilt = buildingArea > governing * lotArea;
+    return {
+        estimate_sqft: Math.max(0, Math.round(allowed - buildingArea)),
+        overbuilt,
+        allowed_floor_area_sqft: overbuilt ? Math.round(governing * lotArea) : Math.round(allowed),
+        governing_far: overbuilt ? governing : estFar,
+        basis,
+        caveats,
+    };
+}
+/** 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: computeUnusedFloorArea(lotArea, buildingArea, far, splitZone),
+    };
+}

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 (rules for one zoning code), list_zoning_districts.',
+    'Report only what the tools return and always keep the source line and disclaimer with it.',
+    'Unused floor area is a simplified FAR-based estimate, not a legal buildable-area determination; say so.',
+    '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.number().nullable(),
+        overbuilt: z.boolean(),
+        allowed_floor_area_sqft: z.number().nullable(),
+        governing_far: z.number().nullable(),
+        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 zoning district(s), built vs. allowed FAR, lot and building area, an estimated unused floor area, year built and land use, from MapPLUTO via NYRezone. 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(),
+            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 rules 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. Height/setback detail is only what NYRezone publishes for that district. 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,203 @@
+// 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.';
+const FALLBACK_VINTAGE = 'NYC MapPLUTO (release as stated at https://nyrezone.com/methodology)';
+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);
+            if (v.release)
+                return v.checkedOn ? `NYC ${v.release} (checked ${v.checkedOn})` : `NYC ${v.release}`;
+        }
+    }
+    catch {
+        // The vintage line is a nicety; never fail a lookup over it.
+    }
+    return FALLBACK_VINTAGE;
+}
+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 verified bulk/height/setback rules for this district; consult the Zoning Resolution.'
+            : null;
+        const vint = page.dataVintage ? `NYC ${page.dataVintage}${page.dataCheckedOn ? ` (checked ${page.dataCheckedOn})` : ''}` : FALLBACK_VINTAGE;
+        const source = `Source: ${vint} via NYRezone; rule values from the NYC Zoning Resolution as shown on ${url}. ${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: ${vint} via ${client.nyrezoneBase}. District pages: ${pages.join(', ') || 'n/a'}. Full report: ${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)}`,
+            `FAR - built: ${fmt(lot.built_far)}; max residential: ${fmt(lot.max_far.residential)}; max commercial: ${fmt(lot.max_far.commercial)}; max community facility: ${fmt(lot.max_far.community_facility)}`,
+            u.estimate_sqft === null
+                ? `Unused floor area: not estimable. ${u.basis}`
+                : u.overbuilt
+                    ? `Unused floor area: about 0 sq ft; existing gross building area (${fmt(lot.building_area_sqft)} sq ft) exceeds the highest FAR MapPLUTO lists (${u.governing_far} x lot area = ${fmt(u.allowed_floor_area_sqft)} sq ft). MapPLUTO building area is gross, not zoning floor area, so this is not evidence of non-compliance. ${u.basis}`
+                    : `Unused floor area (estimate): about ${fmt(u.estimate_sqft, ' sq ft')} of ${fmt(u.allowed_floor_area_sqft)} sq ft allowed. ${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.1.0",
+  "description": "NYRezone MCP - NYC zoning districts and tax-lot lookups (zoning, FAR, unused floor area) from public NYRezone / MapPLUTO data",
+  "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.0.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.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"
+}