# mcp-homedepot

[![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/license-PolyForm--Noncommercial--1.0.0-blue.svg)](./LICENSE.md)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

A [Model Context Protocol](https://modelcontextprotocol.io) server for **Home Depot
Canada** (homedepot.ca). It exposes the store's product catalogue — search, product
detail, store-level stock and a store finder — to MCP clients such as Claude and Cursor.

> **Unofficial.** This project is not affiliated with, endorsed by, or sponsored by
> The Home Depot. It reads publicly available endpoints of homedepot.ca for personal,
> noncommercial use. Respect Home Depot's terms of service and use responsibly.

## Tools

| Tool | Description |
|------|-------------|
| `hd_search` | Product search / listings by keyword. Returns products (SKU, name, brand, model, price, rating, online stock, URL, image), total count, facets and sort options. |
| `hd_product` | Full product card by SKU: name, brand, model, description, images, rating/reviews, warranty, categories, price, in-store stock + aisle/bay, online stock, fulfillment options. |
| `hd_store_availability` | In-store stock of a SKU across a store and its nearby stores, sorted in-stock first. Per store: name, address, phone, coordinates, stock level/status, aisle/bay, pickup status. |
| `hd_stores` | Store directory / find stores near a postal code (geocoded → distance-sorted with `distanceKm`), or the full national directory (~183 stores). |

More tools (suggestions, categories) are planned.

### `hd_search`

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `query` | string | — | Search keyword (required). |
| `storeId` | string | `9999` | Store id for store-specific stock/pricing. |
| `lang` | `en` \| `fr` | `en` | Response language. |
| `sort` | `relevance` \| `price-asc` \| `price-desc` \| `reviewAvgRating` | `relevance` | Sort order. |
| `page` | int | `0` | 0-indexed page. |
| `pageSize` | int (1–60) | `24` | Results per page. |

### `hd_product`

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `sku` | string | — | Product SKU / code (required), e.g. `1001686659`. |
| `postalCode` | string | — | Postal code, e.g. `M5V 2T6`; uses the nearest store (overrides `storeId`). |
| `storeId` | string | `7074` | Store id for store-specific price/stock/aisle. Override default with `HD_DEFAULT_STORE`. |
| `lang` | `en` \| `fr` | `en` | Response language. |

### `hd_store_availability`

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `sku` | string | — | Product SKU / code (required). |
| `postalCode` | string | — | Postal code; nearby stores are taken around it (overrides `storeId`). |
| `storeId` | string | `7074` | Reference store; nearby stores are taken from it. |
| `lang` | `en` \| `fr` | `en` | Response language. |
| `limit` | int (1–20) | `10` | Max number of stores to check. |

> **Default store:** product/availability tools default to store `7074` (Langford, BC).
> Set `HD_DEFAULT_STORE` env var, or pass `storeId`, to use your local store.
> Use `hd_stores` with a postal code to find the right store id.

### `hd_stores`

| Param | Type | Default | Notes |
|-------|------|---------|-------|
| `postalCode` | string | — | Canadian postal code, e.g. `M5V 2T6`. Returns nearest stores with `distanceKm`. |
| `latitude` / `longitude` | number | — | Alternative to `postalCode` for proximity. |
| `lang` | `en` \| `fr` | `en` | Response language. |
| `limit` | int (1–200) | 20 / all | Max stores. Default 20 for a proximity search, all (~183) otherwise. |

> The store API geosorts by coordinates only, so a postal code is first geocoded via
> `api.zippopotam.us` (free, no key). `distanceKm` is computed locally (haversine).

## How it talks to Home Depot

`homedepot.ca/api/*` is behind **Akamai Bot Manager**, which gates on both the
HTTP version and the client's TLS (JA3) fingerprint. Node's native HTTP stack
(`fetch`/undici, `node:http2`) gets `403`. Only **`curl --http2`** is
allowlisted, so every request shells out to `curl`. No cookies are needed for
the public search APIs.

**Requirement:** `curl` with HTTP/2 support must be on `PATH` (standard on macOS
and most Linux distros).

## Build & run

```bash
npm install
npm run build
npm start          # runs the MCP server on stdio
```

Quick smoke test of the search layer:

```bash
node --input-type=module -e 'import {search} from "./dist/search.js"; console.log(await search({query:"drill", pageSize:3}))'
```

Inspect with the MCP Inspector:

```bash
npm run inspect
```

## Connecting a client

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`),
pointing at the built entrypoint:

```json
{
  "mcpServers": {
    "homedepot": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_homedepot/dist/index.js"],
      "env": { "HD_DEFAULT_STORE": "7074" }
    }
  }
}
```

`HD_DEFAULT_STORE` is optional (defaults to `7074`, Langford BC).

## Project layout

```
src/
  index.ts    MCP server + tool registration (stdio)
  hd.ts       curl --http2 transport for homedepot.ca
  search.ts   hd_search implementation + response mapping
  product.ts  hd_product + hd_store_availability (summary, buybox, storesvc APIs)
  stores.ts   hd_stores (store directory + postal-code geocode → nearest)
```

## License

[PolyForm Noncommercial License 1.0.0](./LICENSE.md) — free to use, modify and share
for **noncommercial** purposes. Commercial use requires a separate license from the author.