@matchuplabs/nycfhv-mcp 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @matchuplabs/nycfhv-mcp
+
+MCP server that exposes the [NYC FHV Intelligence API](https://fhv.matchup.dev) — TLC for-hire-vehicle license verification and renewal-window lookups — as Claude / OpenAI agent tools.
+
+## Tools
+
+| Tool | What it does | Cost |
+|---|---|---|
+| `verify_tlc_vehicle` | Verify an FHV by TLC license, DMV plate, or VIN. Returns active status, expiration, base, WAV flag. | 1 credit |
+| `list_upcoming_renewals` | Vehicles whose license expires in the next N days. Filters: base, WAV, max model year. | 5 credits / page |
+
+## Quickstart
+
+1. Get an API key at [matchuplabs.com](https://matchuplabs.com) (product: `fhv-intelligence`).
+2. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "nycfhv": {
+      "command": "npx",
+      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
+      "env": {
+        "FHV_API_KEY": "mv_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop. The two tools appear in the tool picker.
+
+## Environment
+
+| Variable | Required | Default |
+|---|---|---|
+| `FHV_API_KEY` | Yes | — |
+| `FHV_BASE_URL` | No | `https://fhv.matchup.dev` |
+
+## Why this exists
+
+Apps and AI agents that touch NYC for-hire transportation today can't verify a TLC license without scraping a manual portal. This MCP wraps a commercial-grade verification API so an agent can confirm "is this vehicle currently TLC-active?" as a single tool call before authorizing a livery rate, dispatching a Medicaid NEMT trip, or pre-binding insurance.
+
+Data source: NYC TLC's daily-refreshed [For-Hire Vehicles - Active dataset](https://data.cityofnewyork.us/Transportation/For-Hire-Vehicles-FHV-Active/8wbx-tsch). Public record under NY State FOIL.
+
+## Development
+
+```bash
+npm install
+FHV_API_KEY=mv_test_xxx npm run dev    # stdio server, requires a real key
+npm run build
+npm test
+```
+
+## License
+
+MIT. © Matchup Labs.

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer, checkApiKey } from "./server-core.js";
+async function main() {
+    checkApiKey();
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("nycfhv MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/lib/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP-side error envelope. Tools return JSON-stringified errors so the calling
+ * agent can branch on `error.code` without parsing free text.
+ */
+export interface McpError {
+    error: {
+        code: string;
+        message: string;
+        suggested_next_step: string;
+        upstream_status?: number;
+    };
+}
+export declare function mcpError(code: string, message: string, suggested_next_step: string, upstream_status?: number): McpError;
+export declare function mcpErrorString(code: string, message: string, suggested_next_step: string, upstream_status?: number): string;
+/**
+ * Map an upstream RFC 7807 problem-details payload (from fhv.matchup.dev) onto
+ * an MCP error envelope. The API returns `{ type, title, status, detail, ... }`.
+ */
+export declare function mapUpstreamError(status: number, body: unknown): McpError;

package/dist/lib/errors.js

@@ -0,0 +1,47 @@
+/**
+ * MCP-side error envelope. Tools return JSON-stringified errors so the calling
+ * agent can branch on `error.code` without parsing free text.
+ */
+export function mcpError(code, message, suggested_next_step, upstream_status) {
+    return { error: { code, message, suggested_next_step, upstream_status } };
+}
+export function mcpErrorString(code, message, suggested_next_step, upstream_status) {
+    return JSON.stringify(mcpError(code, message, suggested_next_step, upstream_status));
+}
+/**
+ * Map an upstream RFC 7807 problem-details payload (from fhv.matchup.dev) onto
+ * an MCP error envelope. The API returns `{ type, title, status, detail, ... }`.
+ */
+export function mapUpstreamError(status, body) {
+    const detail = body && typeof body === "object" && "detail" in body
+        ? String(body.detail)
+        : `Upstream returned ${status}`;
+    const title = body && typeof body === "object" && "title" in body
+        ? String(body.title)
+        : "Upstream error";
+    switch (status) {
+        case 400:
+            return mcpError("invalid_input", detail, "Fix the input and retry.", 400);
+        case 401:
+            return mcpError("invalid_api_key", "API key missing or invalid for fhv.matchup.dev.", "Set FHV_API_KEY in your MCP server env to a valid key from matchuplabs.com.", 401);
+        case 403:
+            return mcpError("key_disabled", detail, "Generate a fresh key at matchuplabs.com or contact support.", 403);
+        case 404:
+            return mcpError("not_found", detail, "Try a different identifier or relax filters.", 404);
+        case 429: {
+            const code = body && typeof body === "object" && "type" in body && String(body.type).includes("credits_exhausted")
+                ? "credits_exhausted"
+                : "rate_limit_exceeded";
+            const next = code === "credits_exhausted"
+                ? "Upgrade your plan or wait until next billing cycle."
+                : "Back off briefly (default 60s) and retry.";
+            return mcpError(code, detail, next, 429);
+        }
+        case 502:
+        case 503:
+        case 504:
+            return mcpError("upstream_error", `${title}: ${detail}`, "NYC TLC dataset is currently unavailable. Retry in a minute.", status);
+        default:
+            return mcpError("upstream_error", `${title}: ${detail}`, "Retry in a minute. Contact support if the error persists.", status);
+    }
+}

package/dist/lib/fhv-client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Tiny HTTP client for fhv.matchup.dev.
+ *
+ * Reads FHV_API_KEY from env (required) and FHV_BASE_URL (optional, defaults
+ * to production). Returns the parsed envelope `{data, meta}` on 2xx, or an
+ * `{ error: ... }` shape on non-2xx that mirrors the upstream RFC 7807 body.
+ */
+import { type McpError } from "./errors.js";
+export interface FhvSuccess<T> {
+    data: T;
+    meta: {
+        source: string;
+        updated?: string;
+        query_ms?: number;
+        credits_remaining?: number;
+        page?: number;
+        page_size?: number;
+        total_count?: number;
+    };
+}
+export type FhvResult<T> = FhvSuccess<T> | McpError;
+export interface Vehicle {
+    active: boolean;
+    vehicle_license_number: string;
+    name: string;
+    license_type: string;
+    expiration_date: string;
+    days_until_expiration: number;
+    permit_license_number: string | null;
+    dmv_license_plate_number: string | null;
+    vehicle_vin_number: string | null;
+    wheelchair_accessible: boolean;
+    vehicle_year: number | null;
+    base_number: string | null;
+    base_name: string | null;
+    base_type: string | null;
+}
+export declare class FhvClient {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey?: string, baseUrl?: string);
+    private retryFetch;
+    private request;
+    /** GET /api/v1/verify/{identifier} */
+    verify(identifier: string, type?: "auto" | "license" | "plate" | "vin"): Promise<FhvResult<Vehicle>>;
+    /** GET /api/v1/renewals/upcoming */
+    listUpcomingRenewals(params: {
+        days: number;
+        base_number?: string;
+        wheelchair_accessible?: boolean;
+        vehicle_year_max?: number;
+        page?: number;
+        page_size?: number;
+    }): Promise<FhvResult<Vehicle[]>>;
+}

package/dist/lib/fhv-client.js

@@ -0,0 +1,97 @@
+/**
+ * Tiny HTTP client for fhv.matchup.dev.
+ *
+ * Reads FHV_API_KEY from env (required) and FHV_BASE_URL (optional, defaults
+ * to production). Returns the parsed envelope `{data, meta}` on 2xx, or an
+ * `{ error: ... }` shape on non-2xx that mirrors the upstream RFC 7807 body.
+ */
+import { mapUpstreamError, mcpError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://fhv.matchup.dev";
+const REQUEST_TIMEOUT_MS = 10_000;
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+const BACKOFF_MS = [400, 1200];
+export class FhvClient {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.baseUrl = baseUrl || process.env.FHV_BASE_URL || DEFAULT_BASE_URL;
+        const key = apiKey || process.env.FHV_API_KEY;
+        if (!key) {
+            throw new Error("FHV_API_KEY is required — set it as an environment variable or pass it to the FhvClient constructor");
+        }
+        this.apiKey = key;
+    }
+    async retryFetch(url, init, maxRetries = 2) {
+        let lastResponse = null;
+        let lastError = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+            try {
+                const response = await fetch(url, { ...init, signal: controller.signal });
+                clearTimeout(timeoutId);
+                if (response.ok || !RETRYABLE.has(response.status)) {
+                    return response;
+                }
+                if (attempt < maxRetries) {
+                    await new Promise((r) => setTimeout(r, BACKOFF_MS[attempt] ?? 1200));
+                    lastResponse = response;
+                    continue;
+                }
+                return response;
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt < maxRetries) {
+                    await new Promise((r) => setTimeout(r, BACKOFF_MS[attempt] ?? 1200));
+                    continue;
+                }
+            }
+        }
+        if (lastResponse)
+            return lastResponse;
+        throw lastError ?? new Error("retryFetch exhausted retries");
+    }
+    async request(path, params = {}) {
+        const url = new URL(path, this.baseUrl);
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        }
+        let response;
+        try {
+            response = await this.retryFetch(url.toString(), {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                    "User-Agent": "nycfhv-mcp/0.1.0",
+                },
+            });
+        }
+        catch (err) {
+            return mcpError("upstream_timeout", `Request to fhv.matchup.dev failed: ${err instanceof Error ? err.message : String(err)}`, "Check network connectivity and retry.");
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = null;
+        }
+        if (!response.ok) {
+            return mapUpstreamError(response.status, body);
+        }
+        return body;
+    }
+    /** GET /api/v1/verify/{identifier} */
+    verify(identifier, type) {
+        const params = type && type !== "auto" ? { type } : {};
+        return this.request(`/api/v1/verify/${encodeURIComponent(identifier)}`, params);
+    }
+    /** GET /api/v1/renewals/upcoming */
+    listUpcomingRenewals(params) {
+        return this.request(`/api/v1/renewals/upcoming`, params);
+    }
+}

package/dist/server-core.d.ts

@@ -0,0 +1,3 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function createServer(): Server;
+export declare function checkApiKey(): void;

package/dist/server-core.js

@@ -0,0 +1,67 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { TOOL_DEFINITION as verifyDef, TOOL_NAME as verifyName, verifyTlcVehicle, } from "./tools/verify-tlc-vehicle.js";
+import { TOOL_DEFINITION as renewalsDef, TOOL_NAME as renewalsName, listUpcomingRenewals, } from "./tools/list-upcoming-renewals.js";
+export function createServer() {
+    const server = new Server({ name: "nycfhv", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [verifyDef, renewalsDef],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            switch (name) {
+                case verifyName: {
+                    const text = await verifyTlcVehicle((args ?? {}));
+                    return { content: [{ type: "text", text }] };
+                }
+                case renewalsName: {
+                    const text = await listUpcomingRenewals((args ?? {}));
+                    return { content: [{ type: "text", text }] };
+                }
+                default:
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: {
+                                        code: "unknown_tool",
+                                        message: `Tool "${name}" is not implemented by the nycfhv MCP server.`,
+                                        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: "internal_error",
+                                message: "An unexpected error occurred handling the tool call.",
+                                suggested_next_step: "Retry in a few seconds.",
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+export function checkApiKey() {
+    if (!process.env.FHV_API_KEY) {
+        console.error("ERROR: FHV_API_KEY environment variable is not set. The server cannot function without it.");
+        console.error("Set it with: export FHV_API_KEY=mv_live_your_key_here");
+        process.exit(1);
+    }
+}

package/dist/tools/list-upcoming-renewals.d.ts

@@ -0,0 +1,49 @@
+export declare const TOOL_NAME = "list_upcoming_renewals";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            days: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+            base_number: {
+                type: string;
+                description: string;
+            };
+            wheelchair_accessible: {
+                type: string;
+                description: string;
+            };
+            vehicle_year_max: {
+                type: string;
+                description: string;
+            };
+            page: {
+                type: string;
+                description: string;
+                minimum: number;
+            };
+            page_size: {
+                type: string;
+                description: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+        required: string[];
+    };
+};
+export interface ListUpcomingRenewalsArgs {
+    days: number;
+    base_number?: string;
+    wheelchair_accessible?: boolean;
+    vehicle_year_max?: number;
+    page?: number;
+    page_size?: number;
+}
+export declare function listUpcomingRenewals(args: ListUpcomingRenewalsArgs): Promise<string>;

package/dist/tools/list-upcoming-renewals.js

@@ -0,0 +1,68 @@
+import { FhvClient } from "../lib/fhv-client.js";
+export const TOOL_NAME = "list_upcoming_renewals";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "List NYC TLC for-hire vehicles whose license expires within the next N days. Optional filters: TLC base (e.g., 'B03404' for Uber), wheelchair-accessible (WAV) only, and maximum vehicle model year (for fleet-aging targeting). Paginated, 50 results per page by default. Costs 5 credits per page. Use this for renewal-window lead lists (license expediters, insurance brokers, training schools, EV/hybrid dealer prospecting).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            days: {
+                type: "integer",
+                description: "Renewal window from today, inclusive. 1–180 days. Most use cases pick 14, 30, 60, or 90.",
+                minimum: 1,
+                maximum: 180,
+            },
+            base_number: {
+                type: "string",
+                description: "Optional TLC base number filter (e.g., 'B03404' = Uber USA, 'B00477' = INTA-BORO ACRES). Case-insensitive.",
+            },
+            wheelchair_accessible: {
+                type: "boolean",
+                description: "If true, returns only WAV / WAV-pilot vehicles (~8% of fleet). If false, returns only non-WAV vehicles. Omit for both.",
+            },
+            vehicle_year_max: {
+                type: "integer",
+                description: "Optional maximum model year. Use to target older fleet for replacement-financing or pre-sales lead-gen.",
+            },
+            page: {
+                type: "integer",
+                description: "1-indexed page number. Default 1.",
+                minimum: 1,
+            },
+            page_size: {
+                type: "integer",
+                description: "Results per page, 10–100. Default 50.",
+                minimum: 10,
+                maximum: 100,
+            },
+        },
+        required: ["days"],
+    },
+};
+export async function listUpcomingRenewals(args) {
+    if (typeof args.days !== "number" || args.days < 1 || args.days > 180) {
+        return JSON.stringify({
+            error: {
+                code: "invalid_input",
+                message: "`days` must be an integer between 1 and 180.",
+                suggested_next_step: "Pick a renewal window like 30, 60, or 90.",
+            },
+        });
+    }
+    const client = new FhvClient();
+    const result = await client.listUpcomingRenewals(args);
+    if ("error" in result) {
+        return JSON.stringify(result);
+    }
+    return JSON.stringify({
+        data: result.data,
+        meta: {
+            source: result.meta.source,
+            updated: result.meta.updated,
+            page: result.meta.page,
+            page_size: result.meta.page_size,
+            total_count: result.meta.total_count,
+            credits_remaining: result.meta.credits_remaining,
+        },
+    });
+}

package/dist/tools/verify-tlc-vehicle.d.ts

@@ -0,0 +1,25 @@
+export declare const TOOL_NAME = "verify_tlc_vehicle";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            identifier: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                description: string;
+                enum: string[];
+            };
+        };
+        required: string[];
+    };
+};
+export interface VerifyTlcVehicleArgs {
+    identifier: string;
+    type?: "auto" | "license" | "plate" | "vin";
+}
+export declare function verifyTlcVehicle(args: VerifyTlcVehicleArgs): Promise<string>;

package/dist/tools/verify-tlc-vehicle.js

@@ -0,0 +1,45 @@
+import { FhvClient } from "../lib/fhv-client.js";
+export const TOOL_NAME = "verify_tlc_vehicle";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "Verify whether a NYC TLC for-hire vehicle is currently licensed. Accepts a TLC license number (e.g. 'C05015' or '5545596'), DMV plate (e.g. 'T438350C'), or 17-character VIN. Returns active status, expiration date, base affiliation, wheelchair-accessible (WAV) flag, and days_until_expiration. Identifier type is auto-detected by default. Costs 1 credit per call. Use this before authorizing a livery rate, dispatch, or pre-bind insurance check on a NYC for-hire vehicle.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            identifier: {
+                type: "string",
+                description: "TLC license number (legacy 'C05015' or 7-digit numeric '5545596'), DMV plate, or 17-char VIN.",
+            },
+            type: {
+                type: "string",
+                description: "Optional override for identifier auto-detection. Use when the identifier could be ambiguous (e.g., a 7-digit string that could be a license or a plate).",
+                enum: ["auto", "license", "plate", "vin"],
+            },
+        },
+        required: ["identifier"],
+    },
+};
+export async function verifyTlcVehicle(args) {
+    if (!args.identifier || typeof args.identifier !== "string") {
+        return JSON.stringify({
+            error: {
+                code: "invalid_input",
+                message: "`identifier` is required and must be a string.",
+                suggested_next_step: "Provide a TLC license number, plate, or VIN.",
+            },
+        });
+    }
+    const client = new FhvClient();
+    const result = await client.verify(args.identifier.trim(), args.type ?? "auto");
+    if ("error" in result) {
+        return JSON.stringify(result);
+    }
+    return JSON.stringify({
+        data: result.data,
+        meta: {
+            source: result.meta.source,
+            updated: result.meta.updated,
+            credits_remaining: result.meta.credits_remaining,
+        },
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@matchuplabs/nycfhv-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the NYC FHV Intelligence API. Exposes TLC for-hire vehicle license verification and renewal-window lookups as agent tools backed by fhv.matchup.dev.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "nycfhv-mcp": "dist/index.js"
+  },
+  "mcpName": "io.github.MatchupLabs/nycfhv",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MATCHUP-LABS/nycfhv.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://fhv.matchup.dev",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nyc",
+    "tlc",
+    "for-hire-vehicle",
+    "fhv",
+    "license-verification",
+    "rideshare",
+    "ai-agent"
+  ],
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "~1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.2"
+  }
+}

package/server.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.MatchupLabs/nycfhv",
+  "title": "NYC FHV Intelligence API",
+  "description": "Real-time NYC TLC for-hire vehicle license verification and renewal-window lead lookups via MCP.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/MATCHUP-LABS/nycfhv",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@matchuplabs/nycfhv-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FHV_API_KEY",
+          "description": "API key from matchuplabs.com (product='fhv-intelligence')",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "FHV_BASE_URL",
+          "description": "API base URL (default: https://fhv.matchup.dev)",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}