# ProspectMCP

Servidor **MCP** + **API REST** para prospectar negocios de Google Maps / Google Business:

- 🔍 **Búsqueda de negocios** por texto libre ("pizzerías en Palermo, Buenos Aires").
- 🌐 **Filtro con/sin página web** — ideal para encontrar negocios a los que venderles una web.
- ⭐ **Extracción de reviews** — hasta 5 con la API oficial de Google, o **todas** (paginadas) si configurás SerpAPI.
- 📱 **Detección de redes sociales** — si el negocio tiene web, se detectan sus links a Facebook, Instagram, X, LinkedIn, TikTok, YouTube y WhatsApp.
- 🤖 **Generador de prompt para Claude Code** — arma un prompt listo para que Claude Code construya la landing page del negocio basada en sus datos reales, sus mejores reviews y sus redes.

## Arquitectura

```
src/
├── providers/
│   ├── googlePlaces.ts   # Google Places API (New): búsqueda, ficha, reviews (máx. 5)
│   └── serpapi.ts        # SerpAPI (opcional): todas las reviews, paginadas
├── services/
│   ├── prospectService.ts # Lógica central: búsqueda + filtros, reviews, perfiles
│   ├── socialLinks.ts     # Detección de redes sociales en la web del negocio
│   └── promptBuilder.ts   # Prompt de landing page para Claude Code
├── mcp/server.ts          # Servidor MCP (stdio) para Claude
└── api/server.ts          # API REST con API keys (base para comercializar)
```

**Por qué APIs y no scraping directo:** Google bloquea agresivamente el scraping de Maps (captchas, bans de IP) y viola sus términos de servicio. Este proyecto usa la [Places API (New)](https://developers.google.com/maps/documentation/places/web-service/op-overview) oficial y, para el histórico completo de reviews, [SerpAPI](https://serpapi.com) — un servicio de pago que resuelve ese problema de forma estable. El diseño con *providers* permite enchufar otras fuentes más adelante.

## Configuración

1. Cloná el repo e instalá dependencias:

   ```bash
   npm install
   npm run build
   ```

2. Copiá `.env.example` a `.env` y completá:

   | Variable | Requerida | Descripción |
   |---|---|---|
   | `GOOGLE_PLACES_API_KEY` | ✅ | API key de Google Cloud con **Places API (New)** habilitada |
   | `SERPAPI_KEY` | opcional | Para extraer **todas** las reviews (sin ella: máx. 5) |
   | `API_KEYS` | opcional | Keys válidas para la API REST, separadas por coma |
   | `PORT` | opcional | Puerto de la API REST (default 3000) |
   | `DEFAULT_LANGUAGE` / `DEFAULT_REGION` | opcional | Defaults `es` / `AR` |

## Hostearlo como conector remoto (Render)

El servidor MCP tiene dos transportes:

- **stdio** (`dist/mcp/server.js`) — para correrlo localmente en tu máquina.
- **Streamable HTTP** (`dist/mcp/httpServer.js`) — para hostearlo y que cualquiera lo use con un link.

Para deployar en Render:

1. Pusheá el repo a GitHub y en Render elegí **New → Blueprint** apuntando al repo (detecta `render.yaml` solo).
2. Cargá `GOOGLE_PLACES_API_KEY` (y opcionalmente `SERPAPI_KEY` y `MCP_AUTH_TOKENS`) en el dashboard.
3. Tu conector queda en `https://<tu-app>.onrender.com/mcp`.

Con esa URL, cualquier persona lo agrega:

- **Claude web/desktop**: Configuración → Conectores → *Agregar conector personalizado* → pegar la URL.
- **Claude Code**: `claude mcp add --transport http prospectmcp https://<tu-app>.onrender.com/mcp`

**Seguridad/costos:** cada búsqueda consume TU cuota de Google Places y SerpAPI. Si el conector va a ser público, definí `MCP_AUTH_TOKENS` (tokens separados por coma) y repartí un token por cliente; los clientes lo mandan como header `Authorization: Bearer <token>`. Ojo: el plan free de Render duerme el servicio tras 15 min de inactividad (el primer request tarda ~30-60s en despertar); para uso comercial conviene el plan Starter.

## Uso como servidor MCP local (Claude Code / Claude Desktop)

Agregalo a Claude Code:

```bash
claude mcp add prospectmcp \
  --env GOOGLE_PLACES_API_KEY=TU_KEY \
  --env SERPAPI_KEY=TU_KEY_OPCIONAL \
  -- node /ruta/a/ProspectMCP/dist/mcp/server.js
```

O en `claude_desktop_config.json` / `.mcp.json`:

```json
{
  "mcpServers": {
    "prospectmcp": {
      "command": "node",
      "args": ["/ruta/a/ProspectMCP/dist/mcp/server.js"],
      "env": {
        "GOOGLE_PLACES_API_KEY": "TU_KEY",
        "SERPAPI_KEY": "TU_KEY_OPCIONAL"
      }
    }
  }
}
```

### Herramientas MCP disponibles

| Herramienta | Qué hace |
|---|---|
| `search_businesses` | Busca negocios con filtro `with_website` / `without_website` / `any` y rating mínimo |
| `get_business` | Ficha completa de un negocio por `place_id` |
| `get_reviews` | Extrae reviews (todas con SerpAPI; hasta 5 sin ella) |
| `get_business_profile` | Ficha + reviews + redes sociales en una sola llamada |
| `generate_website_prompt` | Prompt listo para Claude Code que arma la landing del negocio |

Ejemplo de flujo en Claude:

> "Buscá gimnasios en Rosario que **no tengan página web** y rating mayor a 4. Del más prometedor, traeme todas las reviews y generame el prompt para armarle la página."

## Uso como API REST

```bash
npm run start:api
```

| Endpoint | Descripción |
|---|---|
| `GET /health` | Estado del servicio |
| `GET /search?query=...&website_filter=without_website&min_rating=4` | Búsqueda con filtros |
| `GET /business/:placeId` | Ficha del negocio |
| `GET /business/:placeId/reviews?max_reviews=200` | Reviews |
| `GET /business/:placeId/profile` | Ficha + reviews + redes |
| `POST /business/:placeId/website-prompt` | Genera el prompt para Claude Code (body: `{ "language": "es", "style_notes": "..." }`) |

Con `API_KEYS` configurado, todas las rutas (salvo `/health`) exigen el header `X-API-Key`.

```bash
curl -H "X-API-Key: mi-key" \
  "http://localhost:3000/search?query=peluquerías%20en%20Córdoba&website_filter=without_website"
```

## Roadmap (comercialización)

- [ ] Panel web del proyecto: búsquedas guardadas, listas de prospectos, exportación CSV.
- [ ] Botón "Generar prompt para Claude Code" por negocio dentro del panel (el endpoint ya existe).
- [ ] Planes y facturación por API key (rate limiting + cuotas).
- [ ] Más providers de reviews y enriquecimiento (email finder, etc.).

## Licencia

MIT