contractor-license-mcp-server 0.3.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +95 -51
  2. package/dist/tools/states.js +47 -114
  3. package/package.json +7 -7
package/README.md CHANGED
@@ -1,14 +1,22 @@
1
1
  # contractor-license-mcp-server
2
2
 
3
- 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.
3
+ **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.
4
4
 
5
- Currently supports **Texas (TDLR)**, **California (CSLB)**, and **Florida (DBPR)**, with more states coming.
5
+ 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.
6
6
 
7
- ## Quick Start
7
+ ## Why this server
8
+
9
+ - **45 states** covered via official state licensing board portals, not third-party data aggregators
10
+ - **Live lookups** — each verification hits the authoritative portal, so expirations and disciplinary actions are as fresh as the board's own data
11
+ - **Batch verification** — up to 25 licenses per call, run in parallel
12
+ - **Disciplinary history** — returned when the portal exposes it
13
+ - Backed by [TradesAPI](https://www.tradesapi.com), a hosted HTTP API you can also hit directly
14
+
15
+ ## Quick start
8
16
 
9
17
  ### Claude Desktop
10
18
 
11
- Add this to your Claude Desktop config file:
19
+ Add this to your Claude Desktop config:
12
20
 
13
21
  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
14
22
  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -16,11 +24,11 @@ Add this to your Claude Desktop config file:
16
24
  ```json
17
25
  {
18
26
  "mcpServers": {
19
- "contractor-license-verification": {
27
+ "tradesapi": {
20
28
  "command": "npx",
21
29
  "args": ["-y", "contractor-license-mcp-server"],
22
30
  "env": {
23
- "CLV_API_URL": "https://contractor-license-verification-production.up.railway.app",
31
+ "CLV_API_URL": "https://www.tradesapi.com",
24
32
  "CLV_API_KEY": "your-api-key-here"
25
33
  }
26
34
  }
@@ -28,37 +36,35 @@ Add this to your Claude Desktop config file:
28
36
  }
29
37
  ```
30
38
 
31
- Restart Claude Desktop after saving the config.
39
+ Restart Claude Desktop after saving.
32
40
 
33
- ### Getting an API Key
41
+ ### Getting an API key
34
42
 
35
- New accounts start with **50 free verification credits**. To get your API key:
43
+ 1. Go to [www.tradesapi.com](https://www.tradesapi.com) and click **Sign up free**
44
+ 2. Enter your email — you'll get a magic link
45
+ 3. Click the link and land on your dashboard, where your API key is waiting
36
46
 
37
- 1. Visit the [billing portal](https://contractor-license-verification-production.up.railway.app/billing/checkout) to create an account
38
- 2. Your API key will be provided on signup
39
- 3. Need more credits? Purchase additional packs at the same billing portal
47
+ New accounts start with **50 free verification credits**, no credit card required. You can purchase additional credit packs from the dashboard when you need more.
40
48
 
41
- ### Direct Install
49
+ ### Direct install
42
50
 
43
51
  ```bash
44
52
  npm install -g contractor-license-mcp-server
45
53
  ```
46
54
 
47
- ## Available Tools
55
+ ## Tools
48
56
 
49
57
  ### `clv_verify_license`
50
58
 
51
59
  Verify a single contractor license against a state licensing board portal.
52
60
 
53
- **Parameters:**
54
-
55
- | Name | Required | Description |
56
- |------|----------|-------------|
57
- | `state` | Yes | Two-letter state code (e.g. `CA`, `TX`, `FL`) |
58
- | `license_number` | Yes | The license number to verify |
59
- | `trade` | No | Trade type (default: `general`) |
60
- | `force_refresh` | No | Bypass cache for fresh data (default: `false`) |
61
- | `response_format` | No | `markdown` or `json` (default: `markdown`) |
61
+ | Parameter | Required | Description |
62
+ |---|---|---|
63
+ | `state` | yes | Two-letter state code (`CA`, `TX`, `FL`, ...) |
64
+ | `license_number` | yes | The license number to verify |
65
+ | `trade` | no | `general`, `electrical`, `plumbing`, `hvac`, `mechanical`, `residential`, or `home_inspection` (defaults to `general`) |
66
+ | `force_refresh` | no | Bypass the 24h cache and re-fetch from the portal |
67
+ | `response_format` | no | `markdown` (default) or `json` |
62
68
 
63
69
  **Example result:**
64
70
 
@@ -77,45 +83,83 @@ Verify a single contractor license against a state licensing board portal.
77
83
 
78
84
  ### `clv_batch_verify`
79
85
 
80
- Verify up to 25 licenses in a single call. Each license is verified independently -- partial failures do not block the batch.
86
+ Verify up to 25 licenses in a single call. Each verification runs independently — partial failures do not block the batch.
81
87
 
82
- **Parameters:**
83
-
84
- | Name | Required | Description |
85
- |------|----------|-------------|
86
- | `licenses` | Yes | Array of `{ state, license_number, trade }` objects (1-25 items) |
87
- | `response_format` | No | `markdown` or `json` (default: `markdown`) |
88
+ | Parameter | Required | Description |
89
+ |---|---|---|
90
+ | `licenses` | yes | Array of `{ state, license_number, trade }` objects (1–25 items) |
91
+ | `response_format` | no | `markdown` (default) or `json` |
88
92
 
89
93
  ### `clv_list_supported_states`
90
94
 
91
- List all states currently supported for verification, including portal URLs and available trades.
92
-
93
- **Parameters:**
94
-
95
- | Name | Required | Description |
96
- |------|----------|-------------|
97
- | `response_format` | No | `markdown` or `json` (default: `markdown`) |
98
-
99
- ## Supported States
100
-
101
- | Code | State | Portal | Trades |
102
- |------|------------|--------|---------------------|
103
- | TX | Texas | TDLR | hvac, electrical |
104
- | CA | California | CSLB | general |
105
- | FL | Florida | DBPR | general |
106
-
107
- More states are being added. Run `clv_list_supported_states` for the latest list.
95
+ List all supported states, including portal URLs and available trades. Use this to see which states and trades you can query.
96
+
97
+ | Parameter | Required | Description |
98
+ |---|---|---|
99
+ | `response_format` | no | `markdown` (default) or `json` |
100
+
101
+ ## Supported states
102
+
103
+ | Code | State | Trades |
104
+ |---|---|---|
105
+ | AK | Alaska | general, electrical, mechanical |
106
+ | AL | Alabama | general, electrical, plumbing, hvac, residential |
107
+ | AR | Arkansas | general |
108
+ | AZ | Arizona | general, electrical, plumbing, hvac |
109
+ | CA | California | general, electrical, plumbing, hvac |
110
+ | CO | Colorado | electrical, plumbing |
111
+ | CT | Connecticut | general, electrical, plumbing, hvac |
112
+ | DC | District of Columbia | general |
113
+ | DE | Delaware | electrical, plumbing, hvac |
114
+ | FL | Florida | general, electrical, plumbing, hvac |
115
+ | GA | Georgia | general |
116
+ | HI | Hawaii | general |
117
+ | IA | Iowa | electrical |
118
+ | ID | Idaho | electrical, plumbing, hvac |
119
+ | IL | Illinois | general, electrical, plumbing, hvac |
120
+ | IN | Indiana | plumbing |
121
+ | KY | Kentucky | general, electrical, hvac, plumbing |
122
+ | LA | Louisiana | general |
123
+ | MA | Massachusetts | general, mechanical |
124
+ | MD | Maryland | general, hvac, electrical, plumbing |
125
+ | ME | Maine | electrical, plumbing |
126
+ | MI | Michigan | electrical, plumbing, hvac |
127
+ | MN | Minnesota | general, electrical, plumbing |
128
+ | MS | Mississippi | general |
129
+ | NC | North Carolina | general |
130
+ | ND | North Dakota | general, electrical |
131
+ | NE | Nebraska | general, electrical |
132
+ | NH | New Hampshire | electrical, plumbing |
133
+ | NJ | New Jersey | general, electrical, hvac, plumbing |
134
+ | NM | New Mexico | general, electrical, plumbing, hvac |
135
+ | NV | Nevada | general, electrical, plumbing, hvac |
136
+ | NY | New York | home_inspection |
137
+ | OH | Ohio | general, electrical, plumbing, hvac |
138
+ | OK | Oklahoma | electrical, plumbing, hvac |
139
+ | OR | Oregon | general |
140
+ | PA | Pennsylvania | general, electrical, hvac, plumbing |
141
+ | RI | Rhode Island | general |
142
+ | SC | South Carolina | general, electrical, plumbing, hvac |
143
+ | TN | Tennessee | general, electrical, plumbing |
144
+ | TX | Texas | hvac, electrical, plumbing |
145
+ | UT | Utah | general, electrical, plumbing, hvac |
146
+ | VA | Virginia | general, electrical, plumbing, hvac |
147
+ | VT | Vermont | electrical, plumbing |
148
+ | WA | Washington | general |
149
+ | WV | West Virginia | general, electrical, hvac, plumbing |
150
+
151
+ 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).
108
152
 
109
153
  ## Configuration
110
154
 
111
155
  | Variable | Required | Description |
112
- |----------|----------|-------------|
113
- | `CLV_API_URL` | Yes | API backend URL |
114
- | `CLV_API_KEY` | Yes | Your API key |
156
+ |---|---|---|
157
+ | `CLV_API_URL` | yes | API backend URL (use `https://www.tradesapi.com`) |
158
+ | `CLV_API_KEY` | yes | Your API key from the dashboard |
115
159
 
116
160
  ## Credits
117
161
 
118
- 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.
162
+ Each license verification consumes **1 credit**, whether the result is fresh or cached. New accounts receive **50 free credits**. Additional credit packs can be purchased from the dashboard at [www.tradesapi.com](https://www.tradesapi.com).
119
163
 
120
164
  ## Development
121
165
 
package/dist/tools/states.js CHANGED
@@ -1,119 +1,52 @@
1
1
  import { formatStatesList } from "../format.js";
2
- // Hardcoded until backend exposes a /states endpoint (Phase 2B+).
3
- // Update this list when new scrapers are registered.
2
+ // Hardcoded until backend exposes a /states endpoint.
3
+ // Last updated: 2026-03-27 — 43 working states.
4
4
  const SUPPORTED_STATES = [
5
- {
6
- code: "AR",
7
- name: "Arkansas",
8
- portal: "https://www.aclb.arkansas.gov/",
9
- status: "healthy",
10
- trades: ["general"],
11
- },
12
- {
13
- code: "CA",
14
- name: "California",
15
- portal: "https://www.cslb.ca.gov/onlineservices/checkalicense/",
16
- status: "healthy",
17
- trades: ["general"],
18
- },
19
- {
20
- code: "DC",
21
- name: "District of Columbia",
22
- portal: "https://dcra.dc.gov/",
23
- status: "healthy",
24
- trades: ["general"],
25
- },
26
- {
27
- code: "FL",
28
- name: "Florida",
29
- portal: "https://www.myfloridalicense.com/wl11.asp",
30
- status: "healthy",
31
- trades: ["general"],
32
- },
33
- {
34
- code: "GA",
35
- name: "Georgia",
36
- portal: "https://verify.sos.ga.gov/",
37
- status: "degraded",
38
- trades: ["general"],
39
- },
40
- {
41
- code: "IL",
42
- name: "Illinois",
43
- portal: "https://idfpr.illinois.gov/",
44
- status: "healthy",
45
- trades: ["general"],
46
- },
47
- {
48
- code: "MS",
49
- name: "Mississippi",
50
- portal: "https://www.msboc.us/",
51
- status: "healthy",
52
- trades: ["general"],
53
- },
54
- {
55
- code: "NC",
56
- name: "North Carolina",
57
- portal: "https://www.nclbgc.org/",
58
- status: "healthy",
59
- trades: ["general"],
60
- },
61
- {
62
- code: "NJ",
63
- name: "New Jersey",
64
- portal: "https://newjersey.mylicense.com/verification/",
65
- status: "healthy",
66
- trades: ["general"],
67
- },
68
- {
69
- code: "NY",
70
- name: "New York",
71
- portal: "https://www.dos.ny.gov/licensing/",
72
- status: "degraded",
73
- trades: ["general"],
74
- },
75
- {
76
- code: "OH",
77
- name: "Ohio",
78
- portal: "https://elicense.ohio.gov/",
79
- status: "healthy",
80
- trades: ["general"],
81
- },
82
- {
83
- code: "OK",
84
- name: "Oklahoma",
85
- portal: "https://www.ok.gov/cib/",
86
- status: "healthy",
87
- trades: ["general"],
88
- },
89
- {
90
- code: "PA",
91
- name: "Pennsylvania",
92
- portal: "https://www.pals.pa.gov/",
93
- status: "degraded",
94
- trades: ["general"],
95
- },
96
- {
97
- code: "RI",
98
- name: "Rhode Island",
99
- portal: "https://www.crb.ri.gov/",
100
- status: "healthy",
101
- trades: ["general"],
102
- },
103
- {
104
- code: "TX",
105
- name: "Texas",
106
- portal: "https://www.tdlr.texas.gov/LicenseSearch/",
107
- status: "healthy",
108
- trades: ["hvac", "electrical"],
109
- },
110
- {
111
- code: "WA",
112
- name: "Washington",
113
- portal: "https://secure.lni.wa.gov/verify/",
114
- status: "healthy",
115
- trades: ["general"],
116
- },
5
+ { code: "AK", name: "Alaska", portal: "https://www.commerce.alaska.gov/", status: "healthy", trades: ["general", "electrical", "mechanical"] },
6
+ { code: "AL", name: "Alabama", portal: "https://genconbd.alabama.gov/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac", "residential"] },
7
+ { code: "AR", name: "Arkansas", portal: "https://www.aclb.arkansas.gov/", status: "healthy", trades: ["general"] },
8
+ { code: "AZ", name: "Arizona", portal: "https://azroc.my.site.com/AZRoc/s/contractor-search", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
9
+ { code: "CA", name: "California", portal: "https://www.cslb.ca.gov/onlineservices/checkalicense/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
10
+ { code: "CO", name: "Colorado", portal: "https://apps2.colorado.gov/dora/licensing/lookup/", status: "healthy", trades: ["electrical", "plumbing"] },
11
+ { code: "CT", name: "Connecticut", portal: "https://elicense.ct.gov/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
12
+ { code: "DC", name: "District of Columbia", portal: "https://dcra.dc.gov/", status: "healthy", trades: ["general"] },
13
+ { code: "DE", name: "Delaware", portal: "https://delpros.delaware.gov/", status: "healthy", trades: ["electrical", "plumbing", "hvac"] },
14
+ { code: "FL", name: "Florida", portal: "https://www.myfloridalicense.com/wl11.asp", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
15
+ { code: "GA", name: "Georgia", portal: "https://goals.sos.ga.gov/", status: "degraded", trades: ["general"] },
16
+ { code: "HI", name: "Hawaii", portal: "https://mypvl.dcca.hawaii.gov/", status: "healthy", trades: ["general"] },
17
+ { code: "IA", name: "Iowa", portal: "https://dps-eeb.my.site.com/", status: "healthy", trades: ["electrical"] },
18
+ { code: "ID", name: "Idaho", portal: "https://dopl.idaho.gov/", status: "healthy", trades: ["electrical", "plumbing", "hvac"] },
19
+ { code: "IL", name: "Illinois", portal: "https://idfpr.illinois.gov/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
20
+ { code: "IN", name: "Indiana", portal: "https://mylicense.in.gov/", status: "healthy", trades: ["plumbing"] },
21
+ { code: "KY", name: "Kentucky", portal: "https://dhbc.ky.gov/", status: "healthy", trades: ["general", "electrical", "hvac", "plumbing"] },
22
+ { code: "LA", name: "Louisiana", portal: "https://arlspublic.lslbc.louisiana.gov/", status: "healthy", trades: ["general"] },
23
+ { code: "MA", name: "Massachusetts", portal: "https://www.mass.gov/", status: "healthy", trades: ["general", "mechanical"] },
24
+ { code: "MD", name: "Maryland", portal: "https://labor.maryland.gov/", status: "healthy", trades: ["general", "hvac", "electrical", "plumbing"] },
25
+ { code: "ME", name: "Maine", portal: "https://pfr.maine.gov/", status: "healthy", trades: ["electrical", "plumbing"] },
26
+ { code: "MI", name: "Michigan", portal: "https://aca-prod.accela.com/LARA/", status: "healthy", trades: ["electrical", "plumbing", "hvac"] },
27
+ { code: "MN", name: "Minnesota", portal: "https://ims.dli.mn.gov/", status: "healthy", trades: ["general", "electrical", "plumbing"] },
28
+ { code: "MS", name: "Mississippi", portal: "https://www.msboc.us/", status: "healthy", trades: ["general"] },
29
+ { code: "NC", name: "North Carolina", portal: "https://www.nclbgc.org/", status: "healthy", trades: ["general"] },
30
+ { code: "ND", name: "North Dakota", portal: "https://firststop.sos.nd.gov/", status: "healthy", trades: ["general", "electrical"] },
31
+ { code: "NE", name: "Nebraska", portal: "https://dol.nebraska.gov/conreg/", status: "healthy", trades: ["general", "electrical"] },
32
+ { code: "NH", name: "New Hampshire", portal: "https://forms.nh.gov/licenseverification/", status: "healthy", trades: ["electrical", "plumbing"] },
33
+ { code: "NJ", name: "New Jersey", portal: "https://newjersey.mylicense.com/verification/", status: "healthy", trades: ["general", "electrical", "hvac", "plumbing"] },
34
+ { code: "NM", name: "New Mexico", portal: "https://public.psiexams.com/search.jsp", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
35
+ { code: "NV", name: "Nevada", portal: "https://app.nvcontractorsboard.com/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
36
+ { code: "NY", name: "New York", portal: "https://www.dos.ny.gov/licensing/", status: "healthy", trades: ["home_inspection"] },
37
+ { code: "OH", name: "Ohio", portal: "https://elicense.ohio.gov/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
38
+ { code: "OK", name: "Oklahoma", portal: "https://www.ok.gov/cib/", status: "healthy", trades: ["electrical", "plumbing", "hvac"] },
39
+ { code: "OR", name: "Oregon", portal: "https://search.ccb.state.or.us/search/", status: "healthy", trades: ["general"] },
40
+ { code: "PA", name: "Pennsylvania", portal: "https://www.pals.pa.gov/", status: "healthy", trades: ["general", "electrical", "hvac", "plumbing"] },
41
+ { code: "RI", name: "Rhode Island", portal: "https://www.crb.ri.gov/", status: "healthy", trades: ["general"] },
42
+ { code: "SC", name: "South Carolina", portal: "https://verify.llronline.com/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
43
+ { code: "TN", name: "Tennessee", portal: "https://verify.tn.gov/", status: "healthy", trades: ["general", "electrical", "plumbing"] },
44
+ { code: "TX", name: "Texas", portal: "https://www.tdlr.texas.gov/LicenseSearch/", status: "healthy", trades: ["hvac", "electrical", "plumbing"] },
45
+ { code: "UT", name: "Utah", portal: "https://secure.utah.gov/llv/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
46
+ { code: "VA", name: "Virginia", portal: "https://dporweb.dpor.virginia.gov/", status: "healthy", trades: ["general", "electrical", "plumbing", "hvac"] },
47
+ { code: "VT", name: "Vermont", portal: "https://sos.vermont.gov/opr/", status: "healthy", trades: ["electrical", "plumbing"] },
48
+ { code: "WA", name: "Washington", portal: "https://secure.lni.wa.gov/verify/", status: "healthy", trades: ["general"] },
49
+ { code: "WV", name: "West Virginia", portal: "https://wvclboard.wv.gov/", status: "healthy", trades: ["general", "electrical", "hvac", "plumbing"] },
117
50
  ];
118
51
  export async function handleListStates(args) {
119
52
  const format = args.response_format ?? "markdown";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "contractor-license-mcp-server",
3
- "version": "0.3.0",
4
- "description": "MCP server for contractor license verification — verify licenses across US state licensing portals via AI agents like Claude Desktop",
3
+ "version": "0.6.0",
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.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "contractor-license-mcp-server": "dist/index.js"
@@ -39,16 +39,16 @@
39
39
  "url": "https://github.com/jackunderwood/Contractor-License-Verification/issues"
40
40
  },
41
41
  "engines": {
42
- "node": ">=18.0.0"
42
+ "node": ">=20.0.0"
43
43
  },
44
44
  "dependencies": {
45
45
  "@modelcontextprotocol/sdk": "^1.27.0",
46
46
  "axios": "^1.7.0",
47
- "zod": "^3.23.0"
47
+ "zod": "^4.3.6"
48
48
  },
49
49
  "devDependencies": {
50
- "@types/node": "^22.0.0",
51
- "typescript": "^5.7.0",
52
- "vitest": "^3.0.0"
50
+ "@types/node": "^25.5.0",
51
+ "typescript": "^6.0.2",
52
+ "vitest": "^4.1.2"
53
53
  }
54
54
  }