contractor-license-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# contractor-license-mcp-server
+
+An [MCP server](https://modelcontextprotocol.io) for verifying US contractor licenses. Send a license number, state, and trade -- get back validity, expiration, status, and disciplinary history. Works with Claude Desktop and any MCP-compatible AI agent.
+
+Currently supports **Texas (TDLR)**, **California (CSLB)**, and **Florida (DBPR)**, with more states coming.
+
+## Quick Start
+
+### Claude Desktop
+
+Add this to your Claude Desktop config file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "contractor-license-verification": {
+      "command": "npx",
+      "args": ["-y", "contractor-license-mcp-server"],
+      "env": {
+        "CLV_API_URL": "https://contractor-license-verification-production.up.railway.app",
+        "CLV_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the config.
+
+### Getting an API Key
+
+New accounts start with **50 free verification credits**. To get your API key:
+
+1. Visit the [billing portal](https://contractor-license-verification-production.up.railway.app/billing/checkout) to create an account
+2. Your API key will be provided on signup
+3. Need more credits? Purchase additional packs at the same billing portal
+
+### Direct Install
+
+```bash
+npm install -g contractor-license-mcp-server
+```
+
+## Available Tools
+
+### `clv_verify_license`
+
+Verify a single contractor license against a state licensing board portal.
+
+**Parameters:**
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `state` | Yes | Two-letter state code (e.g. `CA`, `TX`, `FL`) |
+| `license_number` | Yes | The license number to verify |
+| `trade` | No | Trade type (default: `general`) |
+| `force_refresh` | No | Bypass cache for fresh data (default: `false`) |
+| `response_format` | No | `markdown` or `json` (default: `markdown`) |
+
+**Example result:**
+
+```
+## License Verification: VALID
+
+| Field      | Value                    |
+|------------|--------------------------|
+| Name       | ANDERSON, ORIN RAE       |
+| License #  | TACLA00000103C           |
+| State      | TX                       |
+| Trade      | hvac                     |
+| Status     | Active                   |
+| Expiration | 05/12/2026               |
+```
+
+### `clv_batch_verify`
+
+Verify up to 25 licenses in a single call. Each license is verified independently -- partial failures do not block the batch.
+
+**Parameters:**
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `licenses` | Yes | Array of `{ state, license_number, trade }` objects (1-25 items) |
+| `response_format` | No | `markdown` or `json` (default: `markdown`) |
+
+### `clv_list_supported_states`
+
+List all states currently supported for verification, including portal URLs and available trades.
+
+**Parameters:**
+
+| Name | Required | Description |
+|------|----------|-------------|
+| `response_format` | No | `markdown` or `json` (default: `markdown`) |
+
+## Supported States
+
+| Code | State      | Portal | Trades              |
+|------|------------|--------|---------------------|
+| TX   | Texas      | TDLR   | hvac, electrical    |
+| CA   | California | CSLB   | general             |
+| FL   | Florida    | DBPR   | general             |
+
+More states are being added. Run `clv_list_supported_states` for the latest list.
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CLV_API_URL` | Yes | API backend URL |
+| `CLV_API_KEY` | Yes | Your API key |
+
+## Credits
+
+Each license verification consumes **1 credit** (including cached results). New accounts receive **50 free credits**. Purchase additional credit packs via `POST /billing/checkout` with your API key.
+
+## Development
+
+```bash
+git clone https://github.com/jackunderwood/Contractor-License-Verification.git
+cd Contractor-License-Verification/mcp-server
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,18 @@
+import type { LicenseResult } from "./types.js";
+export declare class ApiError extends Error {
+    statusCode: number;
+    retryAfter?: number | undefined;
+    constructor(message: string, statusCode: number, retryAfter?: number | undefined);
+}
+export declare class ApiClient {
+    private http;
+    constructor(baseURL: string, apiKey: string);
+    verify(state: string, licenseNumber: string, trade: string): Promise<LicenseResult>;
+    health(): Promise<{
+        status: string;
+        api: string;
+        database: string;
+        redis: string;
+    }>;
+    private wrapError;
+}

package/dist/api.js

@@ -0,0 +1,66 @@
+import axios from "axios";
+export class ApiError extends Error {
+    statusCode;
+    retryAfter;
+    constructor(message, statusCode, retryAfter) {
+        super(message);
+        this.statusCode = statusCode;
+        this.retryAfter = retryAfter;
+        this.name = "ApiError";
+    }
+}
+export class ApiClient {
+    http;
+    constructor(baseURL, apiKey) {
+        this.http = axios.create({
+            baseURL,
+            headers: { "X-API-Key": apiKey },
+            timeout: 120_000, // Scrapers can be slow (Playwright + portal load)
+        });
+    }
+    async verify(state, licenseNumber, trade) {
+        // TODO: Add force_refresh param once backend supports cache bypass
+        try {
+            const { data } = await this.http.get("/verify", {
+                params: { state, license: licenseNumber, trade },
+            });
+            return data;
+        }
+        catch (err) {
+            throw this.wrapError(err);
+        }
+    }
+    async health() {
+        try {
+            const { data } = await this.http.get("/health");
+            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", 401);
+            }
+            if (status === 429) {
+                const retryAfter = parseInt(headers?.["retry-after"] ?? "60", 10);
+                return new ApiError(`Rate limit exceeded. Try again in ${retryAfter} seconds.`, 429, retryAfter);
+            }
+            if (status === 400) {
+                return new ApiError(detail, 400);
+            }
+            if (status === 502) {
+                return new ApiError("Verification temporarily unavailable. Try again in a few minutes.", 502);
+            }
+            return new ApiError(detail, status);
+        }
+        if (err.code === "ECONNREFUSED" || err.code === "ENOTFOUND") {
+            return new ApiError("Cannot reach the verification API — check your CLV_API_URL environment variable", 0);
+        }
+        return new ApiError(err.message ?? "Unknown error", 0);
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const CHARACTER_LIMIT = 50000;
+export declare const US_STATE_CODES: Set<string>;

package/dist/constants.js

@@ -0,0 +1,9 @@
+export const CHARACTER_LIMIT = 50_000;
+export const US_STATE_CODES = new Set([
+    "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA",
+    "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD",
+    "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ",
+    "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC",
+    "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY",
+    "DC",
+]);

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+import type { LicenseResult, StateInfo, BatchResponse } 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

@@ -0,0 +1,76 @@
+export function formatLicenseResult(result, format) {
+    if (format === "json") {
+        return JSON.stringify(result, null, 2);
+    }
+    const status = result.valid ? "VALID" : "INVALID";
+    const lines = [
+        `## License Verification: ${status}`,
+        "",
+        `| Field | Value |`,
+        `|-------|-------|`,
+        `| Name | ${result.name ?? "N/A"} |`,
+        `| License # | ${result.license_number} |`,
+        `| State | ${result.state} |`,
+        `| Trade | ${result.trade} |`,
+        `| Status | ${result.status ?? "N/A"} |`,
+        `| Expiration | ${result.expiration ?? "N/A"} |`,
+        `| Source | ${result.source_url ?? "N/A"} |`,
+        `| Cached | ${result.cached ? "Yes" : "No"} |`,
+        `| Checked | ${result.checked_at} |`,
+    ];
+    if (result.disciplinary_actions.length > 0) {
+        lines.push("", "### Disciplinary Actions");
+        for (const action of result.disciplinary_actions) {
+            lines.push(`- ${action}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatStatesList(states, format) {
+    if (format === "json") {
+        return JSON.stringify({ states, total: states.length }, null, 2);
+    }
+    const lines = [
+        `## Supported States (${states.length} 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(", ")} |`);
+    }
+    return lines.join("\n");
+}
+export function formatBatchResponse(batch, format) {
+    if (format === "json") {
+        return JSON.stringify(batch, null, 2);
+    }
+    const { summary, results } = batch;
+    const lines = [
+        `## Batch Verification: ${summary.succeeded}/${summary.total} succeeded`,
+        "",
+    ];
+    for (let i = 0; i < results.length; i++) {
+        const item = results[i];
+        if (item.result) {
+            lines.push(`### ${i + 1}. ${item.result.license_number} (${item.result.state})`);
+            lines.push(item.result.valid ? "**VALID**" : "**INVALID**");
+            if (item.result.name)
+                lines.push(`Name: ${item.result.name}`);
+            if (item.result.status)
+                lines.push(`Status: ${item.result.status}`);
+            lines.push("");
+        }
+        else {
+            lines.push(`### ${i + 1}. ERROR`);
+            lines.push(item.error ?? "Unknown error");
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ApiClient } from "./api.js";
+import { VerifyInputSchema, BatchInputSchema, StatesInputSchema } from "./schemas.js";
+import { handleVerify } from "./tools/verify.js";
+import { handleBatchVerify } from "./tools/batch.js";
+import { handleListStates } from "./tools/states.js";
+function getConfig() {
+    const apiUrl = process.env.CLV_API_URL;
+    const apiKey = process.env.CLV_API_KEY;
+    if (!apiUrl) {
+        console.error("Error: CLV_API_URL environment variable is required.\n" +
+            "Set it to your Contractor License Verification API URL (e.g. https://your-app.railway.app)");
+        process.exit(1);
+    }
+    if (!apiKey) {
+        console.error("Error: CLV_API_KEY environment variable is required.\n" +
+            "Get an API key from your CLV API admin.");
+        process.exit(1);
+    }
+    return { apiUrl, apiKey };
+}
+async function main() {
+    const { apiUrl, apiKey } = getConfig();
+    const client = new ApiClient(apiUrl, apiKey);
+    const server = new McpServer({
+        name: "contractor-license-verification",
+        version: "0.1.0",
+    });
+    server.registerTool("clv_verify_license", {
+        description: "Verify a contractor's license by checking the state licensing board portal. " +
+            "Returns license validity, holder name, status, expiration, and any disciplinary actions.",
+        inputSchema: VerifyInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => handleVerify(client, args));
+    server.registerTool("clv_batch_verify", {
+        description: "Verify multiple contractor licenses in a single request (max 25). " +
+            "Returns results for each license, with partial failure handling — individual failures don't block others.",
+        inputSchema: BatchInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => handleBatchVerify(client, args));
+    server.registerTool("clv_list_supported_states", {
+        description: "List all US states currently supported for contractor license verification, " +
+            "including portal URLs, health status, and available trades.",
+        inputSchema: StatesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => handleListStates(args));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/schemas.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+export declare const VerifyInputSchema: z.ZodObject<{
+    state: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    license_number: z.ZodString;
+    trade: z.ZodDefault<z.ZodString>;
+    force_refresh: z.ZodDefault<z.ZodBoolean>;
+    response_format: z.ZodDefault<z.ZodEnum<["markdown", "json"]>>;
+}, "strip", z.ZodTypeAny, {
+    state: string;
+    license_number: string;
+    trade: string;
+    force_refresh: boolean;
+    response_format: "markdown" | "json";
+}, {
+    state: string;
+    license_number: string;
+    trade?: string | undefined;
+    force_refresh?: boolean | undefined;
+    response_format?: "markdown" | "json" | undefined;
+}>;
+export declare const BatchInputSchema: z.ZodObject<{
+    licenses: z.ZodArray<z.ZodObject<{
+        state: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+        license_number: z.ZodString;
+        trade: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        state: string;
+        license_number: string;
+        trade: string;
+    }, {
+        state: string;
+        license_number: string;
+        trade?: string | undefined;
+    }>, "many">;
+    response_format: z.ZodDefault<z.ZodEnum<["markdown", "json"]>>;
+}, "strip", z.ZodTypeAny, {
+    response_format: "markdown" | "json";
+    licenses: {
+        state: string;
+        license_number: string;
+        trade: string;
+    }[];
+}, {
+    licenses: {
+        state: string;
+        license_number: string;
+        trade?: string | undefined;
+    }[];
+    response_format?: "markdown" | "json" | undefined;
+}>;
+export declare const StatesInputSchema: z.ZodObject<{
+    response_format: z.ZodDefault<z.ZodEnum<["markdown", "json"]>>;
+}, "strip", z.ZodTypeAny, {
+    response_format: "markdown" | "json";
+}, {
+    response_format?: "markdown" | "json" | undefined;
+}>;

package/dist/schemas.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { US_STATE_CODES } from "./constants.js";
+const stateField = z
+    .string()
+    .length(2)
+    .transform((s) => s.toUpperCase())
+    .refine((s) => US_STATE_CODES.has(s), { message: "Invalid US state code" })
+    .describe("Two-letter US state code (e.g. 'CA', 'TX'). Use clv_list_supported_states to see available states.");
+export const VerifyInputSchema = z.object({
+    state: stateField,
+    license_number: z
+        .string()
+        .min(1)
+        .max(50)
+        .describe("The contractor's license number as shown on their license card. Format varies by state."),
+    trade: z
+        .string()
+        .min(1)
+        .max(50)
+        .default("general")
+        .describe("The trade/contractor type (e.g. 'General Contractor', 'Electrical'). Use clv_list_supported_states to see valid values per state."),
+    force_refresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass cache and fetch fresh data from the state portal."),
+    response_format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Response format."),
+});
+export const BatchInputSchema = z.object({
+    licenses: z
+        .array(z.object({
+        state: stateField,
+        license_number: z.string().min(1).max(50).describe("License number."),
+        trade: z.string().min(1).max(50).default("general").describe("Trade type."),
+    }))
+        .min(1)
+        .max(25)
+        .describe("Array of licenses to verify (1-25 items)."),
+    response_format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Response format."),
+});
+export const StatesInputSchema = z.object({
+    response_format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Response format."),
+});

package/dist/tools/batch.d.ts

@@ -0,0 +1,12 @@
+import type { z } from "zod";
+import type { ApiClient } from "../api.js";
+import type { BatchInputSchema } from "../schemas.js";
+type BatchInput = z.output<typeof BatchInputSchema>;
+export declare function handleBatchVerify(client: ApiClient, args: BatchInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}>;
+export {};

package/dist/tools/batch.js

@@ -0,0 +1,33 @@
+import { formatBatchResponse } from "../format.js";
+import { CHARACTER_LIMIT } from "../constants.js";
+export async function handleBatchVerify(client, args) {
+    const { licenses, response_format } = args;
+    const results = [];
+    // Sequential to respect backend rate limits.
+    // TODO: Switch to POST /batch when backend supports it (Phase 2B).
+    for (const item of licenses) {
+        try {
+            const result = await client.verify(item.state, item.license_number, item.trade);
+            results.push({ result, error: null });
+        }
+        catch (err) {
+            results.push({ result: null, error: err.message ?? "Unknown error" });
+        }
+    }
+    const succeeded = results.filter((r) => r.result !== null).length;
+    const batch = {
+        summary: {
+            total: licenses.length,
+            succeeded,
+            failed: licenses.length - succeeded,
+        },
+        results,
+    };
+    let text = formatBatchResponse(batch, response_format);
+    if (text.length > CHARACTER_LIMIT) {
+        text =
+            text.slice(0, CHARACTER_LIMIT) +
+                "\n\n[Output truncated — too many results]";
+    }
+    return { content: [{ type: "text", text }] };
+}

package/dist/tools/states.d.ts

@@ -0,0 +1,10 @@
+import type { z } from "zod";
+import type { StatesInputSchema } from "../schemas.js";
+type StatesInput = z.output<typeof StatesInputSchema>;
+export declare function handleListStates(args: StatesInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export {};

package/dist/tools/states.js

@@ -0,0 +1,34 @@
+import { formatStatesList } from "../format.js";
+// Hardcoded until backend exposes a /states endpoint (Phase 2B+).
+// Update this list when new scrapers are registered.
+const SUPPORTED_STATES = [
+    {
+        code: "CA",
+        name: "California",
+        portal: "https://www.cslb.ca.gov/onlineservices/checkalicense/",
+        status: "healthy",
+        trades: ["general"],
+    },
+    {
+        code: "FL",
+        name: "Florida",
+        portal: "https://www.myfloridalicense.com/wl11.asp",
+        status: "healthy",
+        trades: ["general"],
+    },
+    {
+        code: "TX",
+        name: "Texas",
+        portal: "https://www.tdlr.texas.gov/LicenseSearch/",
+        status: "healthy",
+        trades: ["hvac", "electrical"],
+    },
+];
+export async function handleListStates(args) {
+    const format = args.response_format ?? "markdown";
+    return {
+        content: [
+            { type: "text", text: formatStatesList(SUPPORTED_STATES, format) },
+        ],
+    };
+}

package/dist/tools/verify.d.ts

@@ -0,0 +1,12 @@
+import type { z } from "zod";
+import type { ApiClient } from "../api.js";
+import type { VerifyInputSchema } from "../schemas.js";
+type VerifyInput = z.output<typeof VerifyInputSchema>;
+export declare function handleVerify(client: ApiClient, args: VerifyInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}>;
+export {};

package/dist/tools/verify.js

@@ -0,0 +1,18 @@
+import { formatLicenseResult } from "../format.js";
+export async function handleVerify(client, args) {
+    const { state, license_number, trade, response_format } = args;
+    try {
+        const result = await client.verify(state, license_number, trade);
+        return {
+            content: [
+                { type: "text", text: formatLicenseResult(result, response_format) },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: err.message ?? "Verification failed" }],
+            isError: true,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+export interface LicenseResult {
+    valid: boolean;
+    name: string | null;
+    license_number: string;
+    trade: string;
+    expiration: string | null;
+    status: string | null;
+    state: string;
+    disciplinary_actions: string[];
+    source_url: string | null;
+    cached: boolean;
+    checked_at: string;
+}
+export interface StateInfo {
+    code: string;
+    name: string;
+    portal: string;
+    status: "healthy" | "degraded" | "down";
+    trades: string[];
+}
+export interface BatchItem {
+    state: string;
+    license_number: string;
+    trade: string;
+}
+export interface BatchResult {
+    result: LicenseResult | null;
+    error: string | null;
+}
+export interface BatchResponse {
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+    };
+    results: BatchResult[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "contractor-license-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for contractor license verification — verify licenses across US state licensing portals via AI agents like Claude Desktop",
+  "type": "module",
+  "bin": {
+    "contractor-license-mcp-server": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "contractor",
+    "license",
+    "verification",
+    "claude",
+    "ai-agent",
+    "state-licensing"
+  ],
+  "author": "Jack Underwood",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jackunderwood/Contractor-License-Verification.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://github.com/jackunderwood/Contractor-License-Verification/tree/main/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/jackunderwood/Contractor-License-Verification/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "axios": "^1.7.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}