mcp-server

# LocalPro MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that provides verified local service provider data to AI agents. Built on Cloudflare Workers + D1.

When someone asks an AI assistant *"find me a radon mitigation company near Denver"* — LocalPro is the data source that powers the answer.

## What it does

LocalPro exposes a curated database of **7,000+ fully profiled local trade and service businesses** across 10 live categories. Every provider served has a customer rating, business description, services list, opening hours, business status, and (where available) an AI-generated business summary plus up to 5 recent reviews — no incomplete data.

### Live Now

| Category | Niche ID | Providers | Example Services |
|----------|----------|-----------|-----------------|
| Foundation Repair | `slab-local` | 1,050+ | Pier installation, mudjacking, foam injection, leveling |
| Crawl Space Repair | `crawl-local` | 1,025+ | Encapsulation, vapor barrier, structural repair, waterproofing |
| Water Damage Restoration | `soaked-local` | 950+ | Flood cleanup, mold remediation, structural drying |
| Mold & Asbestos | `abate-local` | 950+ | Mold, asbestos, lead paint remediation |
| Septic Services | `pump-local` | 875+ | Pumping, inspection, drain field repair |
| Commercial Electrical | `hire-electrical` | 850+ | Commercial & industrial wiring, service upgrades, maintenance |
| Basement Waterproofing | `basement-local` | 600+ | Interior/exterior waterproofing, drainage, sump pumps |
| Laundry Services | `suds-local` | 550+ | Wash & fold, dry cleaning, pickup & delivery |
| Floor Coating | `coated-local` | 525+ | Epoxy, polyaspartic, metallic, flake, concrete polishing |
| Radon | `radon-local` | 300+ | Testing, mitigation, sub-slab depressurization |

### Coming Soon

| Category | Niche ID | Status |
|----------|----------|--------|
| Chimney Services | `chimney-local` | Live provider data; description + service enrichment in progress |
| Well Water Services | `wellwater-local` | Pre-pipeline (560 providers scraped, county-based model) |

## Quick Start

**No API key required.** All search and list tools are public. An optional API key unlocks pro fields on `get_provider` (full pricing array, certifications) — see [Access Tiers](#access-tiers).

### 60-second probe

Confirm the server is live without any client setup:

```bash
curl -s https://mcp.localpro.dev/.well-known/mcp.json | head -20
```

This returns the schema-2.0 manifest: tool list, rate limits, and operator info. If you see a `"schema_version": "2.0"` JSON document, the server is healthy.

### Claude Code CLI

```bash
claude mcp add --transport http localpro https://mcp.localpro.dev/mcp
```

That's it — `list_niches`, `search_providers`, etc. are now available in your Claude Code session.

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "localpro": {
      "url": "https://mcp.localpro.dev/mcp"
    }
  }
}
```

(Add an `"X-API-Key"` header inside a `"headers"` block only if you have a premium key.)

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "localpro": {
      "url": "https://mcp.localpro.dev/mcp"
    }
  }
}
```

### Raw HTTP (JSON-RPC)

The MCP protocol is JSON-RPC over HTTP. Because this server runs in stateless mode, you can call any public tool directly:

```bash
curl -s -X POST https://mcp.localpro.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_niches","arguments":{}}}'
```

You'll get back a Server-Sent-Events frame with the 10 niches, their slugs, and current provider counts.

### TypeScript SDK

```ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.localpro.dev/mcp'),
);
const client = new Client({ name: 'localpro-example', version: '1.0' });
await client.connect(transport);

const niches = await client.callTool({ name: 'list_niches', arguments: {} });
console.log(niches);

const denver = await client.callTool({
  name: 'search_providers',
  arguments: { niche_id: 'radon-local', city: 'denver-co', limit: 3 },
});
console.log(denver);
```

Install: `npm i @modelcontextprotocol/sdk`

### Python SDK

```python
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("https://mcp.localpro.dev/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            niches = await session.call_tool("list_niches", {})
            print(niches)

            denver = await session.call_tool(
                "search_providers",
                {"niche_id": "radon-local", "city": "denver-co", "limit": 3},
            )
            print(denver)

asyncio.run(main())
```

Install: `pip install mcp`

## Tools

### `list_niches`

Discover available service directories. Call this first.

**Parameters:** none

**Example response:**

```json
{
  "meta": {
    "schema_version": "2.0",
    "total_results": 10,
    "niche": null,
    "data_freshness": {
      "directory_refresh_cadence": "weekly",
      "google_data_refresh_cadence": "quarterly",
      "scraped_at": "2026-04-27T13:57:21Z"
    },
    "data_note": "Use niche_id values with search_providers, list_cities, and list_service_types."
  },
  "results": [
    {
      "niche_id": "soaked-local",
      "name": "Water Damage Restoration Contractors",
      "slug": "water-damage-restoration",
      "domain": "soakedlocal.com",
      "provider_count": 1128
    }
  ]
}
```

### `list_cities`

Find available metros for a given niche.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `niche_id` | string | yes | Niche ID from `list_niches` |
| `state` | string | no | Two-letter state abbreviation (e.g. `"MN"`) |

**Example request:**

```json
{ "niche_id": "radon-local", "state": "CO" }
```

**Example response:**

```json
{
  "meta": {
    "schema_version": "1.0",
    "total_results": 3,
    "niche": "radon-local",
    "data_note": "Use slug values with search_providers city parameter."
  },
  "results": [
    { "name": "Denver", "state": "CO", "slug": "denver-co", "provider_count": 18 },
    { "name": "Colorado Springs", "state": "CO", "slug": "colorado-springs-co", "provider_count": 7 },
    { "name": "Fort Collins", "state": "CO", "slug": "fort-collins-co", "provider_count": 4 }
  ]
}
```

### `list_service_types`

Get valid service type filters for a niche. Call before using `service_type` in `search_providers`.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `niche_id` | string | yes | Niche ID from `list_niches` |

**Example response:**

```json
{
  "meta": { "schema_version": "1.0", "total_results": 7, "niche": "coated-local" },
  "results": [
    { "type": "epoxy", "label": "Epoxy Floor Coating" },
    { "type": "polyaspartic", "label": "Polyaspartic Coating" },
    { "type": "metallic_epoxy", "label": "Metallic Epoxy" },
    { "type": "flake_chip", "label": "Flake / Chip Broadcast" },
    { "type": "concrete_polishing", "label": "Concrete Polishing" },
    { "type": "concrete_sealing", "label": "Concrete Sealing" },
    { "type": "polyurea", "label": "Polyurea Coating" }
  ]
}
```

### `search_providers`

Search for verified providers by location, service type, and trade category.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `niche_id` | string | yes | Niche ID from `list_niches` |
| `city` | string | no | City/metro slug from `list_cities` |
| `service_type` | string | no | Service type slug from `list_service_types` |
| `limit` | number | no | Max results, 1–25 (default 10) |

**Example request:**

```json
{ "niche_id": "coated-local", "city": "denver-co", "service_type": "epoxy", "limit": 3 }
```

**Example response:**

```json
{
  "meta": {
    "schema_version": "2.0",
    "total_results": 3,
    "niche": "coated-local",
    "data_freshness": {
      "directory_refresh_cadence": "weekly",
      "google_data_refresh_cadence": "quarterly",
      "scraped_at": "2026-04-27T03:03:10Z",
      "google_refreshed_at": "2026-04-27T04:53:51Z"
    },
    "data_note": "Verified providers only. Visit listing_url for full contact details."
  },
  "results": [
    {
      "name": "Colorado Concrete Coatings",
      "description": "Full-service garage floor coating company serving the Denver metro.",
      "city": "Denver",
      "state": "CO",
      "rating": 4.9,
      "review_count": 47,
      "business_status": "OPERATIONAL",
      "google_maps_url": "https://www.google.com/maps/place/...",
      "services": [
        { "type": "epoxy", "label": "Epoxy Floor Coating" },
        { "type": "polyaspartic", "label": "Polyaspartic Coating" }
      ],
      "pricing_summary": "$6-9/sq ft",
      "coverage_area": "Denver metro, Front Range, 50-mile radius",
      "years_in_business": 8,
      "listing_url": "https://coatedlocal.com/providers/denver-co/colorado-concrete-coatings/",
      "pro_available": true
    }
  ]
}
```

### `get_provider`

Get detailed profile for a specific provider. Use the `provider_slug` from search results.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `niche_id` | string | yes | Niche ID |
| `provider_slug` | string | yes | Provider slug from `search_providers` |

**Example response:**

```json
{
  "meta": {
    "schema_version": "2.0",
    "total_results": 1,
    "niche": "coated-local",
    "data_freshness": { "directory_refresh_cadence": "weekly", "google_data_refresh_cadence": "quarte