@matchuplabs/nyc-api-mcp 0.1.0

package/dist/resources/input-formatting.js

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

package/dist/resources/schema-examples.d.ts

@@ -0,0 +1,4 @@
+export declare const RESOURCE_URI = "nyc-api://schema-examples";
+export declare const RESOURCE_NAME = "NYC API Schema & Examples";
+export declare const RESOURCE_DESCRIPTION = "JSON input/output examples for each tool, including both success and error responses.";
+export declare const RESOURCE_CONTENT: string;

package/dist/resources/schema-examples.js

@@ -0,0 +1,121 @@
+export const RESOURCE_URI = "nyc-api://schema-examples";
+export const RESOURCE_NAME = "NYC API Schema & Examples";
+export const RESOURCE_DESCRIPTION = "JSON input/output examples for each tool, including both success and error responses.";
+export const RESOURCE_CONTENT = JSON.stringify({
+    resolve_property_identifier: {
+        description: "Normalize and validate a NYC property identifier.",
+        example_input: { address: "350 fifth ave" },
+        example_success_response: {
+            candidates: [
+                {
+                    address: "350 FIFTH AVE",
+                    borough: "MANHATTAN",
+                    bbl: "1008350001",
+                    bin: "1015000",
+                    confidence: 0.97,
+                },
+            ],
+            resolved: true,
+        },
+        example_error_response: {
+            error: {
+                code: "NO_MATCH",
+                message: "No properties matched the input. Check the address or try a BBL/BIN instead.",
+                suggested_next_step: "Verify the address spelling and include the borough.",
+            },
+        },
+    },
+    get_property_intelligence: {
+        description: "Returns ownership, sales, liens, zoning, and rent stabilization for a property.",
+        example_input: { bbl: "1008350001", detail: ["ownership", "sales"] },
+        example_success_response: {
+            property: {
+                bbl: "1008350001",
+                address: "350 FIFTH AVE",
+                borough: "MANHATTAN",
+                ownership: {
+                    owner_name: "EMPIRE STATE BUILDING ASSOCIATES L.L.C.",
+                    owner_type: "LLC",
+                },
+                sales: [
+                    {
+                        date: "2023-06-15",
+                        price: 250000000,
+                        buyer: "EXAMPLE BUYER LLC",
+                        seller: "EXAMPLE SELLER LLC",
+                    },
+                ],
+                zoning: { district: "C5-3", overlay: null },
+                assessed_value: { total: 1200000000, land: 300000000 },
+                rent_stabilized: true,
+            },
+        },
+        example_error_response: {
+            error: {
+                code: "INVALID_BBL",
+                message: "The BBL provided is not valid. BBL must be a 10-digit string.",
+                suggested_next_step: "Use resolve_property_identifier to get a valid BBL first.",
+            },
+        },
+    },
+    get_building_violations: {
+        description: "Returns DOB/HPD violations, ECB penalties, complaints, and permits for a building.",
+        example_input: { bbl: "1008350001", status: "open" },
+        example_success_response: {
+            building: {
+                bbl: "1008350001",
+                bin: "1015000",
+                address: "350 FIFTH AVE",
+            },
+            violations: [
+                {
+                    source: "DOB",
+                    number: "123456789",
+                    date: "2024-01-10",
+                    category: "ELEVATOR",
+                    description: "FAILURE TO MAINTAIN ELEVATOR",
+                    status: "OPEN",
+                    penalty_amount: 5000,
+                },
+            ],
+            total_count: 1,
+            open_count: 1,
+        },
+        example_error_response: {
+            error: {
+                code: "UPSTREAM_TIMEOUT",
+                message: "The NYC Open Data API did not respond in time.",
+                suggested_next_step: "Retry in a few seconds.",
+            },
+        },
+    },
+    get_restaurant_venue_intel: {
+        description: "Returns health grades, liquor license, permits, and 311 complaints for a venue.",
+        example_input: {
+            name: "JOE'S PIZZA",
+            borough: "MANHATTAN",
+        },
+        example_success_response: {
+            venue: {
+                name: "JOE'S PIZZA",
+                address: "7 CARMINE ST",
+                borough: "MANHATTAN",
+                health: {
+                    grade: "A",
+                    score: 10,
+                    inspection_date: "2024-02-15",
+                    critical_violations: 0,
+                },
+                liquor_license: null,
+                sidewalk_cafe_permit: false,
+            },
+        },
+        example_error_response: {
+            error: {
+                code: "NO_MATCH",
+                message: "No restaurants or venues matched the input. Try adjusting the name or adding a borough.",
+                suggested_next_step: "Check spelling and provide the full business name.",
+            },
+        },
+    },
+}, null, 2);

package/dist/tools/get-building-violations.d.ts

@@ -0,0 +1,38 @@
+export declare const TOOL_NAME = "get_building_violations";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            address: {
+                type: string;
+                description: string;
+            };
+            bin: {
+                type: string;
+                description: string;
+            };
+            borough: {
+                type: string;
+                description: string;
+            };
+            include_complaints: {
+                type: string;
+                description: string;
+            };
+            include_resolved_counts: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export interface GetBuildingViolationsArgs {
+    address?: string;
+    bin?: string;
+    borough?: string;
+    include_complaints?: boolean;
+    include_resolved_counts?: boolean;
+}
+export declare function getBuildingViolations(args: GetBuildingViolationsArgs): Promise<string>;

package/dist/tools/get-building-violations.js

@@ -0,0 +1,160 @@
+import { NycApiClient } from "../lib/nyc-api-client.js";
+import { mcpError, mapApiErrorToMcp, ErrorCodes } from "../lib/errors.js";
+export const TOOL_NAME = "get_building_violations";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "Get building violation records for a NYC property. Returns DOB violations, HPD violations, and summary counts. Optionally include 311 complaint history and resolved violation counts. Costs 1 credit. Call resolve_property_identifier first. Summary by default.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            address: {
+                type: "string",
+                description: "Full or normalized NYC street address",
+            },
+            bin: {
+                type: "string",
+                description: "Building Identification Number",
+            },
+            borough: {
+                type: "string",
+                description: "Borough name or code to disambiguate",
+            },
+            include_complaints: {
+                type: "boolean",
+                description: "Include 311 complaint history (default false)",
+            },
+            include_resolved_counts: {
+                type: "boolean",
+                description: "Include resolved violation counts per agency (default false)",
+            },
+        },
+    },
+};
+function isApiError(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "error" in result &&
+        typeof result.error === "object");
+}
+function unwrapData(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const rec = raw;
+    if (rec.bin || rec.address || rec.bbl)
+        return rec;
+    if (rec.data && typeof rec.data === "object" && !Array.isArray(rec.data)) {
+        return rec.data;
+    }
+    if (Array.isArray(rec.data) && rec.data.length > 0) {
+        return rec.data[0];
+    }
+    if (Array.isArray(rec) && rec.length > 0) {
+        return rec[0];
+    }
+    return null;
+}
+function str(val) {
+    return val != null ? String(val) : "";
+}
+function num(val) {
+    if (val == null)
+        return null;
+    const n = Number(val);
+    return Number.isNaN(n) ? null : n;
+}
+function buildSourceCoverage(data) {
+    return {
+        dob: Boolean(data.dob_violations != null ||
+            data.dob_violation_count != null ||
+            data.dob_open != null),
+        hpd: Boolean(data.hpd_violations != null ||
+            data.hpd_violation_count != null ||
+            data.hpd_open != null),
+        complaints_311: Boolean(data.complaints != null ||
+            data.complaint_count != null ||
+            data.complaints_311 != null),
+    };
+}
+export async function getBuildingViolations(args) {
+    const address = args.address?.trim() || undefined;
+    const bin = args.bin?.trim() || undefined;
+    const borough = args.borough?.trim() || undefined;
+    if (!address && !bin) {
+        return JSON.stringify(mcpError(ErrorCodes.MISSING_REQUIRED_IDENTIFIER, "At least address or bin is required."));
+    }
+    const client = new NycApiClient();
+    const lookupParams = {};
+    if (address)
+        lookupParams.address = address;
+    if (bin)
+        lookupParams.bin = bin;
+    if (borough)
+        lookupParams.borough = borough;
+    // violationsProfile requires address — pass address or bin as address fallback
+    const profileParams = {
+        address: address || bin || "",
+        borough,
+    };
+    let raw;
+    try {
+        raw = await client.violationsProfile(profileParams);
+    }
+    catch (err) {
+        console.error("get_building_violations error:", err);
+        return JSON.stringify(mcpError(ErrorCodes.UPSTREAM_TIMEOUT, `Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
+    }
+    if (isApiError(raw)) {
+        return JSON.stringify(mapApiErrorToMcp(raw));
+    }
+    const data = unwrapData(raw);
+    if (!data) {
+        const notFound = mcpError(ErrorCodes.NOT_FOUND, `No violation data returned for ${bin ? `BIN ${bin}` : `address "${address}"`}.`);
+        return JSON.stringify(notFound);
+    }
+    const sourceCoverage = buildSourceCoverage(data);
+    const dobCount = num(data.dob_violations ?? data.dob_violation_count ?? data.dob_count);
+    const hpdCount = num(data.hpd_violations ?? data.hpd_violation_count ?? data.hpd_count);
+    const totals = {
+        dob_count: dobCount,
+        hpd_count: hpdCount,
+        total: num(data.total_violations ??
+            data.violation_count ??
+            (dobCount ?? 0) + (hpdCount ?? 0)),
+    };
+    // Extract open violations array
+    const rawOpen = data.open_violations || data.violations || data.open;
+    const openViolations = Array.isArray(rawOpen)
+        ? rawOpen.map((v) => ({
+            type: str(v.violation_type || v.type),
+            agency: str(v.agency || v.source),
+            description: str(v.description || v.violation_description),
+            date: str(v.date || v.violation_date || v.issued_date),
+            status: str(v.status || v.disposition || "open"),
+            ...v,
+        }))
+        : [];
+    const profile = {
+        normalized_address: str(data.normalized_address || data.address),
+        bin: str(data.bin || bin),
+        bbl: str(data.bbl),
+        borough: str(data.borough),
+        totals,
+        open_violations: openViolations,
+        source_coverage: sourceCoverage,
+    };
+    if (args.include_complaints) {
+        const complaints = data.complaints_311 || data.complaints || data.complaint_history;
+        profile.complaints_311 = Array.isArray(complaints) ? complaints : [];
+    }
+    if (args.include_resolved_counts) {
+        const dobResolved = num(data.dob_resolved ?? data.dob_resolved_count);
+        const hpdResolved = num(data.hpd_resolved ?? data.hpd_resolved_count);
+        profile.resolved_counts = {
+            dob: dobResolved,
+            hpd: hpdResolved,
+            total: num(data.total_resolved ??
+                (dobResolved ?? 0) + (hpdResolved ?? 0)),
+        };
+    }
+    return JSON.stringify(profile);
+}

package/dist/tools/get-property-intelligence.d.ts

@@ -0,0 +1,43 @@
+export declare const TOOL_NAME = "get_property_intelligence";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            address: {
+                type: string;
+                description: string;
+            };
+            bbl: {
+                type: string;
+                description: string;
+            };
+            borough: {
+                type: string;
+                description: string;
+            };
+            include_sales_history: {
+                type: string;
+                description: string;
+            };
+            include_liens: {
+                type: string;
+                description: string;
+            };
+            include_rent_status: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export interface GetPropertyIntelligenceArgs {
+    address?: string;
+    bbl?: string;
+    borough?: string;
+    include_sales_history?: boolean;
+    include_liens?: boolean;
+    include_rent_status?: boolean;
+}
+export declare function getPropertyIntelligence(args: GetPropertyIntelligenceArgs): Promise<string>;

package/dist/tools/get-property-intelligence.js

@@ -0,0 +1,213 @@
+import { NycApiClient } from "../lib/nyc-api-client.js";
+import { mcpError, mapApiErrorToMcp, ErrorCodes } from "../lib/errors.js";
+export const TOOL_NAME = "get_property_intelligence";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "Get a full property intelligence profile for a NYC property. Returns owner, zoning, assessment, and violation counts. Optionally include sales history, liens detail, and rent stabilization status via flags. Costs 1 credit per call. Always call resolve_property_identifier first to validate the address. Summary response by default — set include flags to true for additional detail.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            address: {
+                type: "string",
+                description: "Full or normalized NYC street address",
+            },
+            bbl: {
+                type: "string",
+                description: "Borough-Block-Lot (10 digits)",
+            },
+            borough: {
+                type: "string",
+                description: "Borough name or code to disambiguate",
+            },
+            include_sales_history: {
+                type: "boolean",
+                description: "Include recent sales/transactions (default false)",
+            },
+            include_liens: {
+                type: "boolean",
+                description: "Include liens detail (default false)",
+            },
+            include_rent_status: {
+                type: "boolean",
+                description: "Include rent stabilization status (default false)",
+            },
+        },
+    },
+};
+function isApiError(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "error" in result &&
+        typeof result.error === "object");
+}
+function unwrapData(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const rec = raw;
+    // Direct record with bbl/address
+    if (rec.bbl || rec.address)
+        return rec;
+    // { data: { ... } } wrapper
+    if (rec.data && typeof rec.data === "object" && !Array.isArray(rec.data)) {
+        return rec.data;
+    }
+    // { data: [ ... ] } wrapper — take first element
+    if (Array.isArray(rec.data) && rec.data.length > 0) {
+        return rec.data[0];
+    }
+    // Array at top level — take first element
+    if (Array.isArray(rec) && rec.length > 0) {
+        return rec[0];
+    }
+    return null;
+}
+function str(val) {
+    if (val == null)
+        return "";
+    if (typeof val === "object" && !Array.isArray(val)) {
+        // Handle nested objects like address: { full, borough, zipcode }
+        const obj = val;
+        return String(obj.full || obj.address || obj.name || JSON.stringify(val));
+    }
+    return String(val);
+}
+function num(val) {
+    if (val == null)
+        return null;
+    const n = Number(val);
+    return Number.isNaN(n) ? null : n;
+}
+function computeConfidence(input) {
+    if (input.bbl)
+        return "high";
+    if (input.address)
+        return "medium";
+    return "low";
+}
+function buildSourceCoverage(data) {
+    return {
+        property_lookup: true,
+        owner: Boolean(data.owner || data.owner_name),
+        zoning: Boolean(data.zoning || data.zoning_district),
+        assessment: Boolean(data.assessed_total || data.assessed_land || data.market_value),
+        building_info: Boolean(data.building_class || data.year_built || data.num_floors),
+        violations: Boolean(data.violation_count != null ||
+            data.dob_violations != null ||
+            data.hpd_violations != null),
+        sales_history: Boolean(data.sales || data.recent_transactions),
+        liens: Boolean(data.liens || data.lien_count != null),
+        rent_stabilization: Boolean(data.rent_stabilized != null || data.rent_status),
+    };
+}
+export async function getPropertyIntelligence(args) {
+    const address = args.address?.trim() || undefined;
+    const bbl = args.bbl?.trim() || undefined;
+    const borough = args.borough?.trim() || undefined;
+    if (!address && !bbl) {
+        return JSON.stringify(mcpError(ErrorCodes.MISSING_REQUIRED_IDENTIFIER, "At least address or bbl is required."));
+    }
+    const client = new NycApiClient();
+    const lookupParams = {};
+    if (bbl)
+        lookupParams.bbl = bbl;
+    if (address)
+        lookupParams.address = address;
+    if (borough)
+        lookupParams.borough = borough;
+    let raw;
+    try {
+        raw = await client.propertyLookup(lookupParams);
+    }
+    catch (err) {
+        console.error("get_property_intelligence error:", err);
+        return JSON.stringify(mcpError(ErrorCodes.UPSTREAM_TIMEOUT, `Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
+    }
+    if (isApiError(raw)) {
+        return JSON.stringify(mapApiErrorToMcp(raw));
+    }
+    const data = unwrapData(raw);
+    if (!data) {
+        const notFound = mcpError(ErrorCodes.NOT_FOUND, `No property data returned for ${bbl ? `BBL ${bbl}` : `address "${address}"`}.`);
+        return JSON.stringify(notFound);
+    }
+    const sourceCoverage = buildSourceCoverage(data);
+    // Extract address and borough from potentially nested address object
+    let normalizedAddress = "";
+    let resolvedBorough = "";
+    const addrField = data.address;
+    if (addrField && typeof addrField === "object" && !Array.isArray(addrField)) {
+        const addrObj = addrField;
+        normalizedAddress = String(addrObj.full || addrObj.address || "");
+        resolvedBorough = String(addrObj.borough || data.borough || "");
+    }
+    else {
+        normalizedAddress = str(data.normalized_address || data.address);
+        resolvedBorough = str(data.borough);
+    }
+    const profile = {
+        normalized_address: normalizedAddress,
+        bbl: String(data.bbl || "").replace(/\.0+$/, ""),
+        bin: str(data.bin),
+        borough: resolvedBorough,
+        confidence: computeConfidence({ address, bbl }),
+        owner: {
+            name: str(data.owner || data.owner_name),
+            type: str(data.owner_type || ""),
+        },
+        zoning: {
+            district: str(data.zoning || data.zoning_district),
+            land_use: str(data.land_use || ""),
+        },
+        assessment: {
+            assessed_total: num(data.assessed_total),
+            assessed_land: num(data.assessed_land),
+            market_value: num(data.market_value),
+            tax_class: str(data.tax_class),
+        },
+        building_info: {
+            building_class: str(data.building_class),
+            year_built: num(data.year_built),
+            num_floors: num(data.num_floors),
+            num_units: num(data.num_units || data.total_units),
+            lot_area_sqft: num(data.lot_area || data.lot_area_sqft),
+        },
+        violation_counts: {
+            dob: num(data.dob_violations ?? data.dob_violation_count),
+            hpd: num(data.hpd_violations ?? data.hpd_violation_count),
+            ecb: num(data.ecb_violations ?? data.ecb_violation_count),
+            total: num(data.violation_count ??
+                data.total_violations ??
+                (num(data.dob_violations ?? data.dob_violation_count) ?? 0) +
+                    (num(data.hpd_violations ?? data.hpd_violation_count) ?? 0) +
+                    (num(data.ecb_violations ?? data.ecb_violation_count) ?? 0)),
+        },
+        coordinates: {
+            latitude: num(data.latitude || data.lat),
+            longitude: num(data.longitude || data.lng || data.lon),
+        },
+        source_coverage: sourceCoverage,
+    };
+    if (args.include_sales_history) {
+        const sales = data.sales || data.recent_transactions;
+        profile.recent_transactions = Array.isArray(sales) ? sales : [];
+    }
+    if (args.include_liens) {
+        const liens = data.liens;
+        const liensArray = Array.isArray(liens) ? liens : [];
+        const activeCount = num(data.active_lien_count ?? data.lien_count) ?? liensArray.length;
+        profile.liens = {
+            active_count: activeCount,
+            has_liens: activeCount > 0,
+            details: liensArray,
+        };
+    }
+    if (args.include_rent_status) {
+        const isStabilized = data.rent_stabilized != null ? Boolean(data.rent_stabilized) : null;
+        profile.rent_stabilization = {
+            is_stabilized: isStabilized,
+            unit_count: num(data.rent_stabilized_units ?? data.stabilized_unit_count),
+            status: str(data.rent_status || (isStabilized === true ? "stabilized" : isStabilized === false ? "not_stabilized" : "unknown")),
+        };
+    }
+    return JSON.stringify(profile);
+}

package/dist/tools/get-restaurant-venue-intel.d.ts

@@ -0,0 +1,38 @@
+export declare const TOOL_NAME = "get_restaurant_venue_intel";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            address: {
+                type: string;
+                description: string;
+            };
+            borough: {
+                type: string;
+                description: string;
+            };
+            include_liquor_license: {
+                type: string;
+                description: string;
+            };
+            include_sidewalk_cafe: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export interface GetRestaurantVenueIntelArgs {
+    name?: string;
+    address?: string;
+    borough?: string;
+    include_liquor_license?: boolean;
+    include_sidewalk_cafe?: boolean;
+}
+export declare function getRestaurantVenueIntel(args: GetRestaurantVenueIntelArgs): Promise<string>;