# Forge Geoapify MCP Server

Remote MCP server for Forge Lead Engine discovery.

It exposes exactly two tools:

- `search_businesses`
- `get_business_details`

## Security model

- `GEOAPIFY_API_KEY` stays only on the server.
- Fleet authenticates to the MCP server with `Authorization: Bearer <MCP_AUTH_TOKEN>`.
- The server never exposes the Geoapify secret in tool outputs, logs, or error bodies.

## What it does

- Searches Geoapify Places for candidate businesses.
- Normalizes only fields actually returned by Geoapify.
- Deduplicates by place ID and stable business/location fingerprints.
- Supports pagination, retries, rate-limit handling, timeouts, and malformed-response handling.
- Returns records for downstream Exa verification, Apollo enrichment, qualification, and scoring.
- Keeps outbound email, WhatsApp, follow-ups, and any sales sending disabled.

## Important workflow rule

A missing website from Geoapify does **not** mean the business has no website.

Downstream pipeline should be:

Geoapify discovery → dedupe → Exa website verification → Apollo contact enrichment → qualification → scoring → research → approval queue

No outbound email / WhatsApp behavior is included in this server.

## Local run

1. Install dependencies:

   ```bash
   npm install
   ```

2. Copy environment file:

   ```bash
   cp .env.example .env
   ```

3. Set `GEOAPIFY_API_KEY` and `MCP_AUTH_TOKEN` in `.env`.

4. Start the server:

   ```bash
   npm run dev
   ```

5. Health check:

   ```bash
   curl -s http://localhost:8787/healthz
   ```

6. MCP endpoint:

   ```bash
   curl -s -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://localhost:8787/mcp
   ```

## Deployment

### Recommended easy hosting

Use **Render** for the simplest free/easy setup.

### Steps

1. Create a web service from this repository.
2. Set environment variables:
   - `GEOAPIFY_API_KEY`
   - `MCP_AUTH_TOKEN`
3. Use the Dockerfile or build command:
   - Build: `npm install && npm run build`
   - Start: `npm start`
4. Ensure HTTPS is enabled.
5. Expose `/mcp` and `/healthz`.

### Recommended URL format

- Base: `https://<your-service-domain>`
- MCP endpoint: `https://<your-service-domain>/mcp`
- Health: `https://<your-service-domain>/healthz`

## Fleet custom MCP configuration

Use a Custom MCP server with:

- URL: `https://<your-service-domain>/mcp`
- Auth mode: Static Headers
- Header: `Authorization: Bearer <MCP_AUTH_TOKEN>`

Do **not** paste `GEOAPIFY_API_KEY` into Fleet. It stays only in the remote server environment.

## Health check

The health endpoint should return:

```json
{ "ok": true }
```

If the server is behind a platform health probe, point it at `/healthz`.

## Manual MCP test request

After deployment, the exact discovery test request is:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_businesses",
    "arguments": {
      "country": "UAE",
      "city": "Dubai",
      "category": "dental clinics",
      "max_results": 10
    }
  }
}
```