contractor-license-mcp-server 0.1.0 → 0.2.0

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { LicenseResult } from "./types.js";
+import type { LicenseResult, SearchResponse } from "./types.js";
 export declare class ApiError extends Error {
     statusCode: number;
     retryAfter?: number | undefined;
@@ -8,6 +8,7 @@ export declare class ApiClient {
     private http;
     constructor(baseURL: string, apiKey: string);
     verify(state: string, licenseNumber: string, trade: string): Promise<LicenseResult>;
+    search(state: string, name: string, trade: string, limit: number): Promise<SearchResponse>;
     health(): Promise<{
         status: string;
         api: string;

package/dist/api.js

@@ -30,6 +30,17 @@ export class ApiClient {
             throw this.wrapError(err);
         }
     }
+    async search(state, name, trade, limit) {
+        try {
+            const { data } = await this.http.get("/search", {
+                params: { state, name, trade, limit },
+            });
+            return data;
+        }
+        catch (err) {
+            throw this.wrapError(err);
+        }
+    }
     async health() {
         try {
             const { data } = await this.http.get("/health");

package/dist/format.d.ts

@@ -1,4 +1,5 @@
-import type { LicenseResult, StateInfo, BatchResponse } from "./types.js";
+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;
+export declare function formatSearchResults(response: SearchResponse, format: "markdown" | "json"): string;

package/dist/format.js

@@ -74,3 +74,27 @@ export function formatBatchResponse(batch, format) {
     }
     return lines.join("\n");
 }
+export function formatSearchResults(response, format) {
+    if (format === "json") {
+        return JSON.stringify(response, null, 2);
+    }
+    const { query, total_results, results, cached, checked_at } = response;
+    const lines = [
+        `## Name Search: "${query.name}" in ${query.state}`,
+        "",
+        `**${total_results} result${total_results === 1 ? "" : "s"} found** | Trade: ${query.trade} | Cached: ${cached ? "Yes" : "No"} | Checked: ${checked_at}`,
+        "",
+    ];
+    if (results.length === 0) {
+        lines.push("No matching contractors found.");
+    }
+    else {
+        lines.push("| # | Name | License # | Trade | Status | Confidence |", "|---|------|-----------|-------|--------|------------|");
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            const conf = `${Math.round(r.confidence * 100)}%`;
+            lines.push(`| ${i + 1} | ${r.name} | ${r.license_number} | ${r.trade} | ${r.status ?? "N/A"} | ${conf} |`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/index.js

@@ -2,10 +2,11 @@
 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 { VerifyInputSchema, BatchInputSchema, StatesInputSchema, SearchInputSchema } from "./schemas.js";
 import { handleVerify } from "./tools/verify.js";
 import { handleBatchVerify } from "./tools/batch.js";
 import { handleListStates } from "./tools/states.js";
+import { handleSearchByName } from "./tools/search.js";
 function getConfig() {
     const apiUrl = process.env.CLV_API_URL;
     const apiKey = process.env.CLV_API_KEY;
@@ -58,6 +59,16 @@ async function main() {
             idempotentHint: true,
         },
     }, async (args) => handleListStates(args));
+    server.registerTool("clv_search_by_name", {
+        description: "Search for contractors by business or individual name in a state licensing database. " +
+            "Returns matching contractors with license numbers, status, and confidence scores.",
+        inputSchema: SearchInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
+    }, async (args) => handleSearchByName(client, args));
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/schemas.d.ts

@@ -48,6 +48,25 @@ export declare const BatchInputSchema: z.ZodObject<{
     }[];
     response_format?: "markdown" | "json" | undefined;
 }>;
+export declare const SearchInputSchema: z.ZodObject<{
+    state: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    name: z.ZodString;
+    trade: z.ZodDefault<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    response_format: z.ZodDefault<z.ZodEnum<["markdown", "json"]>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    state: string;
+    trade: string;
+    response_format: "markdown" | "json";
+    limit: number;
+}, {
+    name: string;
+    state: string;
+    trade?: string | undefined;
+    response_format?: "markdown" | "json" | undefined;
+    limit?: number | undefined;
+}>;
 export declare const StatesInputSchema: z.ZodObject<{
     response_format: z.ZodDefault<z.ZodEnum<["markdown", "json"]>>;
 }, "strip", z.ZodTypeAny, {

package/dist/schemas.js

@@ -43,6 +43,31 @@ export const BatchInputSchema = z.object({
         .default("markdown")
         .describe("Response format."),
 });
+export const SearchInputSchema = z.object({
+    state: stateField,
+    name: z
+        .string()
+        .min(2)
+        .max(200)
+        .describe("Business or individual name to search for in the state licensing database."),
+    trade: z
+        .string()
+        .min(1)
+        .max(50)
+        .default("general")
+        .describe("The trade/contractor type to filter by (e.g. 'General Contractor', 'Electrical'). Use clv_list_supported_states to see valid values per state."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(20)
+        .describe("Maximum number of results to return."),
+    response_format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Response format."),
+});
 export const StatesInputSchema = z.object({
     response_format: z
         .enum(["markdown", "json"])

package/dist/tools/search.d.ts

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

package/dist/tools/search.js

@@ -0,0 +1,23 @@
+import { formatSearchResults } from "../format.js";
+import { CHARACTER_LIMIT } from "../constants.js";
+export async function handleSearchByName(client, args) {
+    const { state, name, trade, limit, response_format } = args;
+    try {
+        const response = await client.search(state, name, trade, limit);
+        let text = formatSearchResults(response, 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 }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: err.message ?? "Name search failed" }],
+            isError: true,
+        };
+    }
+}

package/dist/types.d.ts

@@ -35,3 +35,23 @@ export interface BatchResponse {
     };
     results: BatchResult[];
 }
+export interface SearchResultItem {
+    name: string;
+    license_number: string;
+    trade: string;
+    status: string | null;
+    state: string;
+    confidence: number;
+    source_url: string | null;
+}
+export interface SearchResponse {
+    query: {
+        state: string;
+        name: string;
+        trade: string;
+    };
+    total_results: number;
+    results: SearchResultItem[];
+    cached: boolean;
+    checked_at: string;
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "contractor-license-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.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"
+    "contractor-license-mcp-server": "dist/index.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -29,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jackunderwood/Contractor-License-Verification.git",
+    "url": "git+https://github.com/jackunderwood/Contractor-License-Verification.git",
     "directory": "mcp-server"
   },
   "homepage": "https://github.com/jackunderwood/Contractor-License-Verification/tree/main/mcp-server#readme",