@matchuplabs/nyc-api-mcp 0.1.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import * as capabilityGuide from "./resources/capability-guide.js";
+import * as inputFormatting from "./resources/input-formatting.js";
+import * as schemaExamples from "./resources/schema-examples.js";
+import * as coverageNotes from "./resources/coverage-notes.js";
+import * as creditPolicy from "./resources/credit-policy.js";
+import { TOOL_DEFINITION as resolvePropertyDef, TOOL_NAME as resolvePropertyName, resolvePropertyIdentifier, } from "./tools/resolve-property-identifier.js";
+import { TOOL_DEFINITION as propertyIntelDef, TOOL_NAME as propertyIntelName, getPropertyIntelligence, } from "./tools/get-property-intelligence.js";
+import { TOOL_DEFINITION as buildingViolationsDef, TOOL_NAME as buildingViolationsName, getBuildingViolations, } from "./tools/get-building-violations.js";
+import { TOOL_DEFINITION as restaurantVenueIntelDef, TOOL_NAME as restaurantVenueIntelName, getRestaurantVenueIntel, } from "./tools/get-restaurant-venue-intel.js";
+const server = new Server({ name: "nyc-api", version: "0.1.0" }, { capabilities: { tools: {}, resources: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [resolvePropertyDef, propertyIntelDef, buildingViolationsDef, restaurantVenueIntelDef],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case resolvePropertyName: {
+                const result = await resolvePropertyIdentifier((args ?? {}));
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            case propertyIntelName: {
+                const result = await getPropertyIntelligence((args ?? {}));
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            case buildingViolationsName: {
+                const result = await getBuildingViolations((args ?? {}));
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            case restaurantVenueIntelName: {
+                const result = await getRestaurantVenueIntel((args ?? {}));
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: {
+                                    code: "UNKNOWN_TOOL",
+                                    message: `Tool "${name}" is not implemented.`,
+                                    suggested_next_step: "Check available tools via tools/list.",
+                                },
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        console.error(`Unhandled error in tool "${name}":`, err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: {
+                            code: "UPSTREAM_TIMEOUT",
+                            message: `Unexpected server error: ${err instanceof Error ? err.message : String(err)}`,
+                            suggested_next_step: "Retry in a few seconds.",
+                        },
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+const RESOURCES = [
+    capabilityGuide,
+    inputFormatting,
+    schemaExamples,
+    coverageNotes,
+    creditPolicy,
+];
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: RESOURCES.map((r) => ({
+        uri: r.RESOURCE_URI,
+        name: r.RESOURCE_NAME,
+        description: r.RESOURCE_DESCRIPTION,
+        mimeType: r.RESOURCE_URI === "nyc-api://schema-examples" ? "application/json" : "text/plain",
+    })),
+}));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    const resource = RESOURCES.find((r) => r.RESOURCE_URI === uri);
+    if (!resource) {
+        throw new Error(`Resource not found: ${uri}`);
+    }
+    return {
+        contents: [
+            {
+                uri: resource.RESOURCE_URI,
+                mimeType: resource.RESOURCE_URI === "nyc-api://schema-examples" ? "application/json" : "text/plain",
+                text: resource.RESOURCE_CONTENT,
+            },
+        ],
+    };
+});
+async function main() {
+    if (!process.env.NYC_API_KEY) {
+        console.error("ERROR: NYC_API_KEY environment variable is not set. The server cannot function without it.");
+        console.error("Set it with: export NYC_API_KEY=your_api_key");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("NYC API MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/lib/auth.d.ts

@@ -0,0 +1,2 @@
+export declare function getApiKey(): string;
+export declare function validateApiKeyPresent(): boolean;

package/dist/lib/auth.js

@@ -0,0 +1,10 @@
+export function getApiKey() {
+    const key = process.env.NYC_API_KEY;
+    if (!key) {
+        throw new Error("NYC_API_KEY environment variable is required. Get one at https://nycapi.app");
+    }
+    return key;
+}
+export function validateApiKeyPresent() {
+    return typeof process.env.NYC_API_KEY === "string" && process.env.NYC_API_KEY.length > 0;
+}

package/dist/lib/errors.d.ts

@@ -0,0 +1,31 @@
+export interface McpError {
+    error: {
+        code: string;
+        message: string;
+        suggested_next_step: string;
+    };
+}
+export declare const ErrorCodes: {
+    readonly MISSING_REQUIRED_IDENTIFIER: "MISSING_REQUIRED_IDENTIFIER";
+    readonly AMBIGUOUS_ADDRESS: "AMBIGUOUS_ADDRESS";
+    readonly AMBIGUOUS_VENUE: "AMBIGUOUS_VENUE";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly UPSTREAM_TIMEOUT: "UPSTREAM_TIMEOUT";
+    readonly CREDIT_LIMIT_EXCEEDED: "CREDIT_LIMIT_EXCEEDED";
+    readonly INVALID_API_KEY: "INVALID_API_KEY";
+    readonly UNSUPPORTED_BOROUGH_FORMAT: "UNSUPPORTED_BOROUGH_FORMAT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+export declare function mcpError(code: ErrorCode, message?: string): McpError;
+/**
+ * Map an API error (from NycApiClient) to a structured MCP error.
+ * Handles HTTP status codes and known error code strings.
+ */
+export declare function mapApiErrorToMcp(apiError: {
+    error: {
+        code: string;
+        message: string;
+        status: number;
+    };
+}): McpError;

package/dist/lib/errors.js

@@ -0,0 +1,65 @@
+export const ErrorCodes = {
+    MISSING_REQUIRED_IDENTIFIER: "MISSING_REQUIRED_IDENTIFIER",
+    AMBIGUOUS_ADDRESS: "AMBIGUOUS_ADDRESS",
+    AMBIGUOUS_VENUE: "AMBIGUOUS_VENUE",
+    NOT_FOUND: "NOT_FOUND",
+    UPSTREAM_TIMEOUT: "UPSTREAM_TIMEOUT",
+    CREDIT_LIMIT_EXCEEDED: "CREDIT_LIMIT_EXCEEDED",
+    INVALID_API_KEY: "INVALID_API_KEY",
+    UNSUPPORTED_BOROUGH_FORMAT: "UNSUPPORTED_BOROUGH_FORMAT",
+    RATE_LIMITED: "RATE_LIMITED",
+};
+const defaultSuggestions = {
+    MISSING_REQUIRED_IDENTIFIER: "Provide at least one identifier: address, BBL, or BIN.",
+    AMBIGUOUS_ADDRESS: "Add borough or zipcode to narrow the match.",
+    AMBIGUOUS_VENUE: "Add zipcode or CAMIS ID to narrow the match.",
+    NOT_FOUND: "Use resolve_property_identifier to verify the address or identifier.",
+    UPSTREAM_TIMEOUT: "Retry in a few seconds.",
+    CREDIT_LIMIT_EXCEEDED: "Purchase more credits at nycapi.app.",
+    INVALID_API_KEY: "Check your NYC_API_KEY environment variable.",
+    UNSUPPORTED_BOROUGH_FORMAT: "Use full borough name (e.g., 'Manhattan') or borough code (1-5).",
+    RATE_LIMITED: "Wait and retry.",
+};
+export function mcpError(code, message) {
+    return {
+        error: {
+            code,
+            message: message || code,
+            suggested_next_step: defaultSuggestions[code],
+        },
+    };
+}
+/**
+ * Map an API error (from NycApiClient) to a structured MCP error.
+ * Handles HTTP status codes and known error code strings.
+ */
+export function mapApiErrorToMcp(apiError) {
+    const { code, message, status } = apiError.error;
+    // Map by HTTP status first, then by error code string
+    if (status === 401 || code === "missing_api_key" || code === "invalid_api_key" || code === "INVALID_API_KEY") {
+        return mcpError(ErrorCodes.INVALID_API_KEY, message);
+    }
+    if (status === 402 || code === "credits_exhausted" || code === "CREDIT_LIMIT_EXCEEDED") {
+        return mcpError(ErrorCodes.CREDIT_LIMIT_EXCEEDED, message);
+    }
+    if (status === 429 || code === "rate_limit_exceeded" || code === "RATE_LIMITED") {
+        return mcpError(ErrorCodes.RATE_LIMITED, message);
+    }
+    if (status === 404 || code === "not_found" || code === "NOT_FOUND") {
+        return mcpError(ErrorCodes.NOT_FOUND, message);
+    }
+    if (status === 400) {
+        if (code === "invalid_input" || code === "MISSING_REQUIRED_IDENTIFIER") {
+            return mcpError(ErrorCodes.MISSING_REQUIRED_IDENTIFIER, message);
+        }
+        if (code === "unsupported_borough" || code === "UNSUPPORTED_BOROUGH_FORMAT") {
+            return mcpError(ErrorCodes.UNSUPPORTED_BOROUGH_FORMAT, message);
+        }
+        return mcpError(ErrorCodes.MISSING_REQUIRED_IDENTIFIER, message);
+    }
+    if (status >= 500 || status === 0 || code === "UPSTREAM_TIMEOUT" || code === "UPSTREAM_ERROR" || code === "upstream_error") {
+        return mcpError(ErrorCodes.UPSTREAM_TIMEOUT, message);
+    }
+    // Fallback
+    return mcpError(ErrorCodes.UPSTREAM_TIMEOUT, message);
+}

package/dist/lib/nyc-api-client.d.ts

@@ -0,0 +1,75 @@
+export declare class NycApiClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl?: string, apiKey?: string);
+    private request;
+    propertyLookup(params: {
+        address?: string;
+        bbl?: string;
+        borough?: string;
+        block?: string;
+        lot?: string;
+    }): Promise<unknown>;
+    propertySearch(params: {
+        address?: string;
+        owner?: string;
+        borough?: string;
+        zipcode?: string;
+        building_class?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    venueHealth(params: {
+        name?: string;
+        address?: string;
+        zipcode?: string;
+        borough?: string;
+        camis?: string;
+    }): Promise<unknown>;
+    venueSearch(params: {
+        cuisine?: string;
+        grade?: string;
+        borough?: string;
+        zipcode?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    venuePermits(params: {
+        name?: string;
+        address?: string;
+        zipcode?: string;
+    }): Promise<unknown>;
+    violationsProfile(params: {
+        address: string;
+        borough?: string;
+        zipcode?: string;
+        block?: string;
+        lot?: string;
+    }): Promise<unknown>;
+    violationsDob(params: {
+        address?: string;
+        block?: string;
+        lot?: string;
+        borough?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    violationsHpd(params: {
+        address?: string;
+        block?: string;
+        lot?: string;
+        borough?: string;
+        zipcode?: string;
+        class?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    violationsComplaints(params: {
+        address: string;
+        borough?: string;
+        zipcode?: string;
+        complaint_type?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+}

package/dist/lib/nyc-api-client.js

@@ -0,0 +1,109 @@
+export class NycApiClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl || process.env.NYC_API_BASE_URL || "https://nycapi.app";
+        this.apiKey = apiKey || process.env.NYC_API_KEY || "";
+    }
+    async request(path, params) {
+        const url = new URL(path, this.baseUrl);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        let response;
+        try {
+            response = await fetch(url.toString(), {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                },
+            });
+        }
+        catch (err) {
+            return {
+                error: {
+                    code: "UPSTREAM_TIMEOUT",
+                    message: `Request to NYC API failed: ${err instanceof Error ? err.message : String(err)}`,
+                    status: 0,
+                },
+            };
+        }
+        if (!response.ok) {
+            let body;
+            try {
+                body = await response.text();
+            }
+            catch {
+                body = "";
+            }
+            // Try to extract structured error code from JSON body
+            let errorCode = "UPSTREAM_ERROR";
+            let errorMessage = `NYC API returned ${response.status}: ${body}`;
+            try {
+                const parsed = JSON.parse(body);
+                if (parsed?.error?.code)
+                    errorCode = parsed.error.code;
+                if (parsed?.error?.message)
+                    errorMessage = parsed.error.message;
+            }
+            catch {
+                // Not JSON — use status-based mapping
+            }
+            const statusCodeMap = {
+                400: "invalid_input",
+                401: "invalid_api_key",
+                402: "credits_exhausted",
+                404: "not_found",
+                429: "rate_limit_exceeded",
+                500: "upstream_error",
+                502: "upstream_error",
+                503: "upstream_error",
+            };
+            // Prefer parsed error code, fall back to status-based code
+            if (errorCode === "UPSTREAM_ERROR" && statusCodeMap[response.status]) {
+                errorCode = statusCodeMap[response.status];
+            }
+            return {
+                error: {
+                    code: errorCode,
+                    message: errorMessage,
+                    status: response.status,
+                },
+            };
+        }
+        return response.json();
+    }
+    // --- Property Intelligence ---
+    async propertyLookup(params) {
+        return this.request("/api/property/lookup", params);
+    }
+    async propertySearch(params) {
+        return this.request("/api/property/search", params);
+    }
+    // --- Restaurant & Venue Intel ---
+    async venueHealth(params) {
+        return this.request("/api/venue/health", params);
+    }
+    async venueSearch(params) {
+        return this.request("/api/venue/search", params);
+    }
+    async venuePermits(params) {
+        return this.request("/api/venue/permits", params);
+    }
+    // --- Building Violations ---
+    async violationsProfile(params) {
+        return this.request("/api/violations/profile", params);
+    }
+    async violationsDob(params) {
+        return this.request("/api/violations/dob", params);
+    }
+    async violationsHpd(params) {
+        return this.request("/api/violations/hpd", params);
+    }
+    async violationsComplaints(params) {
+        return this.request("/api/violations/complaints", params);
+    }
+}

package/dist/lib/usage.d.ts

@@ -0,0 +1,11 @@
+export declare enum UsageClass {
+    Resolver = "resolver",
+    SummaryLookup = "summary_lookup",
+    DetailLookup = "detail_lookup",
+    Estimate = "estimate"
+}
+export interface UsageEntry {
+    tool: string;
+    usageClass: UsageClass;
+    timestamp: Date;
+}

package/dist/lib/usage.js

@@ -0,0 +1,7 @@
+export var UsageClass;
+(function (UsageClass) {
+    UsageClass["Resolver"] = "resolver";
+    UsageClass["SummaryLookup"] = "summary_lookup";
+    UsageClass["DetailLookup"] = "detail_lookup";
+    UsageClass["Estimate"] = "estimate";
+})(UsageClass || (UsageClass = {}));

package/dist/resources/capability-guide.d.ts

@@ -0,0 +1,4 @@
+export declare const RESOURCE_URI = "nyc-api://capability-guide";
+export declare const RESOURCE_NAME = "NYC API Capability Guide";
+export declare const RESOURCE_DESCRIPTION = "Explains what each tool does, when to use it, and the recommended decision tree for NYC property/building/venue questions.";
+export declare const RESOURCE_CONTENT = "# NYC API MCP \u2014 Capability Guide\n\n## Tools Overview\n\n### 1. resolve_property_identifier\n**What it does:** Normalizes and validates a NYC property identifier. Accepts a partial address, BBL, or BIN and returns the normalized address, BBL, BIN, borough, and a confidence score.\n**When to use:** ALWAYS call this first before using get_property_intelligence or get_building_violations. It ensures you have the correct, unambiguous property. Returns multiple candidates if the input is ambiguous.\n**Cost:** Free or near-free \u2014 always resolve first.\n\n### 2. get_property_intelligence\n**What it does:** Returns ownership, sales history, liens, assessed value, rent stabilization status, zoning, and lot details for a NYC property.\n**When to use:** When the user asks about property ownership, value, sales, liens, zoning, or rent stabilization. Requires a BBL (get one from resolve_property_identifier first).\n**Cost:** 1 credit per call.\n\n### 3. get_building_violations\n**What it does:** Returns DOB and HPD violations, ECB penalties, complaints, and open permits for a building.\n**When to use:** When the user asks about building violations, complaints, permits, safety issues, or code enforcement. Requires a BIN or BBL.\n**Cost:** 1 credit per call.\n\n### 4. get_restaurant_venue_intel\n**What it does:** Returns health inspection grades, liquor license status, sidewalk cafe permits, and 311 complaints for a restaurant or venue.\n**When to use:** When the user asks about restaurant health grades, liquor licenses, venue permits, or food-related complaints. Accepts a name and/or address.\n**Cost:** 1 credit per call.\n\n## Decision Tree\n\n1. **Resolve first.** Always call resolve_property_identifier to normalize the address or identifier before any lookup.\n2. **Check confidence.** If confidence < 0.8 or multiple candidates are returned, ask the user to clarify.\n3. **Choose the right lookup:**\n   - Property ownership, value, zoning, liens \u2192 get_property_intelligence\n   - Building violations, permits, complaints \u2192 get_building_violations\n   - Restaurant/venue health, liquor, permits \u2192 get_restaurant_venue_intel\n4. **Combine when needed.** You can call multiple lookup tools for the same property if the question spans domains (e.g., \"Tell me everything about 100 Broadway\").\n\n## Which Tool for Which Question?\n\n| Question type | Tool |\n|---|---|\n| Who owns this property? | get_property_intelligence |\n| What is this property worth? | get_property_intelligence |\n| Is this apartment rent stabilized? | get_property_intelligence |\n| Are there open violations? | get_building_violations |\n| Any DOB or HPD complaints? | get_building_violations |\n| What is the restaurant health grade? | get_restaurant_venue_intel |\n| Does this bar have a liquor license? | get_restaurant_venue_intel |\n| What's the BBL for this address? | resolve_property_identifier |\n";

package/dist/resources/capability-guide.js

@@ -0,0 +1,50 @@
+export const RESOURCE_URI = "nyc-api://capability-guide";
+export const RESOURCE_NAME = "NYC API Capability Guide";
+export const RESOURCE_DESCRIPTION = "Explains what each tool does, when to use it, and the recommended decision tree for NYC property/building/venue questions.";
+export const RESOURCE_CONTENT = `# NYC API MCP — Capability Guide
+
+## Tools Overview
+
+### 1. resolve_property_identifier
+**What it does:** Normalizes and validates a NYC property identifier. Accepts a partial address, BBL, or BIN and returns the normalized address, BBL, BIN, borough, and a confidence score.
+**When to use:** ALWAYS call this first before using get_property_intelligence or get_building_violations. It ensures you have the correct, unambiguous property. Returns multiple candidates if the input is ambiguous.
+**Cost:** Free or near-free — always resolve first.
+
+### 2. get_property_intelligence
+**What it does:** Returns ownership, sales history, liens, assessed value, rent stabilization status, zoning, and lot details for a NYC property.
+**When to use:** When the user asks about property ownership, value, sales, liens, zoning, or rent stabilization. Requires a BBL (get one from resolve_property_identifier first).
+**Cost:** 1 credit per call.
+
+### 3. get_building_violations
+**What it does:** Returns DOB and HPD violations, ECB penalties, complaints, and open permits for a building.
+**When to use:** When the user asks about building violations, complaints, permits, safety issues, or code enforcement. Requires a BIN or BBL.
+**Cost:** 1 credit per call.
+
+### 4. get_restaurant_venue_intel
+**What it does:** Returns health inspection grades, liquor license status, sidewalk cafe permits, and 311 complaints for a restaurant or venue.
+**When to use:** When the user asks about restaurant health grades, liquor licenses, venue permits, or food-related complaints. Accepts a name and/or address.
+**Cost:** 1 credit per call.
+
+## Decision Tree
+
+1. **Resolve first.** Always call resolve_property_identifier to normalize the address or identifier before any lookup.
+2. **Check confidence.** If confidence < 0.8 or multiple candidates are returned, ask the user to clarify.
+3. **Choose the right lookup:**
+   - Property ownership, value, zoning, liens → get_property_intelligence
+   - Building violations, permits, complaints → get_building_violations
+   - Restaurant/venue health, liquor, permits → get_restaurant_venue_intel
+4. **Combine when needed.** You can call multiple lookup tools for the same property if the question spans domains (e.g., "Tell me everything about 100 Broadway").
+
+## Which Tool for Which Question?
+
+| Question type | Tool |
+|---|---|
+| Who owns this property? | get_property_intelligence |
+| What is this property worth? | get_property_intelligence |
+| Is this apartment rent stabilized? | get_property_intelligence |
+| Are there open violations? | get_building_violations |
+| Any DOB or HPD complaints? | get_building_violations |
+| What is the restaurant health grade? | get_restaurant_venue_intel |
+| Does this bar have a liquor license? | get_restaurant_venue_intel |
+| What's the BBL for this address? | resolve_property_identifier |
+`;

package/dist/resources/coverage-notes.d.ts

@@ -0,0 +1,4 @@
+export declare const RESOURCE_URI = "nyc-api://coverage-notes";
+export declare const RESOURCE_NAME = "NYC API Data Coverage Notes";
+export declare const RESOURCE_DESCRIPTION = "Explains data sources, what each covers, refresh cycles, and limitations including rent stabilization caveats.";
+export declare const RESOURCE_CONTENT = "# NYC API MCP \u2014 Data Coverage Notes\n\n## Data Sources\n\n### PLUTO (Primary Land Use Tax Lot Output)\n- **Covers:** Lot-level data \u2014 zoning, building class, lot area, built year, assessed value, number of units, owner name.\n- **Refresh:** Released roughly every 6 months by NYC DCP. Cached copies may lag by up to a month after release.\n- **Limitations:** Owner name is from tax records and may show LLCs or trusts rather than beneficial owners.\n\n### ACRIS (Automated City Register Information System)\n- **Covers:** Recorded property documents \u2014 deeds, mortgages, liens, satisfactions, UCC filings.\n- **Refresh:** Near real-time for newly recorded documents (1-3 business day lag). Historical records go back to 1966 for Manhattan, 1983 for other boroughs.\n- **Limitations:** Does not cover Staten Island (which uses a separate recording system). Document text is often scanned images, not structured data.\n\n### DOB (Department of Buildings)\n- **Covers:** Building permits, violations, complaints, certificates of occupancy, elevator inspections.\n- **Refresh:** Daily updates via NYC Open Data. Active permits and violations update within 24 hours.\n- **Limitations:** Some older violations may have incomplete descriptions. DOB NOW BIS data may differ slightly from legacy BIS data during transition.\n\n### HPD (Housing Preservation & Development)\n- **Covers:** Housing code violations, complaints, registrations, litigation, emergency repair program.\n- **Refresh:** Daily updates via NYC Open Data.\n- **Limitations:** Only covers residential properties. Does not include commercial-only buildings.\n\n### DOH (Department of Health)\n- **Covers:** Restaurant inspection results, grades (A/B/C), violation codes, closure orders.\n- **Refresh:** Updated regularly via NYC Open Data, typically within a week of an inspection.\n- **Limitations:** Grades may not reflect the very latest inspection if results are pending adjudication. Letter grade posting follows a specific cycle after initial/re-inspection.\n\n### DCA / DCWP (Department of Consumer and Worker Protection)\n- **Covers:** Business licenses, sidewalk cafe permits, newsstand permits.\n- **Refresh:** Updated periodically via NYC Open Data.\n- **Limitations:** Not all business types require DCA licenses. Coverage may not include newer permit categories.\n\n### 311\n- **Covers:** Complaint records for noise, illegal conversion, building conditions, rodents, street conditions, and more.\n- **Refresh:** Daily updates. Complaints are logged immediately but resolution may take weeks.\n- **Limitations:** Complaint data reflects what was reported, not necessarily verified conditions. High-volume complaint types (noise) may have duplicates.\n\n## Rent Stabilization Status\n\nRent stabilization data comes from DHCR (Division of Housing and Community Renewal) registration records and property tax records (RPAD/DOF).\n\n**What it means:** If a property is flagged as rent-stabilized, it has units subject to rent regulation \u2014 meaning rents, lease renewals, and eviction are governed by the Rent Stabilization Code.\n\n**Limitations:**\n- The most reliable public indicator is whether the property reports stabilized units in its annual tax filings (RPAD). This can lag by a year.\n- Individual apartment stabilization status cannot be determined from public bulk data alone \u2014 only building-level counts.\n- Properties may have a mix of stabilized and market-rate units.\n- DHCR does not provide a public API; building-level registration lists require FOIL requests.\n- De-regulation (when a unit leaves stabilization via high-rent vacancy or luxury decontrol) is not always reflected promptly.\n\n**Best practice:** Use the stabilization flag as a strong indicator, but advise users that individual unit status requires a DHCR rent history request.\n\n## General Freshness Expectations\n\n| Source | Typical refresh | Lag |\n|---|---|---|\n| DOB violations/permits | Daily | < 24 hours |\n| HPD violations/complaints | Daily | < 24 hours |\n| DOH restaurant inspections | Weekly | 1-7 days |\n| ACRIS documents | Near real-time | 1-3 business days |\n| PLUTO | Semi-annually | Up to 1 month after release |\n| 311 complaints | Daily | < 24 hours |\n| DCA/DCWP licenses | Periodic | 1-2 weeks |\n";

package/dist/resources/coverage-notes.js

@@ -0,0 +1,69 @@
+export const RESOURCE_URI = "nyc-api://coverage-notes";
+export const RESOURCE_NAME = "NYC API Data Coverage Notes";
+export const RESOURCE_DESCRIPTION = "Explains data sources, what each covers, refresh cycles, and limitations including rent stabilization caveats.";
+export const RESOURCE_CONTENT = `# NYC API MCP — Data Coverage Notes
+
+## Data Sources
+
+### PLUTO (Primary Land Use Tax Lot Output)
+- **Covers:** Lot-level data — zoning, building class, lot area, built year, assessed value, number of units, owner name.
+- **Refresh:** Released roughly every 6 months by NYC DCP. Cached copies may lag by up to a month after release.
+- **Limitations:** Owner name is from tax records and may show LLCs or trusts rather than beneficial owners.
+
+### ACRIS (Automated City Register Information System)
+- **Covers:** Recorded property documents — deeds, mortgages, liens, satisfactions, UCC filings.
+- **Refresh:** Near real-time for newly recorded documents (1-3 business day lag). Historical records go back to 1966 for Manhattan, 1983 for other boroughs.
+- **Limitations:** Does not cover Staten Island (which uses a separate recording system). Document text is often scanned images, not structured data.
+
+### DOB (Department of Buildings)
+- **Covers:** Building permits, violations, complaints, certificates of occupancy, elevator inspections.
+- **Refresh:** Daily updates via NYC Open Data. Active permits and violations update within 24 hours.
+- **Limitations:** Some older violations may have incomplete descriptions. DOB NOW BIS data may differ slightly from legacy BIS data during transition.
+
+### HPD (Housing Preservation & Development)
+- **Covers:** Housing code violations, complaints, registrations, litigation, emergency repair program.
+- **Refresh:** Daily updates via NYC Open Data.
+- **Limitations:** Only covers residential properties. Does not include commercial-only buildings.
+
+### DOH (Department of Health)
+- **Covers:** Restaurant inspection results, grades (A/B/C), violation codes, closure orders.
+- **Refresh:** Updated regularly via NYC Open Data, typically within a week of an inspection.
+- **Limitations:** Grades may not reflect the very latest inspection if results are pending adjudication. Letter grade posting follows a specific cycle after initial/re-inspection.
+
+### DCA / DCWP (Department of Consumer and Worker Protection)
+- **Covers:** Business licenses, sidewalk cafe permits, newsstand permits.
+- **Refresh:** Updated periodically via NYC Open Data.
+- **Limitations:** Not all business types require DCA licenses. Coverage may not include newer permit categories.
+
+### 311
+- **Covers:** Complaint records for noise, illegal conversion, building conditions, rodents, street conditions, and more.
+- **Refresh:** Daily updates. Complaints are logged immediately but resolution may take weeks.
+- **Limitations:** Complaint data reflects what was reported, not necessarily verified conditions. High-volume complaint types (noise) may have duplicates.
+
+## Rent Stabilization Status
+
+Rent stabilization data comes from DHCR (Division of Housing and Community Renewal) registration records and property tax records (RPAD/DOF).
+
+**What it means:** If a property is flagged as rent-stabilized, it has units subject to rent regulation — meaning rents, lease renewals, and eviction are governed by the Rent Stabilization Code.
+
+**Limitations:**
+- The most reliable public indicator is whether the property reports stabilized units in its annual tax filings (RPAD). This can lag by a year.
+- Individual apartment stabilization status cannot be determined from public bulk data alone — only building-level counts.
+- Properties may have a mix of stabilized and market-rate units.
+- DHCR does not provide a public API; building-level registration lists require FOIL requests.
+- De-regulation (when a unit leaves stabilization via high-rent vacancy or luxury decontrol) is not always reflected promptly.
+
+**Best practice:** Use the stabilization flag as a strong indicator, but advise users that individual unit status requires a DHCR rent history request.
+
+## General Freshness Expectations
+
+| Source | Typical refresh | Lag |
+|---|---|---|
+| DOB violations/permits | Daily | < 24 hours |
+| HPD violations/complaints | Daily | < 24 hours |
+| DOH restaurant inspections | Weekly | 1-7 days |
+| ACRIS documents | Near real-time | 1-3 business days |
+| PLUTO | Semi-annually | Up to 1 month after release |
+| 311 complaints | Daily | < 24 hours |
+| DCA/DCWP licenses | Periodic | 1-2 weeks |
+`;

package/dist/resources/credit-policy.d.ts

@@ -0,0 +1,4 @@
+export declare const RESOURCE_URI = "nyc-api://credit-policy";
+export declare const RESOURCE_NAME = "NYC API Credit & Usage Policy";
+export declare const RESOURCE_DESCRIPTION = "Explains credit costs per tool, detail flags, and best practices to minimize usage.";
+export declare const RESOURCE_CONTENT = "# NYC API MCP \u2014 Credit & Usage Policy\n\n## Credit Costs\n\n| Tool | Cost |\n|---|---|\n| resolve_property_identifier | Free (or near-free) |\n| get_property_intelligence | 1 credit per call |\n| get_building_violations | 1 credit per call |\n| get_restaurant_venue_intel | 1 credit per call |\n\n## Detail Flags\n\nSeveral lookup tools accept optional \"detail\" flags to control which data sections are returned (e.g., ownership, sales, violations). **Detail flags do not cost extra credits.** Whether you request one detail section or all of them, the call costs the same 1 credit.\n\nUse detail flags to get exactly the data you need \u2014 not to save credits, but to get a more focused, faster response.\n\n## Best Practices\n\n1. **Resolve first.** Always call resolve_property_identifier before a lookup tool. It is free and prevents wasted credits on bad identifiers.\n\n2. **Use summary mode.** When a tool offers a summary mode or default response, use it unless the user explicitly needs full detail. Summaries are faster and easier to work with.\n\n3. **Avoid duplicate calls.** If you already have results from a lookup tool for a given property, do not call it again for the same property in the same conversation \u2014 reuse the earlier response.\n\n4. **Combine questions.** If the user asks about ownership AND violations for the same property, call get_property_intelligence and get_building_violations in parallel \u2014 but only once each.\n\n5. **Check confidence before proceeding.** If resolve_property_identifier returns confidence < 0.8 or multiple candidates, ask the user to clarify before spending credits on a lookup.\n\n6. **Cache across turns.** If the user asks follow-up questions about the same property, reuse the data you already retrieved rather than making new API calls.\n\n## Summary\n\n- Resolver: always call first, always free.\n- Lookups: 1 credit each, detail flags are free.\n- Do not repeat calls. Resolve \u2192 confirm \u2192 lookup \u2192 reuse.\n";

package/dist/resources/credit-policy.js

@@ -0,0 +1,40 @@
+export const RESOURCE_URI = "nyc-api://credit-policy";
+export const RESOURCE_NAME = "NYC API Credit & Usage Policy";
+export const RESOURCE_DESCRIPTION = "Explains credit costs per tool, detail flags, and best practices to minimize usage.";
+export const RESOURCE_CONTENT = `# NYC API MCP — Credit & Usage Policy
+
+## Credit Costs
+
+| Tool | Cost |
+|---|---|
+| resolve_property_identifier | Free (or near-free) |
+| get_property_intelligence | 1 credit per call |
+| get_building_violations | 1 credit per call |
+| get_restaurant_venue_intel | 1 credit per call |
+
+## Detail Flags
+
+Several lookup tools accept optional "detail" flags to control which data sections are returned (e.g., ownership, sales, violations). **Detail flags do not cost extra credits.** Whether you request one detail section or all of them, the call costs the same 1 credit.
+
+Use detail flags to get exactly the data you need — not to save credits, but to get a more focused, faster response.
+
+## Best Practices
+
+1. **Resolve first.** Always call resolve_property_identifier before a lookup tool. It is free and prevents wasted credits on bad identifiers.
+
+2. **Use summary mode.** When a tool offers a summary mode or default response, use it unless the user explicitly needs full detail. Summaries are faster and easier to work with.
+
+3. **Avoid duplicate calls.** If you already have results from a lookup tool for a given property, do not call it again for the same property in the same conversation — reuse the earlier response.
+
+4. **Combine questions.** If the user asks about ownership AND violations for the same property, call get_property_intelligence and get_building_violations in parallel — but only once each.
+
+5. **Check confidence before proceeding.** If resolve_property_identifier returns confidence < 0.8 or multiple candidates, ask the user to clarify before spending credits on a lookup.
+
+6. **Cache across turns.** If the user asks follow-up questions about the same property, reuse the data you already retrieved rather than making new API calls.
+
+## Summary
+
+- Resolver: always call first, always free.
+- Lookups: 1 credit each, detail flags are free.
+- Do not repeat calls. Resolve → confirm → lookup → reuse.
+`;

package/dist/resources/input-formatting.d.ts

@@ -0,0 +1,4 @@
+export declare const RESOURCE_URI = "nyc-api://input-formatting";
+export declare const RESOURCE_NAME = "NYC API Input Formatting Guide";
+export declare const RESOURCE_DESCRIPTION = "Explains NYC address formats, BBL/BIN identifiers, and borough values accepted by the tools.";
+export declare const RESOURCE_CONTENT = "# NYC API MCP \u2014 Input Formatting Guide\n\n## Address Format\nNYC addresses follow the pattern: HOUSE_NUMBER STREET_NAME\n\nExamples:\n- 100 BROADWAY\n- 350 FIFTH AVE\n- 1 CENTRE ST\n- 233 BROADWAY\n- 42-10 QUEENS BLVD (hyphenated house numbers are common in Queens)\n\nTips:\n- Street suffixes can be abbreviated (AVE, ST, BLVD, PL, DR) or spelled out.\n- Include the borough if the street name is not unique (e.g., \"100 BROADWAY, MANHATTAN\").\n- The resolver handles common misspellings and abbreviations.\n\n## BBL Format (Borough-Block-Lot)\nA 10-digit string that uniquely identifies a tax lot in NYC.\n\nStructure: B BBBBB LLLL\n- B (1 digit): Borough number\n- BBBBB (5 digits): Block number (zero-padded)\n- LLLL (4 digits): Lot number (zero-padded)\n\nBorough numbers:\n- 1 = Manhattan\n- 2 = Bronx\n- 3 = Brooklyn\n- 4 = Queens\n- 5 = Staten Island\n\nExamples:\n- 1000670001 \u2192 Manhattan, Block 00067, Lot 0001\n- 3012340056 \u2192 Brooklyn, Block 01234, Lot 0056\n- 4004561234 \u2192 Queens, Block 00456, Lot 1234\n\n## BIN Format (Building Identification Number)\nA 7-digit number that uniquely identifies a building in NYC.\n\nStructure: B NNNNNN\n- First digit is the borough number (same as BBL).\n- Remaining 6 digits identify the specific building.\n\nExamples:\n- 1001389 \u2192 a building in Manhattan\n- 3345678 \u2192 a building in Brooklyn\n\nNote: A single BBL (tax lot) can have multiple BINs (buildings), but each BIN belongs to exactly one BBL.\n\n## Borough Values\nThe tools accept borough names or abbreviations:\n\n| Full name | Abbreviation | Borough number |\n|---|---|---|\n| Manhattan | MN | 1 |\n| Bronx | BX | 2 |\n| Brooklyn | BK | 3 |\n| Queens | QN | 4 |\n| Staten Island | SI | 5 |\n\nBoth full names and abbreviations are case-insensitive.\n";