@matchuplabs/nyc-api-mcp 0.1.0

package/dist/tools/get-restaurant-venue-intel.js

@@ -0,0 +1,190 @@
+import { NycApiClient } from "../lib/nyc-api-client.js";
+import { mcpError, mapApiErrorToMcp, ErrorCodes } from "../lib/errors.js";
+export const TOOL_NAME = "get_restaurant_venue_intel";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "Get health inspection and compliance data for a NYC restaurant or venue. Returns current health grade, inspection score, and last inspection date. Optionally include sidewalk cafe permits and business license detail. Costs 1 credit. For name-only searches, provide borough to improve match accuracy.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "Restaurant or venue name",
+            },
+            address: {
+                type: "string",
+                description: "Street address of the restaurant or venue",
+            },
+            borough: {
+                type: "string",
+                description: "Borough name to improve match accuracy",
+            },
+            include_liquor_license: {
+                type: "boolean",
+                description: "Include liquor/business license detail (default false)",
+            },
+            include_sidewalk_cafe: {
+                type: "boolean",
+                description: "Include sidewalk cafe permit detail (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 name/camis
+    if (rec.camis || rec.dba || rec.restaurant_name)
+        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.address && input.name)
+        return "high";
+    if (input.address)
+        return "medium";
+    if (input.name && input.borough)
+        return "medium";
+    if (input.name)
+        return "low";
+    return "low";
+}
+function buildSourceCoverage(data, includePermits, includeLicenses) {
+    return {
+        health_inspection: Boolean(data.grade || data.score != null || data.inspection_date),
+        inspection_history: Boolean(data.total_inspections != null || data.inspections),
+        sidewalk_cafe_permits: includePermits,
+        business_licenses: includeLicenses,
+    };
+}
+export async function getRestaurantVenueIntel(args) {
+    const name = args.name?.trim() || undefined;
+    const address = args.address?.trim() || undefined;
+    const borough = args.borough?.trim() || undefined;
+    const includeSidewalkCafe = args.include_sidewalk_cafe ?? false;
+    const includeLiquorLicense = args.include_liquor_license ?? false;
+    if (!name && !address) {
+        return JSON.stringify(mcpError(ErrorCodes.MISSING_REQUIRED_IDENTIFIER, "At least name or address is required."));
+    }
+    const client = new NycApiClient();
+    // Fetch health data
+    const healthParams = {};
+    if (name)
+        healthParams.name = name;
+    if (address)
+        healthParams.address = address;
+    if (borough)
+        healthParams.borough = borough;
+    let healthRaw;
+    try {
+        healthRaw = await client.venueHealth(healthParams);
+    }
+    catch (err) {
+        console.error("get_restaurant_venue_intel error:", err);
+        return JSON.stringify(mcpError(ErrorCodes.UPSTREAM_TIMEOUT, `Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
+    }
+    if (isApiError(healthRaw)) {
+        return JSON.stringify(mapApiErrorToMcp(healthRaw));
+    }
+    const data = unwrapData(healthRaw);
+    if (!data) {
+        const notFound = mcpError(ErrorCodes.NOT_FOUND, `No venue data returned for ${name ? `"${name}"` : `address "${address}"`}.`);
+        return JSON.stringify(notFound);
+    }
+    // Optionally fetch permits (sidewalk cafe + business licenses)
+    let permitsData = null;
+    if (includeSidewalkCafe || includeLiquorLicense) {
+        const permitsParams = {};
+        if (name)
+            permitsParams.name = name;
+        if (address)
+            permitsParams.address = address;
+        try {
+            const permitsRaw = await client.venuePermits(permitsParams);
+            if (!isApiError(permitsRaw)) {
+                permitsData = unwrapData(permitsRaw);
+            }
+        }
+        catch (err) {
+            console.error("get_restaurant_venue_intel permits sub-call error:", err);
+            // Non-fatal: continue without permits data
+        }
+    }
+    const sourceCoverage = buildSourceCoverage(data, includeSidewalkCafe, includeLiquorLicense);
+    // Extract address and borough from potentially nested address object
+    let venueAddress = "";
+    let venueBoro = "";
+    const addrField = data.address;
+    if (addrField && typeof addrField === "object" && !Array.isArray(addrField)) {
+        const addrObj = addrField;
+        venueAddress = String(addrObj.full || addrObj.address || addrObj.building || "");
+        venueBoro = String(addrObj.borough || data.boro || data.borough || "");
+    }
+    else {
+        venueAddress = str(data.address || data.building_address || data.street);
+        venueBoro = str(data.boro || data.borough);
+    }
+    const profile = {
+        matched_entity: {
+            name: str(data.dba || data.restaurant_name || data.name),
+            address: venueAddress,
+            borough: venueBoro,
+            camis: str(data.camis),
+            cuisine: str(data.cuisine_description || data.cuisine),
+            confidence: computeConfidence({ name, address, borough }),
+        },
+        health_inspection: {
+            grade: str(data.grade || data.current_grade),
+            score: num(data.score || data.inspection_score),
+            date: str(data.inspection_date || data.grade_date || data.last_inspection_date),
+            action: str(data.action || data.inspection_action),
+            critical_violations: num(data.critical_flag_count ?? data.critical_violations),
+        },
+        total_inspections: num(data.total_inspections ?? data.inspection_count),
+        source_coverage: sourceCoverage,
+    };
+    if (includeSidewalkCafe) {
+        const permits = permitsData?.sidewalk_cafe_permits ?? permitsData?.cafe_permits;
+        profile.sidewalk_cafe_permits = Array.isArray(permits) ? permits : [];
+    }
+    if (includeLiquorLicense) {
+        const licenses = permitsData?.business_licenses ?? permitsData?.liquor_licenses ?? permitsData?.licenses;
+        profile.business_licenses = Array.isArray(licenses) ? licenses : [];
+    }
+    return JSON.stringify(profile);
+}

package/dist/tools/resolve-property-identifier.d.ts

@@ -0,0 +1,27 @@
+export declare const TOOL_NAME = "resolve_property_identifier";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            address: {
+                type: string;
+                description: string;
+            };
+            bbl: {
+                type: string;
+                description: string;
+            };
+            bin: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function resolvePropertyIdentifier(args: {
+    address?: string;
+    bbl?: string;
+    bin?: string;
+}): Promise<string>;

package/dist/tools/resolve-property-identifier.js

@@ -0,0 +1,256 @@
+import { NycApiClient } from "../lib/nyc-api-client.js";
+import { mcpError, mapApiErrorToMcp, ErrorCodes } from "../lib/errors.js";
+export const TOOL_NAME = "resolve_property_identifier";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "Normalize and validate a NYC property identifier. Pass a partial address, BBL, or BIN and get back the normalized address, BBL, BIN, borough, and a confidence score. Use this BEFORE calling get_property_intelligence or get_building_violations to ensure you have the correct property. Returns multiple candidates if the input is ambiguous. Free or near-free — always resolve first.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            address: {
+                type: "string",
+                description: "Partial or full NYC street address",
+            },
+            bbl: {
+                type: "string",
+                description: "Borough-Block-Lot (10 digits)",
+            },
+            bin: {
+                type: "string",
+                description: "Building Identification Number",
+            },
+        },
+    },
+};
+function isApiError(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "error" in result &&
+        typeof result.error === "object");
+}
+function extractCandidate(record, confidence) {
+    // Handle nested address object from PropertyProfile: { full, borough, zipcode }
+    let normalizedAddress = "";
+    let borough = "";
+    const addr = record.address;
+    if (addr && typeof addr === "object" && !Array.isArray(addr)) {
+        const addrObj = addr;
+        normalizedAddress = String(addrObj.full || addrObj.address || "");
+        borough = String(addrObj.borough || record.borough || "");
+    }
+    else {
+        normalizedAddress = String(addr || record.normalized_address || "");
+        borough = String(record.borough || "");
+    }
+    return {
+        normalized_address: normalizedAddress,
+        bbl: String(record.bbl || "").replace(/\.0+$/, ""),
+        bin: record.bin ? String(record.bin) : null,
+        borough,
+        confidence,
+    };
+}
+function computeConfidence(input) {
+    if (input.bbl)
+        return 1.0;
+    if (input.bin)
+        return 0.95;
+    if (input.address && input.borough)
+        return 0.9;
+    return 0.7;
+}
+/** Known NYC borough names and abbreviations */
+const BOROUGH_ALIASES = {
+    manhattan: "Manhattan",
+    bronx: "Bronx",
+    brooklyn: "Brooklyn",
+    queens: "Queens",
+    "staten island": "Staten Island",
+    mn: "Manhattan",
+    bx: "Bronx",
+    bk: "Brooklyn",
+    qn: "Queens",
+    si: "Staten Island",
+    "new york": "Manhattan",
+    nyc: "Manhattan",
+    ny: "Manhattan",
+};
+/**
+ * Parse a free-text address into street address + borough.
+ * Handles formats like:
+ *   "100 Broadway, Manhattan"
+ *   "100 Broadway Manhattan"
+ *   "100 Broadway, Brooklyn, NY"
+ *   "100 Broadway New York"
+ */
+function parseAddressAndBorough(rawAddress) {
+    const trimmed = rawAddress.trim();
+    // Try comma-separated parts
+    const parts = trimmed.split(",").map((p) => p.trim()).filter(Boolean);
+    if (parts.length >= 2) {
+        // Check each part after the first for a borough match
+        for (let i = 1; i < parts.length; i++) {
+            const normalized = parts[i].toLowerCase().replace(/\s+/g, " ");
+            if (BOROUGH_ALIASES[normalized]) {
+                const street = parts.slice(0, i).join(", ");
+                return { street, borough: BOROUGH_ALIASES[normalized] };
+            }
+        }
+        // No borough found in comma parts — use first part as street
+        return { street: parts[0] };
+    }
+    // No commas — check if the last word(s) are a borough
+    const words = trimmed.split(/\s+/);
+    // Try last two words (e.g., "Staten Island")
+    if (words.length >= 3) {
+        const lastTwo = words.slice(-2).join(" ").toLowerCase();
+        if (BOROUGH_ALIASES[lastTwo]) {
+            return { street: words.slice(0, -2).join(" "), borough: BOROUGH_ALIASES[lastTwo] };
+        }
+    }
+    // Try last word (e.g., "Manhattan")
+    if (words.length >= 2) {
+        const lastOne = words[words.length - 1].toLowerCase();
+        if (BOROUGH_ALIASES[lastOne]) {
+            return { street: words.slice(0, -1).join(" "), borough: BOROUGH_ALIASES[lastOne] };
+        }
+    }
+    return { street: trimmed };
+}
+export async function resolvePropertyIdentifier(args) {
+    const rawAddress = args.address?.trim() || undefined;
+    const bbl = args.bbl?.trim() || undefined;
+    const bin = args.bin?.trim() || undefined;
+    if (!rawAddress && !bbl && !bin) {
+        return JSON.stringify(mcpError(ErrorCodes.MISSING_REQUIRED_IDENTIFIER));
+    }
+    // Parse address into street + borough
+    let address;
+    let borough;
+    if (rawAddress) {
+        const parsed = parseAddressAndBorough(rawAddress);
+        address = parsed.street;
+        borough = parsed.borough;
+    }
+    try {
+        const client = new NycApiClient();
+        // Step 1: Try /api/property/lookup
+        const lookupParams = {};
+        if (bbl)
+            lookupParams.bbl = bbl;
+        if (address)
+            lookupParams.address = address;
+        if (borough)
+            lookupParams.borough = borough;
+        if (bin)
+            lookupParams.bin = bin;
+        const lookupResult = await client.propertyLookup(lookupParams);
+        if (isApiError(lookupResult)) {
+            // For non-404 errors, return immediately
+            const mapped = mapApiErrorToMcp(lookupResult);
+            if (mapped.error.code !== ErrorCodes.NOT_FOUND) {
+                return JSON.stringify(mapped);
+            }
+            // For 404, fall through to search
+        }
+        else if (lookupResult) {
+            const record = lookupResult;
+            // Single match from lookup
+            if (record.bbl || record.address) {
+                const confidence = computeConfidence({ address, bbl, bin, borough });
+                const candidate = extractCandidate(record, confidence);
+                const result = {
+                    candidates: [candidate],
+                    match_count: 1,
+                    recommendation: "Exact match found. Proceed with get_property_intelligence or get_building_violations.",
+                };
+                return JSON.stringify(result);
+            }
+            // Lookup returned an array of results (some APIs do this)
+            if (Array.isArray(record)) {
+                const candidates = record.map((r, i) => extractCandidate(r, i === 0 ? 0.9 : 0.9 - i * 0.1));
+                if (candidates.length === 1) {
+                    const result = {
+                        candidates,
+                        match_count: 1,
+                        recommendation: "Single match found. Proceed with get_property_intelligence or get_building_violations.",
+                    };
+                    return JSON.stringify(result);
+                }
+                if (candidates.length > 1) {
+                    const result = {
+                        candidates: candidates.slice(0, 10),
+                        match_count: candidates.length,
+                        recommendation: "Multiple candidates found. Add borough or zipcode to narrow the match, or select a candidate by BBL.",
+                    };
+                    return JSON.stringify(result);
+                }
+            }
+            // Check if lookup returned a data wrapper
+            if (record.data) {
+                const data = record.data;
+                if (Array.isArray(data) && data.length > 0) {
+                    const candidates = data.map((r, i) => extractCandidate(r, i === 0 ? computeConfidence({ address, bbl, bin, borough }) : 0.7 - i * 0.1));
+                    const result = {
+                        candidates: candidates.slice(0, 10),
+                        match_count: candidates.length,
+                        recommendation: candidates.length === 1
+                            ? "Exact match found. Proceed with get_property_intelligence or get_building_violations."
+                            : "Multiple candidates found. Add borough or zipcode to narrow the match, or select a candidate by BBL.",
+                    };
+                    return JSON.stringify(result);
+                }
+                if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+                    const candidate = extractCandidate(data, computeConfidence({ address, bbl, bin, borough }));
+                    const result = {
+                        candidates: [candidate],
+                        match_count: 1,
+                        recommendation: "Exact match found. Proceed with get_property_intelligence or get_building_violations.",
+                    };
+                    return JSON.stringify(result);
+                }
+            }
+        }
+        // Step 2: If lookup failed/empty and we have an address, try search
+        if (address) {
+            const searchResult = await client.propertySearch({ address, borough });
+            if (isApiError(searchResult)) {
+                const mapped = mapApiErrorToMcp(searchResult);
+                if (mapped.error.code !== ErrorCodes.NOT_FOUND) {
+                    return JSON.stringify(mapped);
+                }
+            }
+            else if (searchResult) {
+                const searchRecord = searchResult;
+                let results = [];
+                if (Array.isArray(searchRecord)) {
+                    results = searchRecord;
+                }
+                else if (Array.isArray(searchRecord.data)) {
+                    results = searchRecord.data;
+                }
+                else if (Array.isArray(searchRecord.results)) {
+                    results = searchRecord.results;
+                }
+                if (results.length > 0) {
+                    const candidates = results.slice(0, 10).map((r, i) => extractCandidate(r, i === 0 ? 0.7 : Math.max(0.3, 0.7 - i * 0.1)));
+                    const result = {
+                        candidates,
+                        match_count: results.length,
+                        recommendation: candidates.length === 1
+                            ? "Single search match found. Verify the address and proceed."
+                            : "Multiple search results found. Refine with borough or zipcode, or select a candidate by BBL.",
+                    };
+                    return JSON.stringify(result);
+                }
+            }
+        }
+        // Step 3: Nothing found
+        const notFound = mcpError(ErrorCodes.NOT_FOUND, `No property found for the given identifier${address ? ` (address: "${address}"${borough ? `, borough: ${borough}` : ""})` : ""}${bbl ? ` (BBL: ${bbl})` : ""}${bin ? ` (BIN: ${bin})` : ""}. Try providing both address and borough (Manhattan, Bronx, Brooklyn, Queens, or Staten Island).`);
+        return JSON.stringify(notFound);
+    }
+    catch (err) {
+        console.error("resolve_property_identifier error:", err);
+        return JSON.stringify(mcpError(ErrorCodes.UPSTREAM_TIMEOUT, `Unexpected error: ${err instanceof Error ? err.message : String(err)}`));
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@matchuplabs/nyc-api-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for NYC property intelligence, building violations, and restaurant/venue compliance data via nycapi.app",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "nyc-api-mcp": "dist/index.js"
+  },
+  "mcpName": "io.github.matchuplabs/nyc-api",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MATCHUP-LABS/nycapi.git"
+  },
+  "keywords": ["mcp", "nyc", "property", "violations", "restaurant", "real-estate", "api", "ai-agent"],
+  "files": ["dist", "server.json", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "node-fetch": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,12 @@
+{
+  "name": "io.github.matchuplabs/nyc-api",
+  "title": "NYC Property & Venue API",
+  "description": "NYC property intelligence, building violations, and restaurant/venue compliance — unified, agent-ready MCP tools.",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "name": "@matchuplabs/nyc-api-mcp"
+    }
+  ]
+}