@matchuplabs/nycfhv-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,18 +1,166 @@
 # @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.
+MCP server that exposes the [NYC FHV Intelligence API](https://fhv.matchup.dev) — real-time TLC for-hire-vehicle license verification and renewal-window lookups — as Claude, Cursor, Windsurf, and VS Code agent tools.
+
+Data source: NYC TLC's [For-Hire Vehicles - Active dataset](https://data.cityofnewyork.us/Transportation/For-Hire-Vehicles-FHV-Active/8wbx-tsch), refreshed daily 4–7 PM ET. Public record under NY State FOIL.
+
+## 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.
+
+The API also correctly handles wheelchair-accessible (WAV) status — Socrata returns the WAV column as `"WAV"` / `"PILOT"` / absent (not `"YES"` / `"NO"`), and most wrappers silently misclassify the ~8,400-vehicle WAV cohort. This one doesn't.
 
 ## 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 |
+| `verify_tlc_vehicle` | Verify an FHV by TLC license, DMV plate, or VIN. | 1 credit |
+| `list_upcoming_renewals` | Vehicles whose license expires in the next N days. | 5 credits / page |
+| `subscribe_renewal_webhook` | Daily push notifications for renewal-window deltas. | 0 to create, 1 / event |
+
+### `verify_tlc_vehicle`
+
+Verify whether a NYC TLC for-hire vehicle is currently licensed. Read-only.
+
+**Inputs**
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `identifier` | string | yes | TLC license (`C05015` or `5545596`), DMV plate (`T438350C`), or 17-char VIN. |
+| `type` | `"auto" \| "license" \| "plate" \| "vin"` | no | Override auto-detection. Default `"auto"`. |
+
+**Auto-detection rules**
+
+- 17 alphanumeric chars → VIN
+- One letter + five digits (e.g., `C05015`) → TLC license number
+- Otherwise → DMV plate
+
+**Example response**
+
+```json
+{
+  "data": {
+    "active": true,
+    "vehicle_license_number": "5545596",
+    "name": "OPERATOR NAME",
+    "license_type": "FHV",
+    "expiration_date": "2026-08-14",
+    "days_until_expiration": 95,
+    "permit_license_number": "B03404",
+    "dmv_license_plate_number": "T438350C",
+    "vehicle_vin_number": "1FADP3K20JL215555",
+    "wheelchair_accessible": false,
+    "vehicle_year": 2018,
+    "base_number": "B03404",
+    "base_name": "UBER USA, LLC",
+    "base_type": "Black Car"
+  },
+  "meta": {
+    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
+    "updated": "2026-05-11T22:14:00Z",
+    "credits_remaining": 4998
+  }
+}
+```
+
+**Error shape** (any tool)
+
+```json
+{
+  "error": {
+    "code": "not_found",
+    "message": "No active TLC record matches that identifier.",
+    "suggested_next_step": "Confirm the identifier with the operator or try a different type."
+  }
+}
+```
+
+### `list_upcoming_renewals`
 
-## Quickstart
+List vehicles whose license expires within the next N days. Read-only. Paginated.
+
+**Inputs**
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `days` | integer (1–180) | yes | Renewal window from today, inclusive. |
+| `base_number` | string | no | TLC base filter (e.g., `B03404` = Uber). |
+| `wheelchair_accessible` | boolean | no | `true` = WAV only, `false` = non-WAV only, omit for both. |
+| `vehicle_year_max` | integer | no | Max model year — fleet-aging targeting. |
+| `page` | integer | no | 1-indexed. Default 1. |
+| `page_size` | integer (10–100) | no | Default 50. |
+
+**Example response**
+
+```json
+{
+  "data": [
+    {
+      "active": true,
+      "vehicle_license_number": "5545596",
+      "name": "OPERATOR NAME",
+      "expiration_date": "2026-06-01",
+      "days_until_expiration": 21,
+      "wheelchair_accessible": true,
+      "vehicle_year": 2017,
+      "base_number": "B03404",
+      "base_name": "UBER USA, LLC"
+    }
+  ],
+  "meta": {
+    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
+    "updated": "2026-05-11T22:14:00Z",
+    "page": 1,
+    "page_size": 50,
+    "total_count": 412,
+    "credits_remaining": 4993
+  }
+}
+```
+
+### `subscribe_renewal_webhook`
+
+Subscribe a webhook URL to daily renewal-window deltas. Each day after the TLC dataset refresh, the API diffs newly-entered renewal-window vehicles against yesterday's snapshot and POSTs the delta. Events are HMAC-SHA256-signed via the `signing_secret` returned at creation.
+
+**Inputs**
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| `webhook_url` | string (HTTPS) | yes | Endpoint to receive daily POST events. |
+| `days` | integer (1–180) | no | Renewal window. Default 30. |
+| `base_number` | string | no | Filter to one TLC base. |
+| `wheelchair_accessible` | boolean | no | WAV-only or non-WAV-only filter. |
+| `vehicle_year_max` | integer | no | Max model year filter. |
+| `description` | string (≤200) | no | Human-readable label. |
+
+**Example response**
+
+```json
+{
+  "data": {
+    "id": "sub_01HXYZ...",
+    "status": "active",
+    "signing_secret": "whsec_...",
+    "webhook_url": "https://example.com/fhv-webhook",
+    "filter": { "days": 30, "base_number": "B03404" },
+    "created_at": "2026-05-11T22:14:00Z"
+  },
+  "meta": {
+    "source": "matchuplabs/fhv-intelligence/subscriptions"
+  },
+  "important": "Store the signing_secret securely — it is only returned once. Use it to verify the X-FHV-Signature header on incoming webhook events."
+}
+```
+
+## Install
 
 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):
+2. Add the config block below to your MCP host.
+3. Restart the host. The three tools appear in the tool picker.
+
+### Claude Desktop
+
+Config path: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
 
 ```json
 {
@@ -28,20 +176,75 @@ MCP server that exposes the [NYC FHV Intelligence API](https://fhv.matchup.dev)
 }
 ```
 
-3. Restart Claude Desktop. The two tools appear in the tool picker.
+### Cursor
 
-## Environment
+Config path: `~/.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json` (per-project).
 
-| Variable | Required | Default |
-|---|---|---|
-| `FHV_API_KEY` | Yes | — |
-| `FHV_BASE_URL` | No | `https://fhv.matchup.dev` |
+```json
+{
+  "mcpServers": {
+    "nycfhv": {
+      "command": "npx",
+      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
+      "env": {
+        "FHV_API_KEY": "mv_live_your_key_here"
+      }
+    }
+  }
+}
+```
 
-## Why this exists
+### VS Code (with Copilot MCP)
 
-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.
+Config path: `<project>/.vscode/mcp.json`.
+
+```json
+{
+  "servers": {
+    "nycfhv": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
+      "env": {
+        "FHV_API_KEY": "mv_live_your_key_here"
+      }
+    }
+  }
+}
+```
 
-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.
+### Windsurf
+
+Config path: `~/.codeium/windsurf/mcp_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "nycfhv": {
+      "command": "npx",
+      "args": ["-y", "@matchuplabs/nycfhv-mcp"],
+      "env": {
+        "FHV_API_KEY": "mv_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add nycfhv -- npx -y @matchuplabs/nycfhv-mcp
+```
+
+Then set `FHV_API_KEY` in your shell or via `claude mcp` env config.
+
+## Environment
+
+| Variable | Required | Default |
+|---|---|---|
+| `FHV_API_KEY` | yes | — |
+| `FHV_BASE_URL` | no | `https://fhv.matchup.dev` |
 
 ## Development
 
@@ -52,6 +255,12 @@ npm run build
 npm test
 ```
 
+## Links
+
+- [API docs](https://fhv.matchup.dev)
+- [Source (api-ventures monorepo)](https://github.com/MATCHUP-LABS/api-ventures/tree/main/products/nyc-fhv-intelligence-api/mcp-server)
+- [Report issues](https://github.com/MATCHUP-LABS/api-ventures/issues)
+
 ## License
 
 MIT. © Matchup Labs.

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

@@ -52,4 +52,25 @@ export declare class FhvClient {
         page?: number;
         page_size?: number;
     }): Promise<FhvResult<Vehicle[]>>;
+    /** POST /api/v1/renewals/subscriptions */
+    createSubscription(params: {
+        webhook_url: string;
+        filter: {
+            days?: number;
+            base_number?: string;
+            wheelchair_accessible?: boolean;
+            vehicle_year_max?: number;
+        };
+        description?: string;
+    }): Promise<FhvResult<Subscription>>;
+}
+export interface Subscription {
+    id: string;
+    webhook_url: string;
+    filter: Record<string, unknown>;
+    description?: string;
+    signing_secret: string;
+    status: "active" | "paused" | "failed";
+    created_at: string;
+    last_delivery_at: string | null;
 }

package/dist/lib/fhv-client.js

@@ -53,22 +53,28 @@ export class FhvClient {
             return lastResponse;
         throw lastError ?? new Error("retryFetch exhausted retries");
     }
-    async request(path, params = {}) {
+    async request(path, params = {}, options) {
+        const method = options?.method ?? "GET";
         const url = new URL(path, this.baseUrl);
-        for (const [k, v] of Object.entries(params)) {
-            if (v !== undefined)
-                url.searchParams.set(k, String(v));
+        if (method === "GET") {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": "nycfhv-mcp/0.1.0",
+        };
+        const init = { method, headers };
+        if (options?.jsonBody !== undefined) {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(options.jsonBody);
         }
         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",
-                },
-            });
+            response = await this.retryFetch(url.toString(), init);
         }
         catch (err) {
             return mcpError("upstream_timeout", `Request to fhv.matchup.dev failed: ${err instanceof Error ? err.message : String(err)}`, "Check network connectivity and retry.");
@@ -94,4 +100,11 @@ export class FhvClient {
     listUpcomingRenewals(params) {
         return this.request(`/api/v1/renewals/upcoming`, params);
     }
+    /** POST /api/v1/renewals/subscriptions */
+    createSubscription(params) {
+        return this.request(`/api/v1/renewals/subscriptions`, {}, {
+            method: "POST",
+            jsonBody: params,
+        });
+    }
 }

package/dist/server-core.js

@@ -2,10 +2,11 @@ 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";
+import { TOOL_DEFINITION as subscribeDef, TOOL_NAME as subscribeName, subscribeRenewalWebhook, } from "./tools/subscribe-renewal-webhook.js";
 export function createServer() {
-    const server = new Server({ name: "nycfhv", version: "0.1.0" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "nycfhv", version: "0.1.1" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [verifyDef, renewalsDef],
+        tools: [verifyDef, renewalsDef, subscribeDef],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -19,6 +20,10 @@ export function createServer() {
                     const text = await listUpcomingRenewals((args ?? {}));
                     return { content: [{ type: "text", text }] };
                 }
+                case subscribeName: {
+                    const text = await subscribeRenewalWebhook((args ?? {}));
+                    return { content: [{ type: "text", text }] };
+                }
                 default:
                     return {
                         content: [

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

@@ -2,6 +2,13 @@ export declare const TOOL_NAME = "list_upcoming_renewals";
 export declare const TOOL_DEFINITION: {
     name: string;
     description: string;
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     inputSchema: {
         type: "object";
         properties: {

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

@@ -3,6 +3,13 @@ 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).",
+    annotations: {
+        title: "List Upcoming TLC Renewals",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/subscribe-renewal-webhook.d.ts

@@ -0,0 +1,53 @@
+export declare const TOOL_NAME = "subscribe_renewal_webhook";
+export declare const TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            webhook_url: {
+                type: string;
+                description: string;
+            };
+            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;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export interface SubscribeRenewalWebhookArgs {
+    webhook_url: string;
+    days?: number;
+    base_number?: string;
+    wheelchair_accessible?: boolean;
+    vehicle_year_max?: number;
+    description?: string;
+}
+export declare function subscribeRenewalWebhook(args: SubscribeRenewalWebhookArgs): Promise<string>;

package/dist/tools/subscribe-renewal-webhook.js

@@ -0,0 +1,84 @@
+import { FhvClient } from "../lib/fhv-client.js";
+export const TOOL_NAME = "subscribe_renewal_webhook";
+export const TOOL_DEFINITION = {
+    name: TOOL_NAME,
+    description: "Subscribe a webhook URL to daily FHV renewal-window notifications. Each day after the TLC dataset refresh (~4-7 PM ET), the API diffs newly-entered renewal-window vehicles against yesterday's snapshot and POSTs the delta to your webhook. Payload is signed with HMAC-SHA256 via the signing_secret returned at creation. Costs 0 credits to create; 1 credit per delivered event.",
+    annotations: {
+        title: "Subscribe to Renewal Webhook",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            webhook_url: {
+                type: "string",
+                description: "HTTPS endpoint that will receive daily POST events with renewal-window vehicle deltas.",
+            },
+            days: {
+                type: "integer",
+                description: "Renewal window from today, 1-180 days. Vehicles entering this window trigger an event. Default 30.",
+                minimum: 1,
+                maximum: 180,
+            },
+            base_number: {
+                type: "string",
+                description: "Optional TLC base filter (e.g., 'B03404' = Uber). Only vehicles from this base trigger events.",
+            },
+            wheelchair_accessible: {
+                type: "boolean",
+                description: "If set, only WAV (true) or non-WAV (false) vehicles trigger events.",
+            },
+            vehicle_year_max: {
+                type: "integer",
+                description: "Optional max model year filter for fleet-aging targeting.",
+            },
+            description: {
+                type: "string",
+                description: "Optional human-readable label for this subscription (max 200 chars).",
+            },
+        },
+        required: ["webhook_url"],
+    },
+};
+export async function subscribeRenewalWebhook(args) {
+    if (!args.webhook_url || typeof args.webhook_url !== "string") {
+        return JSON.stringify({
+            error: {
+                code: "invalid_input",
+                message: "`webhook_url` is required and must be an HTTPS URL.",
+                suggested_next_step: "Provide a valid HTTPS webhook endpoint.",
+            },
+        });
+    }
+    const client = new FhvClient();
+    const result = await client.createSubscription({
+        webhook_url: args.webhook_url,
+        filter: {
+            days: args.days,
+            base_number: args.base_number,
+            wheelchair_accessible: args.wheelchair_accessible,
+            vehicle_year_max: args.vehicle_year_max,
+        },
+        description: args.description,
+    });
+    if ("error" in result) {
+        return JSON.stringify(result);
+    }
+    return JSON.stringify({
+        data: {
+            id: result.data.id,
+            status: result.data.status,
+            signing_secret: result.data.signing_secret,
+            webhook_url: result.data.webhook_url,
+            filter: result.data.filter,
+            created_at: result.data.created_at,
+        },
+        meta: {
+            source: result.meta.source,
+        },
+        important: "Store the signing_secret securely — it is only returned once. Use it to verify the X-FHV-Signature header on incoming webhook events.",
+    });
+}

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

@@ -2,6 +2,13 @@ export declare const TOOL_NAME = "verify_tlc_vehicle";
 export declare const TOOL_DEFINITION: {
     name: string;
     description: string;
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     inputSchema: {
         type: "object";
         properties: {

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

@@ -3,6 +3,13 @@ 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.",
+    annotations: {
+        title: "Verify TLC Vehicle",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     inputSchema: {
         type: "object",
         properties: {

package/llms-full.txt

@@ -0,0 +1,264 @@
+# @matchuplabs/nycfhv-mcp — Full Reference for LLMs
+
+This is a single-file dump of everything an LLM needs to plan tool use against the NYC FHV Intelligence MCP server. Includes per-tool input schemas, response shapes, error semantics, and the cost model.
+
+Package: `@matchuplabs/nycfhv-mcp` (npm)
+Server name: `io.github.MatchupLabs/nycfhv`
+Transport: stdio
+Source: https://github.com/MATCHUP-LABS/api-ventures/tree/main/products/nyc-fhv-intelligence-api/mcp-server
+
+## Environment variables
+
+- `FHV_API_KEY` (required, secret) — get one at matchuplabs.com, product slug `fhv-intelligence`.
+- `FHV_BASE_URL` (optional) — defaults to `https://fhv.matchup.dev`.
+
+## Cost model
+
+| Operation | Credits |
+|---|---|
+| `verify_tlc_vehicle` call | 1 |
+| `list_upcoming_renewals` page | 5 |
+| `subscribe_renewal_webhook` create | 0 |
+| Webhook event delivery | 1 |
+| Edge-cached repeat call within TTL | 0 |
+
+Credits are charged only on successful responses. The remaining balance is in `meta.credits_remaining` on every response.
+
+## Identifier auto-detection (verify_tlc_vehicle)
+
+- 17 alphanumeric characters → VIN
+- One letter followed by five digits (e.g., `C05015`) → TLC license number (legacy format)
+- 7-digit numeric (e.g., `5545596`) → TLC license number (current format)
+- Otherwise → DMV plate
+
+Override via `type: "license" | "plate" | "vin"`.
+
+## Tools
+
+### Tool 1: verify_tlc_vehicle
+
+Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
+
+Description: Verify whether a NYC TLC for-hire vehicle is currently licensed. Use before authorizing a livery rate, dispatching a Medicaid NEMT trip, or pre-binding insurance.
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "identifier": {
+      "type": "string",
+      "description": "TLC license number (legacy 'C05015' or 7-digit '5545596'), DMV plate, or 17-char VIN."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["auto", "license", "plate", "vin"],
+      "description": "Optional override for identifier auto-detection. Default 'auto'."
+    }
+  },
+  "required": ["identifier"]
+}
+```
+
+Success response shape:
+
+```json
+{
+  "data": {
+    "active": "boolean",
+    "vehicle_license_number": "string",
+    "name": "string (operator name)",
+    "license_type": "string",
+    "expiration_date": "string (YYYY-MM-DD)",
+    "days_until_expiration": "number (can be negative if expired)",
+    "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 (TLC base, e.g. 'B03404')",
+    "base_name": "string | null (e.g. 'UBER USA, LLC')",
+    "base_type": "string | null (e.g. 'Black Car', 'Livery', 'Luxury Limousine')"
+  },
+  "meta": {
+    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
+    "updated": "ISO 8601 timestamp",
+    "credits_remaining": "number"
+  }
+}
+```
+
+### Tool 2: list_upcoming_renewals
+
+Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: true`.
+
+Description: List vehicles whose license expires within the next N days. Paginated. Use for renewal-window lead lists (license expediters, insurance brokers, training schools, EV/hybrid dealer prospecting).
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "days": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 180,
+      "description": "Renewal window from today, inclusive. Most use cases pick 14, 30, 60, or 90."
+    },
+    "base_number": {
+      "type": "string",
+      "description": "Optional TLC base filter (case-insensitive). Example: 'B03404' = Uber, 'B00477' = Inta-Boro Acres."
+    },
+    "wheelchair_accessible": {
+      "type": "boolean",
+      "description": "true = WAV / WAV-pilot only (~8% of fleet). false = non-WAV only. Omit for both."
+    },
+    "vehicle_year_max": {
+      "type": "integer",
+      "description": "Optional max model year. Targets older fleet for replacement-financing or pre-sales lead-gen."
+    },
+    "page": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "1-indexed page number. Default 1."
+    },
+    "page_size": {
+      "type": "integer",
+      "minimum": 10,
+      "maximum": 100,
+      "description": "Results per page. Default 50."
+    }
+  },
+  "required": ["days"]
+}
+```
+
+Success response shape:
+
+```json
+{
+  "data": "Array<Vehicle> (same shape as verify_tlc_vehicle.data, one per vehicle)",
+  "meta": {
+    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
+    "updated": "ISO 8601 timestamp",
+    "page": "number",
+    "page_size": "number",
+    "total_count": "number (total matching the filter, not just this page)",
+    "credits_remaining": "number"
+  }
+}
+```
+
+### Tool 3: subscribe_renewal_webhook
+
+Annotations: `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true`.
+
+Description: Subscribe a webhook URL to daily FHV renewal-window notifications. After each daily TLC dataset refresh (~4–7 PM ET), the API diffs newly-entered renewal-window vehicles against yesterday's snapshot and POSTs the delta to the webhook. Events are HMAC-SHA256 signed via the `signing_secret` returned at creation.
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "webhook_url": {
+      "type": "string",
+      "description": "HTTPS endpoint that will receive daily POST events."
+    },
+    "days": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 180,
+      "description": "Renewal window from today. Default 30."
+    },
+    "base_number": {
+      "type": "string",
+      "description": "Optional TLC base filter."
+    },
+    "wheelchair_accessible": {
+      "type": "boolean",
+      "description": "WAV-only (true) or non-WAV-only (false) filter."
+    },
+    "vehicle_year_max": {
+      "type": "integer",
+      "description": "Max model year filter."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional human-readable label, max 200 chars."
+    }
+  },
+  "required": ["webhook_url"]
+}
+```
+
+Success response shape:
+
+```json
+{
+  "data": {
+    "id": "string (subscription id)",
+    "status": "active | paused | failed",
+    "signing_secret": "string (ONLY RETURNED ONCE — store securely)",
+    "webhook_url": "string",
+    "filter": "object (echo of input filter params)",
+    "created_at": "ISO 8601 timestamp"
+  },
+  "meta": {
+    "source": "matchuplabs/fhv-intelligence/subscriptions"
+  },
+  "important": "Store the signing_secret securely — it is only returned once. Use it to verify the X-FHV-Signature header on incoming webhook events."
+}
+```
+
+Webhook event payload (delivered daily to the registered URL):
+
+```json
+{
+  "event": "renewal_window.delta",
+  "subscription_id": "sub_...",
+  "delivered_at": "ISO 8601",
+  "data": {
+    "added": "Array<Vehicle>",
+    "removed": "Array<Vehicle>"
+  },
+  "meta": {
+    "source": "nyc-open-data/tlc-fhv-active/8wbx-tsch",
+    "snapshot_date": "YYYY-MM-DD"
+  }
+}
+```
+
+Signature header: `X-FHV-Signature: sha256=<hex digest of body using signing_secret>`.
+
+## Error semantics (all tools)
+
+Every error follows this shape:
+
+```json
+{
+  "error": {
+    "code": "string (machine-readable: 'invalid_input' | 'not_found' | 'auth_failed' | 'rate_limited' | 'credits_exhausted' | 'upstream_unavailable' | 'internal_error')",
+    "message": "string (human-readable)",
+    "suggested_next_step": "string (actionable guidance for the agent)"
+  }
+}
+```
+
+Common codes:
+
+- `invalid_input` — bad/missing param. Re-check input schema.
+- `not_found` — verify_tlc_vehicle: no matching active record. Vehicle may be inactive, mistyped, or never licensed.
+- `auth_failed` — bad/missing FHV_API_KEY.
+- `rate_limited` — too many requests for the current tier. Back off.
+- `credits_exhausted` — out of credits. Upgrade tier or wait for monthly reset.
+- `upstream_unavailable` — NYC Socrata is down or refreshing. Retry in 5–10 min.
+
+## Use-case primers
+
+- **NEMT Medicaid trip dispatch**: before assigning a trip, call `verify_tlc_vehicle` with the assigned vehicle's plate or TLC number. Confirm `active: true` and (for WAV-required trips) `wheelchair_accessible: true`. If false, route the trip to a different vehicle.
+- **Livery insurance pre-bind**: call `verify_tlc_vehicle`; deny binding if `active: false` or `days_until_expiration < 7`.
+- **Renewal-window lead-gen**: call `list_upcoming_renewals` with `days: 30`, optionally filtered by base or `vehicle_year_max` (for replacement-financing pitches). Paginate.
+- **Fleet monitoring**: call `subscribe_renewal_webhook` once with your base filter; receive a daily delta of vehicles entering the renewal window without polling.

package/llms.txt

@@ -0,0 +1,25 @@
+# @matchuplabs/nycfhv-mcp
+
+> MCP server for the NYC FHV Intelligence API. Verifies NYC TLC for-hire vehicle licenses (by TLC number, DMV plate, or VIN) and lists renewal-window leads. Backed by fhv.matchup.dev, daily-refreshed from NYC TLC's official For-Hire Vehicles - Active dataset (8wbx-tsch). Public-record data under NY State FOIL.
+
+The MCP exposes 3 tools:
+
+- `verify_tlc_vehicle` — read-only, 1 credit. Verify whether a vehicle is currently TLC-active by license, plate, or VIN. Returns active status, expiration, base affiliation, and wheelchair-accessible (WAV) flag.
+- `list_upcoming_renewals` — read-only, 5 credits/page. Paginated list of vehicles whose license expires in the next N days. Filterable by base, WAV status, and vehicle model year.
+- `subscribe_renewal_webhook` — write, 0 credits to create + 1 credit per delivered event. Subscribes a webhook URL to daily renewal-window deltas, HMAC-SHA256 signed.
+
+Use cases: NEMT fleet pre-dispatch verification, livery dispatch authorization, insurance pre-bind, fleet-aging targeting for dealer/financing lead-gen, license-expediter prospecting.
+
+## Install
+
+- [README](https://github.com/MATCHUP-LABS/api-ventures/blob/main/products/nyc-fhv-intelligence-api/mcp-server/README.md): full install configs for Claude Desktop, Cursor, VS Code, Windsurf, Claude Code CLI.
+- [Full schemas](https://github.com/MATCHUP-LABS/api-ventures/blob/main/products/nyc-fhv-intelligence-api/mcp-server/llms-full.txt): single-file dump of every tool definition + response shape.
+
+## Get an API key
+
+- [matchuplabs.com](https://matchuplabs.com) — product slug `fhv-intelligence`. Free tier available.
+
+## Optional
+
+- [API docs](https://fhv.matchup.dev): underlying HTTP API the MCP wraps.
+- [Source](https://github.com/MATCHUP-LABS/api-ventures/tree/main/products/nyc-fhv-intelligence-api/mcp-server): TypeScript, MIT license.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matchuplabs/nycfhv-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -11,10 +11,16 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/MATCHUP-LABS/nycfhv.git",
-    "directory": "mcp-server"
+    "url": "https://github.com/MATCHUP-LABS/api-ventures.git",
+    "directory": "products/nyc-fhv-intelligence-api/mcp-server"
   },
   "homepage": "https://fhv.matchup.dev",
+  "bugs": {
+    "url": "https://github.com/MATCHUP-LABS/api-ventures/issues"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -24,12 +30,21 @@
     "fhv",
     "license-verification",
     "rideshare",
-    "ai-agent"
+    "ai-agent",
+    "nemt",
+    "fleet-management",
+    "compliance",
+    "wheelchair-accessible",
+    "wav",
+    "government-data",
+    "transportation"
   ],
   "files": [
     "dist",
     "server.json",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "scripts": {
     "build": "tsc",

package/server.json

@@ -3,17 +3,18 @@
   "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",
+  "version": "0.1.1",
   "repository": {
-    "url": "https://github.com/MATCHUP-LABS/nycfhv",
-    "source": "github"
+    "url": "https://github.com/MATCHUP-LABS/api-ventures",
+    "source": "github",
+    "subfolder": "products/nyc-fhv-intelligence-api/mcp-server"
   },
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@matchuplabs/nycfhv-mcp",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "transport": {
         "type": "stdio"
       },