contractor-license-mcp-server 0.6.3 → 0.6.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Underwood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -164,8 +164,8 @@ Each license verification consumes **1 credit**, whether the result is fresh or
 ## Development
 
 ```bash
-git clone https://github.com/jackunderwood/Contractor-License-Verification.git
-cd Contractor-License-Verification/mcp-server
+git clone https://github.com/Noquarter6/contractor-license-mcp-server.git
+cd contractor-license-mcp-server
 npm install
 npm run build
 npm test

package/dist/api.js

@@ -15,11 +15,10 @@ export class ApiClient {
         this.http = axios.create({
             baseURL,
             headers: { "X-API-Key": apiKey },
-            timeout: 120_000, // Scrapers can be slow (Playwright + portal load)
+            timeout: 120_000, // Portal lookups can be slow
         });
     }
     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 },

package/dist/index.js

@@ -12,7 +12,7 @@ function getConfig() {
     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)");
+            "Set it to https://www.tradesapi.com");
         process.exit(1);
     }
     if (!apiKey) {
@@ -27,11 +27,16 @@ async function main() {
     const client = new ApiClient(apiUrl, apiKey);
     const server = new McpServer({
         name: "contractor-license-verification",
-        version: "0.1.0",
+        version: "0.6.3",
     });
     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.",
+        description: "Verify a single contractor license against a state licensing board portal. " +
+            "Returns validity, licensee name, status, expiration date, and any disciplinary actions on file. " +
+            "Use this when you have a specific license number to check. " +
+            "Use clv_search_by_name instead when you only have a contractor's name. " +
+            "Results are cached for 24 hours; set force_refresh to bypass. " +
+            "Returns an error for unsupported states (check clv_list_supported_states first). " +
+            "This is a read-only lookup that does not modify any licensing data.",
         inputSchema: VerifyInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -40,8 +45,11 @@ async function main() {
         },
     }, 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.",
+        description: "Verify multiple contractor licenses in a single request (1-25 items). " +
+            "Each license is verified independently — individual failures do not block the batch. " +
+            "Use this instead of multiple clv_verify_license calls when checking more than one license. " +
+            "Returns a summary (succeeded/failed counts) plus per-license results with the same fields as clv_verify_license. " +
+            "Returns an error if the array is empty or exceeds 25 items.",
         inputSchema: BatchInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -50,8 +58,10 @@ async function main() {
         },
     }, 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.",
+        description: "List all US states supported for contractor license verification, with portal URLs, health status, and available trades per state. " +
+            "Call this before verifying to confirm a state and trade combination is supported. " +
+            "Returns 45 states. Health status is 'healthy', 'degraded', or 'down'. " +
+            "Does not make any network requests — the state list is embedded in the server.",
         inputSchema: StatesInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -61,7 +71,10 @@ async function main() {
     }, 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.",
+            "Use this when you have a contractor's name but not their license number. " +
+            "Use clv_verify_license instead when you already have the license number. " +
+            "Returns matching contractors with license numbers, status, and confidence scores (0-1). " +
+            "Partial name matches are supported. Results are capped by the limit parameter (default 20, max 50).",
         inputSchema: SearchInputSchema,
         annotations: {
             readOnlyHint: true,

package/dist/schemas.js

@@ -5,43 +5,43 @@ const stateField = z
     .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.");
+    .describe("Two-letter US state code (e.g. 'CA', 'TX', 'FL'). 45 states supported. Call clv_list_supported_states to see the full list with available trades.");
 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."),
+        .describe("The contractor's license number exactly as issued (e.g. 'TACLA00000103C' for TX HVAC, '1098765' for CA). 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."),
+        .describe("Trade category: 'general', 'electrical', 'plumbing', 'hvac', 'mechanical', 'residential', or 'home_inspection'. Defaults to 'general'. Available trades vary by state — check clv_list_supported_states."),
     force_refresh: z
         .boolean()
         .default(false)
-        .describe("Bypass cache and fetch fresh data from the state portal."),
+        .describe("Bypass the 24-hour cache and re-fetch live from the state portal. Use when you need the most current data."),
     response_format: z
         .enum(["markdown", "json"])
         .default("markdown")
-        .describe("Response format."),
+        .describe("Output format. 'markdown' is optimized for chat display with tables. 'json' returns structured data for programmatic use."),
 });
 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."),
+        license_number: z.string().min(1).max(50).describe("License number exactly as issued. Format varies by state."),
+        trade: z.string().min(1).max(50).default("general").describe("Trade category (e.g. 'general', 'electrical', 'plumbing', 'hvac'). Defaults to 'general'."),
     }))
         .min(1)
         .max(25)
-        .describe("Array of licenses to verify (1-25 items)."),
+        .describe("Array of licenses to verify (1-25 items). Each license is verified independently — a failure on one does not affect the others."),
     response_format: z
         .enum(["markdown", "json"])
         .default("markdown")
-        .describe("Response format."),
+        .describe("Output format. 'markdown' is optimized for chat display. 'json' returns structured data for programmatic use."),
 });
 export const SearchInputSchema = z.object({
     state: stateField,
@@ -49,28 +49,28 @@ export const SearchInputSchema = z.object({
         .string()
         .min(2)
         .max(200)
-        .describe("Business or individual name to search for in the state licensing database."),
+        .describe("Business or individual name to search for. Partial matches are supported (e.g. 'Anderson' will match 'Anderson Electric LLC')."),
     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."),
+        .describe("Trade category to filter by: 'general', 'electrical', 'plumbing', 'hvac', etc. Defaults to 'general'. Check clv_list_supported_states for valid trades per state."),
     limit: z
         .number()
         .int()
         .min(1)
         .max(50)
         .default(20)
-        .describe("Maximum number of results to return."),
+        .describe("Maximum number of results to return. Defaults to 20, capped at 50."),
     response_format: z
         .enum(["markdown", "json"])
         .default("markdown")
-        .describe("Response format."),
+        .describe("Output format. 'markdown' is optimized for chat display with tables. 'json' returns structured data for programmatic use."),
 });
 export const StatesInputSchema = z.object({
     response_format: z
         .enum(["markdown", "json"])
         .default("markdown")
-        .describe("Response format."),
+        .describe("Output format. 'markdown' renders a table with state codes, names, status, and trades. 'json' returns a structured array."),
 });

package/dist/tools/batch.js

@@ -3,8 +3,6 @@ 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);

package/dist/tools/states.js

@@ -1,6 +1,4 @@
 import { formatStatesList } from "../format.js";
-// Hardcoded until backend exposes a /states endpoint.
-// Last updated: 2026-03-27 — 43 working states.
 const SUPPORTED_STATES = [
     { code: "AK", name: "Alaska", portal: "https://www.commerce.alaska.gov/", status: "healthy", trades: ["general", "electrical", "mechanical"] },
     { code: "AL", name: "Alabama", portal: "https://genconbd.alabama.gov/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac", "residential"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contractor-license-mcp-server",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Real-time contractor license verification across 45 US states. MCP server for Claude Desktop and other AI agents — verify license status, expiration, and disciplinary history directly against state licensing board portals.",
   "mcpName": "io.github.Noquarter6/contractor-license-mcp-server",
   "type": "module",