@mambalabsdev/mcp-houzz-professionals 0.0.0-stage → 1.0.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mamba Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,107 @@
1
- # Temporary Holding Version
1
+ # Houzz Professionals Directory MCP Server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-houzz-professionals)](https://www.npmjs.com/package/@mambalabsdev/mcp-houzz-professionals) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-houzz-professionals)](https://github.com/mambalabsdev/mcp-houzz-professionals/blob/main/LICENSE)
4
+
5
+ An MCP server for the Mamba Labs Houzz Professionals Directory actor on Apify. Houzz home services pros as rows.
6
+
7
+ ## What's Inside
8
+
9
+ - [What it does](#what-it-does)
10
+ - [Quick start](#quick-start)
11
+ - [Prerequisites](#prerequisites)
12
+ - [Example prompts](#example-prompts)
13
+ - [Tool](#tool)
14
+ - [Inputs](#inputs)
15
+ - [Pricing](#pricing)
16
+ - [Full actor documentation](#full-actor-documentation)
17
+ - [License](#license)
18
+
19
+ ## What it does
20
+
21
+ Takes Houzz categories and US or Canadian cities, or Houzz directory URLs, and returns one row per professional listed, with phone, address, rating, review count, and typical job cost.
22
+
23
+ All of the work runs on Apify. This package is a thin client that starts the actor run, waits for it, and hands back the dataset rows.
24
+
25
+ ## Quick start
26
+
27
+ You need Node.js 18 or newer and an Apify account with an API token.
28
+
29
+ Add this to your Claude Desktop config (`claude_desktop_config.json`), Cursor, or any MCP client:
30
+
31
+ ```json
32
+ {
33
+ "mcpServers": {
34
+ "mamba-houzz-professionals": {
35
+ "command": "npx",
36
+ "args": [
37
+ "-y",
38
+ "@mambalabsdev/mcp-houzz-professionals"
39
+ ],
40
+ "env": {
41
+ "APIFY_TOKEN": "your-apify-token"
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ Restart the client. The `find_houzz_professionals` tool appears.
49
+
50
+ ## Prerequisites
51
+
52
+ - Node.js 18 or newer.
53
+ - An Apify API token from [console.apify.com/account/integrations](https://console.apify.com/account/integrations), set as `APIFY_TOKEN`. The server lists its tool without a token; a call needs one.
54
+
55
+ ## Example prompts
56
+
57
+ - "Find 30 general contractors in Denver, CO on Houzz with their phone numbers."
58
+ - "List kitchen remodelers in Austin, TX on Houzz rated 4.5 or higher."
59
+
60
+ ## Tool
61
+
62
+ `find_houzz_professionals`. One tool. Example arguments:
63
+
64
+ ```json
65
+ {
66
+ "categories": [
67
+ "general contractor"
68
+ ],
69
+ "locations": [
70
+ "Denver, CO"
71
+ ],
72
+ "max_results_per_search": 15
73
+ }
74
+ ```
75
+
76
+ ## Inputs
77
+
78
+ Every buyer facing input of the actor. Omitted inputs take the actor's own defaults.
79
+
80
+ | Input | Type | Required | Description |
81
+ |---|---|---|---|
82
+ | `categories` | array | no | Houzz professional categories, such as general contractor, plumber, roofer, interior designer, kitchen remodelers, or a Houzz category slug such as general-contractor. One search per category per place. Houzz has 64 categories; a name Houzz does not know returns a free summary row. |
83
+ | `locations` | array | no | US or Canadian cities as City, ST, for example Denver, CO or Toronto, ON. Put each place on its own line. A place Houzz does not recognize, or resolves to a different city, returns a free summary row. |
84
+ | `start_urls` | array | no | Optional. Houzz directory pages, for example https://www.houzz.com/professionals/general-contractor/c/Denver--CO. Profile pages are not read. |
85
+ | `max_results_per_search` | number | no | Professional rows to return for each category and place, or each URL, counting sponsored cards when they are included. Houzz lists 15 organic professionals a page. Default 15, maximum 1500. |
86
+ | `include_sponsored` | boolean | no | yes (default) returns the paid placements Houzz mixes into the results, labeled sponsored and without a rank. no returns organic results only. |
87
+ | `dedupe` | boolean | no | yes (default) returns each professional once per run, so a professional found by two searches, or shown again as a sponsored card on a later page, is charged once. no returns it again each time, charged each time. |
88
+ | `max_charge_usd` | number | no | Optional. The run stops before a charge that would pass this amount. Summary rows are always returned. |
89
+
90
+ ## Pricing
91
+
92
+ Pay per event on Apify, billed to your Apify account. Prices in USD.
93
+
94
+ | Event | Free plan | Bronze | Silver | Gold |
95
+ |---|---|---|---|---|
96
+ | `pro-row`, one professional | $0.002 | $0.0019 | $0.0018 | $0.0017 |
97
+ | `apify-actor-start`, per run start | $0.004 | $0.004 | $0.004 | $0.004 |
98
+
99
+ Summary rows and refused input are free. Mamba Labs pays the platform costs of the run, Apify proxy traffic included.
100
+
101
+ ## Full actor documentation
102
+
103
+ [apify.com/mambalabs/houzz-professionals](https://apify.com/mambalabs/houzz-professionals)
104
+
105
+ ## License
106
+
107
+ MIT. See [LICENSE](LICENSE).
package/SECURITY.md ADDED
@@ -0,0 +1,31 @@
1
+ # Security Policy
2
+
3
+ ## Supported versions
4
+
5
+ The latest published `1.x` release of
6
+ `@mambalabsdev/mcp-houzz-professionals` receives security updates.
7
+
8
+ | Version | Supported |
9
+ | ------- | ------------------ |
10
+ | 1.x | :white_check_mark: |
11
+ | < 1.0 | :x: |
12
+
13
+ ## Reporting a vulnerability
14
+
15
+ Please do not open a public GitHub issue for security reports.
16
+
17
+ Email security reports to **labs@mambamindsetgrowth.com** with:
18
+
19
+ - a description of the issue and its impact,
20
+ - steps to reproduce, and
21
+ - any relevant logs or proof of concept.
22
+
23
+ We aim to acknowledge reports within 3 business days and to provide a remediation
24
+ timeline after triage. Coordinated disclosure is appreciated.
25
+
26
+ ## Handling of credentials
27
+
28
+ This server reads an `APIFY_TOKEN` from the environment and uses it only to call
29
+ the Apify API on your behalf. The token is never logged or written to disk by this
30
+ package. Treat your `APIFY_TOKEN` as a secret and rotate it at
31
+ https://console.apify.com/account/integrations if you believe it has been exposed.
package/build/index.js ADDED
@@ -0,0 +1,203 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync } from "node:fs";
3
+ import { fileURLToPath } from "node:url";
4
+ import { dirname, join } from "node:path";
5
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
6
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
7
+ import { z } from "zod";
8
+ const here = dirname(fileURLToPath(import.meta.url));
9
+ const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
10
+ // Distinctive UA so Apify run meta.userAgent marks MCP-originated runs.
11
+ const USER_AGENT = `mambalabs-mcp ${pkg.name}@${pkg.version}`;
12
+ // Drop undefined values so optional inputs are not sent to the actor.
13
+ function compact(obj) {
14
+ const out = {};
15
+ for (const [k, v] of Object.entries(obj)) {
16
+ if (v !== undefined)
17
+ out[k] = v;
18
+ }
19
+ return out;
20
+ }
21
+ // How long the actor run itself is allowed to take, in seconds. Fleet standard
22
+ // (standing build rule 5, 2026-10-05). A run of 50 searches of 100 posts each
23
+ const ACTOR_RUN_TIMEOUT_SECS = 1800;
24
+ // How long this wrapper waits for that run, in milliseconds. The actor's own
25
+ // timeout plus two minutes, so the run's own TIMED-OUT status is what the
26
+ // caller sees rather than the wrapper giving up first and reporting nothing.
27
+ const WRAPPER_WAIT_MS = (ACTOR_RUN_TIMEOUT_SECS + 120) * 1000;
28
+ const POLL_INTERVAL_MS = 3000;
29
+ const TERMINAL = new Set(["SUCCEEDED", "FAILED", "TIMED-OUT", "ABORTED", "ABORTING"]);
30
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
31
+ // Shared caller. actorPath is the actor's immutable Apify actor ID (a stable key
32
+ // that survives Store renames). The /v2/acts/{id} endpoint accepts it directly,
33
+ // so a Store rename never breaks these calls.
34
+ //
35
+ // START AND POLL, NOT RUN-SYNC. Apify's synchronous endpoints carry a platform
36
+ // ceiling of 300 seconds on the HTTP wait itself and answer 408 past it whatever
37
+ // the timeout parameter says, so a long run reads as a timeout even though the
38
+ // actor goes on to finish. Starting the run, polling it to a terminal status and
39
+ // then reading the dataset is the only way to wait as long as the actor needs.
40
+ //
41
+ // The token is read here rather than at module load, so the tool registers
42
+ // unconditionally and a server started without APIFY_TOKEN still advertises its
43
+ // capabilities instead of reporting none.
44
+ async function runActor(actorPath, actorLabel, input) {
45
+ const APIFY_TOKEN = process.env.APIFY_TOKEN;
46
+ if (!APIFY_TOKEN) {
47
+ return { isError: true, content: [{ type: "text", text: "APIFY_TOKEN is not set. Create a token at https://console.apify.com/account/integrations and set it as the APIFY_TOKEN environment variable." }] };
48
+ }
49
+ const headers = {
50
+ Authorization: `Bearer ${APIFY_TOKEN}`,
51
+ "Content-Type": "application/json",
52
+ "User-Agent": USER_AGENT,
53
+ };
54
+ const httpError = async (response) => {
55
+ let detail = "";
56
+ try {
57
+ const body = (await response.json());
58
+ if (body?.error?.message)
59
+ detail = ` ${body.error.message}`;
60
+ }
61
+ catch {
62
+ detail = "";
63
+ }
64
+ switch (response.status) {
65
+ case 400:
66
+ return `The ${actorLabel} run was rejected as invalid input.${detail}`;
67
+ case 401:
68
+ return "Invalid Apify token. Check your APIFY_TOKEN environment variable.";
69
+ case 402:
70
+ return "Insufficient Apify credits. Check your account balance at https://console.apify.com/billing";
71
+ default:
72
+ return `Apify request to ${actorLabel} failed with status ${response.status}.${detail}`;
73
+ }
74
+ };
75
+ // 1. Start the run.
76
+ let started;
77
+ try {
78
+ started = await fetch(`https://api.apify.com/v2/acts/${actorPath}/runs?timeout=${ACTOR_RUN_TIMEOUT_SECS}`, { method: "POST", headers, body: JSON.stringify(input) });
79
+ }
80
+ catch (err) {
81
+ const message = err instanceof Error ? err.message : String(err);
82
+ return { isError: true, content: [{ type: "text", text: `Could not reach the Apify API: ${message}` }] };
83
+ }
84
+ if (!started.ok) {
85
+ return { isError: true, content: [{ type: "text", text: await httpError(started) }] };
86
+ }
87
+ let run;
88
+ try {
89
+ run = (await started.json()).data ?? {};
90
+ }
91
+ catch (err) {
92
+ const message = err instanceof Error ? err.message : String(err);
93
+ return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run start returned a response that could not be parsed: ${message}` }] };
94
+ }
95
+ const runId = run.id;
96
+ if (!runId) {
97
+ return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run start returned no run id, so there is nothing to wait for.` }] };
98
+ }
99
+ // 2. Poll to a terminal status.
100
+ const deadline = Date.now() + WRAPPER_WAIT_MS;
101
+ let status = run.status ?? "READY";
102
+ let datasetId = run.defaultDatasetId;
103
+ while (!TERMINAL.has(status)) {
104
+ if (Date.now() >= deadline) {
105
+ return {
106
+ isError: true,
107
+ content: [{ type: "text", text: `The ${actorLabel} run ${runId} was still ${status} after ${Math.round(WRAPPER_WAIT_MS / 1000)} seconds and this call stopped waiting. The run itself is still on Apify: read it at https://console.apify.com/actors/runs/${runId}` }],
108
+ };
109
+ }
110
+ await sleep(POLL_INTERVAL_MS);
111
+ let poll;
112
+ try {
113
+ poll = await fetch(`https://api.apify.com/v2/actor-runs/${runId}`, { headers });
114
+ }
115
+ catch (err) {
116
+ const message = err instanceof Error ? err.message : String(err);
117
+ return { isError: true, content: [{ type: "text", text: `Lost contact with the Apify API while waiting for ${actorLabel} run ${runId}: ${message}` }] };
118
+ }
119
+ if (!poll.ok) {
120
+ return { isError: true, content: [{ type: "text", text: await httpError(poll) }] };
121
+ }
122
+ const body = (await poll.json());
123
+ status = body.data?.status ?? status;
124
+ datasetId = body.data?.defaultDatasetId ?? datasetId;
125
+ }
126
+ // 3. A run that did not succeed is a failure the caller must see, never an
127
+ // empty success. Surfacing it here is what keeps a crashed run from reading
128
+ // as "no results found".
129
+ if (status !== "SUCCEEDED") {
130
+ return {
131
+ isError: true,
132
+ content: [{ type: "text", text: `The ${actorLabel} run did not succeed (run ID: ${runId}, status: ${status}).` }],
133
+ };
134
+ }
135
+ if (!datasetId) {
136
+ return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run ${runId} succeeded but reported no dataset, so there is nothing to return.` }] };
137
+ }
138
+ // 4. Read the dataset.
139
+ let ds;
140
+ try {
141
+ ds = await fetch(`https://api.apify.com/v2/datasets/${datasetId}/items?format=json`, { headers });
142
+ }
143
+ catch (err) {
144
+ const message = err instanceof Error ? err.message : String(err);
145
+ return { isError: true, content: [{ type: "text", text: `Could not read the ${actorLabel} dataset: ${message}` }] };
146
+ }
147
+ if (!ds.ok) {
148
+ return { isError: true, content: [{ type: "text", text: await httpError(ds) }] };
149
+ }
150
+ let items;
151
+ try {
152
+ items = await ds.json();
153
+ }
154
+ catch (err) {
155
+ const message = err instanceof Error ? err.message : String(err);
156
+ return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run returned a response that could not be parsed: ${message}` }] };
157
+ }
158
+ if (!Array.isArray(items)) {
159
+ const asObj = items;
160
+ const detail = asObj?.error?.message
161
+ ? `${asObj.error.message}`
162
+ : JSON.stringify(items);
163
+ return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run did not return a dataset. ${detail}` }] };
164
+ }
165
+ return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] };
166
+ }
167
+ // The actor's number and on or off inputs are text fields (Apify checks input
168
+ // types before the actor starts, and Clay sends text), so numbers and booleans
169
+ // from the model are sent as text.
170
+ function asActorInput(args) {
171
+ const out = {};
172
+ for (const [k, v] of Object.entries(compact(args))) {
173
+ out[k] = typeof v === "number" || typeof v === "boolean" ? String(v) : v;
174
+ }
175
+ return out;
176
+ }
177
+ const server = new McpServer({
178
+ name: "mamba-houzz-professionals",
179
+ version: pkg.version,
180
+ });
181
+ // Houzz Professionals Directory (immutable actor ID gv0DatXK2mOidqKLe). Every buyer facing input of the actor is exposed.
182
+ server.registerTool("find_houzz_professionals", {
183
+ title: "Find Houzz professionals",
184
+ description: "Search the Houzz directory for home services professionals by category and city, such as general contractors in Denver, CO. Returns one row per professional with name, phone, address, rating, review count, typical job cost, Houzz profile link, and any website or social links the professional listed.",
185
+ annotations: {
186
+ title: "Find Houzz professionals",
187
+ readOnlyHint: true,
188
+ destructiveHint: false,
189
+ idempotentHint: true,
190
+ openWorldHint: true,
191
+ },
192
+ inputSchema: {
193
+ categories: z.array(z.string()).optional().describe("Houzz professional categories, such as general contractor, plumber, roofer, interior designer, kitchen remodelers, or a Houzz category slug such as general-contractor. One search per category per place. Houzz has 64 categories; a name Houzz does not know returns a free summary row."),
194
+ locations: z.array(z.string()).optional().describe("US or Canadian cities as City, ST, for example Denver, CO or Toronto, ON. Put each place on its own line. A place Houzz does not recognize, or resolves to a different city, returns a free summary row."),
195
+ start_urls: z.array(z.string()).optional().describe("Optional. Houzz directory pages, for example https://www.houzz.com/professionals/general-contractor/c/Denver--CO. Profile pages are not read."),
196
+ max_results_per_search: z.number().optional().describe("Professional rows to return for each category and place, or each URL, counting sponsored cards when they are included. Houzz lists 15 organic professionals a page. Default 15, maximum 1500."),
197
+ include_sponsored: z.boolean().optional().describe("yes (default) returns the paid placements Houzz mixes into the results, labeled sponsored and without a rank. no returns organic results only."),
198
+ dedupe: z.boolean().optional().describe("yes (default) returns each professional once per run, so a professional found by two searches, or shown again as a sponsored card on a later page, is charged once. no returns it again each time, charged each time."),
199
+ max_charge_usd: z.number().optional().describe("Optional. The run stops before a charge that would pass this amount. Summary rows are always returned."),
200
+ },
201
+ }, async (args) => runActor("gv0DatXK2mOidqKLe", "Houzz Professionals Directory", asActorInput(args)));
202
+ const transport = new StdioServerTransport();
203
+ await server.connect(transport);
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@mambalabsdev/mcp-houzz-professionals",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0",
4
+ "description": "MCP server for Houzz Professionals Directory: contractors and home services pros by category and city from Houzz.",
5
+ "type": "module",
6
+ "bin": {
7
+ "mcp-houzz-professionals": "./build/index.js"
8
+ },
9
+ "files": [
10
+ "build",
11
+ "README.md",
12
+ "LICENSE",
13
+ "SECURITY.md"
14
+ ],
15
+ "scripts": {
16
+ "build": "tsc && chmod +x build/index.js",
17
+ "test": "npm run build && node --test test/*.test.js",
18
+ "prepublishOnly": "npm run build"
19
+ },
20
+ "keywords": [
21
+ "mcp",
22
+ "model-context-protocol",
23
+ "houzz",
24
+ "contractors",
25
+ "home-services",
26
+ "remodelers",
27
+ "lead-generation",
28
+ "scraper",
29
+ "apify",
30
+ "mcp",
31
+ "apify",
32
+ "clay"
33
+ ],
34
+ "author": "Mamba Labs <labs@mambamindsetgrowth.com>",
35
+ "license": "MIT",
36
+ "homepage": "https://apify.com/mambalabs/houzz-professionals",
37
+ "repository": {
38
+ "type": "git",
39
+ "url": "https://github.com/mambalabsdev/mcp-houzz-professionals"
40
+ },
41
+ "engines": {
42
+ "node": ">=18"
43
+ },
44
+ "dependencies": {
45
+ "@modelcontextprotocol/sdk": "^1.32.2",
46
+ "zod": "^4.4.3"
47
+ },
48
+ "devDependencies": {
49
+ "@types/node": "^26.2.0",
50
+ "typescript": "5.9.3"
51
+ },
52
+ "mcpName": "com.mambabuilt/mcp-houzz-professionals"
53
+ }