# creci-sp-api

API REST + MCP para consulta de corretores imobiliários de São Paulo (CRECI-SP).

## Stack

- **FastAPI** + **FastMCP 3.0** — REST e protocolo MCP
- **PostgreSQL 16** — banco de dados
- **SQLAlchemy async** + asyncpg — ORM
- **Docker Compose** — banco + app em um comando

## Rodando localmente

```bash
cp .env.example .env
# editar .env se necessário
docker compose up --build
```

API disponível em `http://localhost:8004`  
Docs em `http://localhost:8004/docs`

## Importar dados

Após o `docker compose up`, importar o CSV coletado:

```bash
docker compose exec app python scripts/import_csv.py /caminho/corretores_sp.csv
```

Ou de fora do container (banco exposto na porta 5432):

```bash
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/creci_sp \
  python scripts/import_csv.py corretores_sp.csv
```

## Endpoints

| Método | Rota | Descrição |
|--------|------|-----------|
| GET | `/corretores` | Lista com filtros: `?q=nome&cidade=SP&situacao=ativo` |
| GET | `/corretores/{creci}` | Dados de um corretor pelo CRECI |
| GET | `/corretores/stats` | Estatísticas gerais |
| GET | `/corretores/cidades` | Ranking de cidades |
| GET | `/health` | Health check |
| POST | `/mcp` | Endpoint MCP (StreamableHTTP) |

## MCP Tools

| Tool | Descrição |
|------|-----------|
| `buscar_corretor` | Busca por nome, CRECI, cidade ou situação |
| `corretor_por_creci` | Dados completos pelo número CRECI |
| `estatisticas_creci` | Total, ativos, top cidades |
| `listar_cidades_sp` | Todas as cidades com corretores |

## Deploy no Coolify

1. Criar novo recurso → **Docker Compose**
2. Apontar para este repositório
3. Configurar variáveis de ambiente:
   - `API_TOKEN` — token de autenticação Bearer
   - `DB_PASSWORD` — senha do PostgreSQL
4. Deploy

## Autenticação

Definir `API_TOKEN` no `.env`. Todas as rotas exigem:
```
Authorization: Bearer <token>
```
Deixar vazio para desabilitar autenticação.