contractor-license-mcp-server 0.6.5 → 0.8.0

package/README.md

@@ -1,12 +1,12 @@
 # contractor-license-mcp-server
 
-**Real-time contractor license verification across 45 US states.** An [MCP server](https://modelcontextprotocol.io) that lets Claude Desktop, Cursor, and any MCP-compatible AI agent verify a contractor's license, status, expiration, and disciplinary history directly against state licensing board portals.
+**Real-time contractor license verification across all 50 US states + DC, plus 8 major-city contractor licensing portals (Chicago, NYC, Philadelphia, Detroit, Atlanta, Dallas, Las Vegas, Nashville).** An [MCP server](https://modelcontextprotocol.io) that lets Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible AI agent verify a contractor's license, status, expiration, and disciplinary history directly against licensing board portals.
 
 Send `{state, license_number, trade}` — get back validity, licensee name, expiration date, status, and any disciplinary actions on file. Results are fetched live from official state portals (no stale nightly exports) and cached for 24 hours when active.
 
 ## Why this server
 
-- **45 states** covered via official state licensing board portals, not third-party data aggregators
+- **All 50 US states + DC + 8 major cities** covered via official licensing board portals, not third-party data aggregators
 - **Live lookups** — each verification hits the authoritative portal, so expirations and disciplinary actions are as fresh as the board's own data
 - **Batch verification** — up to 25 licenses per call, run in parallel
 - **Disciplinary history** — returned when the portal exposes it
@@ -14,13 +14,33 @@ Send `{state, license_number, trade}` — get back validity, licensee name, expi
 
 ## Quick start
 
-### Claude Desktop
+### Hosted (recommended)
 
-Add this to your Claude Desktop config:
+No install required. Add this to your Claude Desktop config:
 
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
+```json
+{
+  "mcpServers": {
+    "tradesapi": {
+      "type": "streamable-http",
+      "url": "https://www.tradesapi.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Replace `YOUR_API_KEY` with the key from your dashboard and restart Claude Desktop.
+
+### Local install (alternative)
+
+If you prefer to run the MCP server locally via stdio:
+
 ```json
 {
   "mcpServers": {
@@ -54,15 +74,16 @@ npm install -g contractor-license-mcp-server
 
 ## Tools
 
-### `clv_verify_license`
+### `verify_license`
 
-Verify a single contractor license against a state licensing board portal.
+Verify a single contractor license against the official state (or city) licensing portal.
 
 | Parameter | Required | Description |
 |---|---|---|
 | `state` | yes | Two-letter state code (`CA`, `TX`, `FL`, ...) |
+| `city` | no | Optional city slug to target a municipal portal: `chicago`, `nyc`, `philadelphia`, `detroit`, `atlanta`, `dallas`, `lasvegas`, `nashville`. Lowercase, no spaces. |
 | `license_number` | yes | The license number to verify |
-| `trade` | no | `general`, `electrical`, `plumbing`, `hvac`, `mechanical`, `residential`, or `home_inspection` (defaults to `general`) |
+| `trade` | no | `general`, `electrical`, `plumbing`, `hvac`, `mechanical`, `roofing`, `residential`, ... (defaults to `general`) |
 | `force_refresh` | no | Bypass the 24h cache and re-fetch from the portal |
 | `response_format` | no | `markdown` (default) or `json` |
 
@@ -81,74 +102,45 @@ Verify a single contractor license against a state licensing board portal.
 | Expiration | 05/12/2026               |
 ```
 
-### `clv_batch_verify`
+### `batch_verify`
 
-Verify up to 25 licenses in a single call. Each verification runs independently — partial failures do not block the batch.
+Verify up to 25 licenses in a single call. Each verification runs independently — partial failures do not block the batch. Per-item `city` is supported.
 
 | Parameter | Required | Description |
 |---|---|---|
-| `licenses` | yes | Array of `{ state, license_number, trade }` objects (1–25 items) |
+| `licenses` | yes | Array of `{ state, city?, license_number, trade }` objects (1–25 items) |
 | `response_format` | no | `markdown` (default) or `json` |
 
-### `clv_list_supported_states`
+### `search_by_name`
 
-List all supported states, including portal URLs and available trades. Use this to see which states and trades you can query.
+Fuzzy-match contractors by business or individual name within a single state (or city) database. Costs 2 credits per call.
 
 | Parameter | Required | Description |
 |---|---|---|
+| `state` | yes | Two-letter state code |
+| `city` | no | Optional city slug for municipal databases |
+| `name` | yes | Business or individual name (case-insensitive, partial-match tolerant) |
+| `trade` | no | Trade filter |
+| `limit` | no | Max results (1–50, default 20) |
 | `response_format` | no | `markdown` (default) or `json` |
 
-## Supported states
+Not every state portal supports name search — call `list_supported_states` and check `supports_name_search` per jurisdiction first.
+
+### `list_supported_states`
 
-| Code | State | Trades |
+List every supported jurisdiction with portal URLs, current health, available trades, and registered municipal scrapers nested under each state. Use this to discover what's reachable before constructing other tool calls.
+
+| Parameter | Required | Description |
 |---|---|---|
-| AK | Alaska | general, electrical, mechanical |
-| AL | Alabama | general, electrical, plumbing, hvac, residential |
-| AR | Arkansas | general |
-| AZ | Arizona | general, electrical, plumbing, hvac |
-| CA | California | general, electrical, plumbing, hvac |
-| CO | Colorado | electrical, plumbing |
-| CT | Connecticut | general, electrical, plumbing, hvac |
-| DC | District of Columbia | general |
-| DE | Delaware | electrical, plumbing, hvac |
-| FL | Florida | general, electrical, plumbing, hvac |
-| GA | Georgia | general |
-| HI | Hawaii | general |
-| IA | Iowa | electrical |
-| ID | Idaho | electrical, plumbing, hvac |
-| IL | Illinois | general, electrical, plumbing, hvac |
-| IN | Indiana | plumbing |
-| KY | Kentucky | general, electrical, hvac, plumbing |
-| LA | Louisiana | general |
-| MA | Massachusetts | general, mechanical |
-| MD | Maryland | general, hvac, electrical, plumbing |
-| ME | Maine | electrical, plumbing |
-| MI | Michigan | electrical, plumbing, hvac |
-| MN | Minnesota | general, electrical, plumbing |
-| MS | Mississippi | general |
-| NC | North Carolina | general |
-| ND | North Dakota | general, electrical |
-| NE | Nebraska | general, electrical |
-| NH | New Hampshire | electrical, plumbing |
-| NJ | New Jersey | general, electrical, hvac, plumbing |
-| NM | New Mexico | general, electrical, plumbing, hvac |
-| NV | Nevada | general, electrical, plumbing, hvac |
-| NY | New York | home_inspection |
-| OH | Ohio | general, electrical, plumbing, hvac |
-| OK | Oklahoma | electrical, plumbing, hvac |
-| OR | Oregon | general |
-| PA | Pennsylvania | general, electrical, hvac, plumbing |
-| RI | Rhode Island | general |
-| SC | South Carolina | general, electrical, plumbing, hvac |
-| TN | Tennessee | general, electrical, plumbing |
-| TX | Texas | hvac, electrical, plumbing |
-| UT | Utah | general, electrical, plumbing, hvac |
-| VA | Virginia | general, electrical, plumbing, hvac |
-| VT | Vermont | electrical, plumbing |
-| WA | Washington | general |
-| WV | West Virginia | general, electrical, hvac, plumbing |
-
-Coverage expands continuously. Run `clv_list_supported_states` from your agent for the current list, or see the live state grid at [www.tradesapi.com](https://www.tradesapi.com).
+| `response_format` | no | `markdown` (default) or `json` |
+
+## Coverage
+
+All 50 US states + DC at the state level, plus 8 major-city contractor licensing portals (Chicago, NYC, Philadelphia, Detroit, Atlanta, Dallas, Las Vegas, Nashville).
+
+Run `list_supported_states` from your agent for the live, fetched-fresh-each-call list of supported jurisdictions, available trades per jurisdiction, current portal health, and which states support name search. The MCP package no longer bundles a static state table — what comes back from `list_supported_states` is always current with prod.
+
+You can also see the live state grid at [www.tradesapi.com](https://www.tradesapi.com).
 
 ## Configuration
 
@@ -164,8 +156,8 @@ Each license verification consumes **1 credit**, whether the result is fresh or
 ## Development
 
 ```bash
-git clone https://github.com/Noquarter6/contractor-license-mcp-server.git
-cd contractor-license-mcp-server
+git clone https://github.com/jackunderwood/Contractor-License-Verification.git
+cd Contractor-License-Verification/mcp-server
 npm install
 npm run build
 npm test

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { LicenseResult, SearchResponse, CreditInfo } from "./types.js";
+import type { BatchItem, BatchResponse, LicenseResult, SearchResponse, StatesApiResponse } from "./types.js";
 export declare class ApiError extends Error {
     statusCode: number;
     retryAfter?: number | undefined;
@@ -6,21 +6,16 @@ export declare class ApiError extends Error {
 }
 export declare class ApiClient {
     private http;
-    constructor(baseURL: string, apiKey: string);
-    verify(state: string, licenseNumber: string, trade: string): Promise<{
-        data: LicenseResult;
-        credits: CreditInfo;
-    }>;
-    search(state: string, name: string, trade: string, limit: number): Promise<{
-        data: SearchResponse;
-        credits: CreditInfo;
-    }>;
+    constructor(baseURL: string, apiKey: string, extraHeaders?: Record<string, string>);
+    verify(state: string, licenseNumber: string, trade: string, city?: string, forceRefresh?: boolean): Promise<LicenseResult>;
+    batch(items: BatchItem[]): Promise<BatchResponse>;
+    search(state: string, name: string, trade: string, limit: number, city?: string): Promise<SearchResponse>;
     health(): Promise<{
         status: string;
         api: string;
         database: string;
         redis: string;
     }>;
-    private parseCredits;
+    states(): Promise<StatesApiResponse>;
     private wrapError;
 }

package/dist/api.js

@@ -11,30 +11,57 @@ export class ApiError extends Error {
 }
 export class ApiClient {
     http;
-    constructor(baseURL, apiKey) {
+    constructor(baseURL, apiKey, extraHeaders = {}) {
+        const headers = { ...extraHeaders };
+        if (apiKey)
+            headers["X-API-Key"] = apiKey;
         this.http = axios.create({
             baseURL,
-            headers: { "X-API-Key": apiKey },
-            timeout: 120_000, // Portal lookups can be slow
+            headers,
+            timeout: 120_000,
         });
     }
-    async verify(state, licenseNumber, trade) {
+    async verify(state, licenseNumber, trade, city, forceRefresh) {
         try {
-            const resp = await this.http.get("/verify", {
-                params: { state, license: licenseNumber, trade },
-            });
-            return { data: resp.data, credits: this.parseCredits(resp.headers) };
+            const params = { state, license: licenseNumber, trade };
+            if (city)
+                params.city = city;
+            if (forceRefresh)
+                params.fresh = "true";
+            const { data } = await this.http.get("/verify", { params });
+            return data;
+        }
+        catch (err) {
+            throw this.wrapError(err);
+        }
+    }
+    async batch(items) {
+        try {
+            const body = {
+                licenses: items.map((it) => ({
+                    state: it.state,
+                    ...(it.city ? { city: it.city } : {}),
+                    license: it.license,
+                    trade: it.trade,
+                })),
+            };
+            const { data } = await this.http.post("/batch", body);
+            return {
+                summary: { total: data.total, succeeded: data.succeeded, failed: data.failed },
+                results: data.results,
+            };
         }
         catch (err) {
             throw this.wrapError(err);
         }
     }
-    async search(state, name, trade, limit) {
+    async search(state, name, trade, limit, city) {
         try {
-            const resp = await this.http.get("/search", {
-                params: { state, name, trade, limit },
-            });
-            return { data: resp.data, credits: this.parseCredits(resp.headers) };
+            const params = { state, name, trade, limit };
+            if (city)
+                params.city = city;
+            const { data } = await this.http.get("/search", { params });
+            return data;
         }
         catch (err) {
             throw this.wrapError(err);
@@ -49,20 +76,21 @@ export class ApiClient {
             throw this.wrapError(err);
         }
     }
-    parseCredits(headers) {
-        const remaining = headers?.["x-credits-remaining"];
-        const charged = headers?.["x-credits-charged"];
-        return {
-            remaining: remaining != null ? parseInt(remaining, 10) : null,
-            charged: charged != null ? parseInt(charged, 10) : null,
-        };
+    async states() {
+        try {
+            const { data } = await this.http.get("/states");
+            return data;
+        }
+        catch (err) {
+            throw this.wrapError(err);
+        }
     }
     wrapError(err) {
         if (err.isAxiosError && err.response) {
             const { status, data, headers } = err.response;
             const detail = data?.detail ?? "Unknown error";
             if (status === 401) {
-                return new ApiError("Authentication failed — check your CLV_API_KEY environment variable. Get a key at https://www.tradesapi.com", 401);
+                return new ApiError("Authentication failed — check your CLV_API_KEY environment variable", 401);
             }
             if (status === 429) {
                 const retryAfter = parseInt(headers?.["retry-after"] ?? "60", 10);
@@ -72,7 +100,7 @@ export class ApiClient {
                 return new ApiError(detail, 400);
             }
             if (status === 502) {
-                return new ApiError(`Verification temporarily unavailable — the state portal may be down. Try again in a few minutes.`, 502);
+                return new ApiError("Verification temporarily unavailable. Try again in a few minutes.", 502);
             }
             return new ApiError(detail, status);
         }

package/dist/format.d.ts

@@ -1,5 +1,4 @@
-import type { LicenseResult, StateInfo, BatchResponse, SearchResponse, CreditInfo } from "./types.js";
-export declare function formatCredits(credits: CreditInfo): string;
+import type { LicenseResult, StateInfo, BatchResponse, SearchResponse } from "./types.js";
 export declare function formatLicenseResult(result: LicenseResult, format: "markdown" | "json"): string;
 export declare function formatStatesList(states: StateInfo[], format: "markdown" | "json"): string;
 export declare function formatBatchResponse(batch: BatchResponse, format: "markdown" | "json"): string;

package/dist/format.js

@@ -1,21 +1,3 @@
-function normalizeStatus(status) {
-    if (!status)
-        return "N/A";
-    const s = status.toLowerCase();
-    if (s === "not_found" || s === "not found")
-        return "Not Found";
-    if (s === "unknown")
-        return "Unknown (lookup may have failed)";
-    return status;
-}
-export function formatCredits(credits) {
-    const parts = [];
-    if (credits.charged != null)
-        parts.push(`Credits used: ${credits.charged}`);
-    if (credits.remaining != null)
-        parts.push(`Credits remaining: ${credits.remaining}`);
-    return parts.length > 0 ? `\n\n---\n${parts.join(" | ")}` : "";
-}
 export function formatLicenseResult(result, format) {
     if (format === "json") {
         return JSON.stringify(result, null, 2);
@@ -30,7 +12,7 @@ export function formatLicenseResult(result, format) {
         `| License # | ${result.license_number} |`,
         `| State | ${result.state} |`,
         `| Trade | ${result.trade} |`,
-        `| Status | ${normalizeStatus(result.status)} |`,
+        `| Status | ${result.status ?? "N/A"} |`,
         `| Expiration | ${result.expiration ?? "N/A"} |`,
         `| Source | ${result.source_url ?? "N/A"} |`,
         `| Cached | ${result.cached ? "Yes" : "No"} |`,
@@ -39,36 +21,53 @@ export function formatLicenseResult(result, format) {
     if (result.disciplinary_actions.length > 0) {
         lines.push("", "### Disciplinary Actions");
         for (const action of result.disciplinary_actions) {
-            if (typeof action === "string") {
-                lines.push(`- ${action}`);
-            }
-            else if (action && typeof action === "object" && "description" in action) {
-                lines.push(`- ${action.description}`);
-            }
-            else {
-                lines.push(`- ${JSON.stringify(action)}`);
-            }
+            lines.push(`- ${action}`);
         }
     }
     return lines.join("\n");
 }
+function statusIcon(status) {
+    switch (status) {
+        case "healthy":
+            return "OK";
+        case "degraded":
+            return "DEGRADED";
+        case "maintenance":
+            return "MAINTENANCE";
+        default:
+            return "DOWN";
+    }
+}
 export function formatStatesList(states, format) {
+    const allMunis = states.flatMap((s) => s.municipalities ?? []);
     if (format === "json") {
-        return JSON.stringify({ states, total: states.length }, null, 2);
+        return JSON.stringify({
+            total_states: states.length,
+            total_municipalities: allMunis.length,
+            states,
+        }, null, 2);
     }
+    const header = allMunis.length > 0
+        ? `## Supported Jurisdictions (${states.length} states + ${allMunis.length} cities)`
+        : `## Supported States (${states.length} states)`;
     const lines = [
-        `## Supported States (${states.length} states)`,
+        header,
+        "",
+        "### States",
         "",
         "| State | Name | Status | Trades |",
         "|-------|------|--------|--------|",
     ];
     for (const s of states) {
-        const statusIcon = s.status === "healthy"
-            ? "OK"
-            : s.status === "degraded"
-                ? "DEGRADED"
-                : "DOWN";
-        lines.push(`| ${s.code} | ${s.name} | ${statusIcon} | ${s.trades.join(", ")} |`);
+        lines.push(`| ${s.code} | ${s.name} | ${statusIcon(s.status)} | ${s.trades.join(", ")} |`);
+    }
+    if (allMunis.length > 0) {
+        lines.push("", "### Cities (municipal scrapers)", "");
+        lines.push("| Code | City | Parent State | Status | Trades |");
+        lines.push("|------|------|--------------|--------|--------|");
+        for (const m of allMunis) {
+            lines.push(`| ${m.code} | ${m.city} | ${m.parent_state} | ${statusIcon(m.status)} | ${m.trades.join(", ")} |`);
+        }
     }
     return lines.join("\n");
 }
@@ -89,7 +88,7 @@ export function formatBatchResponse(batch, format) {
             if (item.result.name)
                 lines.push(`Name: ${item.result.name}`);
             if (item.result.status)
-                lines.push(`Status: ${normalizeStatus(item.result.status)}`);
+                lines.push(`Status: ${item.result.status}`);
             lines.push("");
         }
         else {

package/dist/http.d.ts

@@ -0,0 +1,9 @@
+export interface AuthResult {
+    /** api_key_id when authenticated via JWT, or undefined when authenticated via raw API key */
+    apiKeyId?: string;
+    /** Raw token (either JWT or raw API key) — used to build ApiClient */
+    token: string;
+    /** True if this was a JWT (and therefore Node uses X-Internal-Secret + X-Api-Key-Id when calling FastAPI) */
+    isJwt: boolean;
+}
+export declare function sessionIdentity(auth: AuthResult): string;