# Servidor MCP para API ProDoctor Cloud

Servidor Model Context Protocol (MCP) que expõe a API Aberta do ProDoctor Cloud como ferramentas acessíveis por agentes de IA (Claude Code, Cursor, Codex, etc.) via protocolo STDIO.

## Arquitetura

```
src/
├── index.ts                  # Bootstrap MCP (server + handlers genéricos)
├── client/
│   └── prodoctor-api.ts      # Axios client + rate limiter (token-bucket) + retry
├── utils/
│   ├── dates.ts              # formatDate, formatObjectDates (ISO → dd/mm/yyyy)
│   └── strings.ts            # cleanString (normalização CPF/telefone)
└── tools/
    ├── index.ts              # Agregador central (ALL_TOOLS + TOOL_HANDLERS)
    ├── agenda.ts             # 10 tools — módulo Agenda completo
    ├── pacientes.ts          # 3 tools — listar, pesquisar, detalhar
    ├── usuarios.ts           # 2 tools — listar, detalhar
    └── procedimentos.ts      # 3 tools — pesquisar, detalhar, tabelas
```

### Princípios

- **Rate limiting**: token-bucket de 120 req/min que *aguarda* (nunca devolve 429 ao agente).
- **Retry**: backoff exponencial (2 tentativas) em 429/5xx.
- **Fim do filtro em memória**: buscas passam filtros server-side (PascalCase); fallback apenas sobre a página retornada.
- **Schemas tipados**: JSON Schema detalhado em cada tool — o agente sabe exatamente o que preencher.
- **Sem switch gigante**: dispatcher via `Map<name, handler>`, fácil de estender.

## Instalação e Configuração

### Pré-requisitos

- Node.js 18+
- npm

### Instalar

```bash
npm install
```

### Configurar credenciais

Copie `.env.example` para `.env` e preencha suas chaves:

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

```ini
PRODOCTOR_API_KEY="sua_chave_api_aqui"
PRODOCTOR_API_PASSWORD="sua_senha_api_aqui"
PRODOCTOR_TIMEZONE="-03:00"
PRODOCTOR_TIMEZONE_NAME="America/Sao_Paulo"
PRODOCTOR_BASE_URL="https://open-api.prodoctor.net"
```

> **Dica**: envolva valores com caracteres especiais em aspas duplas para evitar interpretação do `#` como comentário.

### Compilar e executar

```bash
npm run build
npm start
```

Ou em modo desenvolvimento:

```bash
npm run dev
```

## Ferramentas Disponíveis (18 tools)

### Agenda (10)

| Tool MCP | Endpoint API | Descrição |
|---|---|---|
| `agenda_listar_agendamentos` | `POST /Agenda/Listar` | Lista agendamentos do dia para um usuário |
| `agenda_buscar_agendamentos_paciente` | `POST /Agenda/Buscar` | Busca agendamentos de um paciente por período |
| `agenda_horarios_livres` | `POST /Agenda/Livres` | Busca horários livres na agenda |
| `agenda_inserir_agendamento` | `POST /Agenda/Inserir` | Insere novo agendamento |
| `agenda_alterar_agendamento` | `PUT /Agenda/Alterar` | Altera dados de um agendamento (remarcar) |
| `agenda_desmarcar_agendamento` | `PATCH /Agenda/Desmarcar` | Desmarca/cancela um agendamento |
| `agenda_excluir_agendamento` | `POST /Agenda/Excluir` | Exclui definitivamente um agendamento |
| `agenda_detalhar_agendamento` | `POST /Agenda/Detalhar` | Detalha informações de um agendamento |
| `agenda_buscar_por_status_tipo` | `POST /Agenda/BuscarPorStatusTipo` | Busca agendamentos por status/tipo |
| `agenda_alterar_status_agendamento` | `PATCH /Agenda/AlterarStatus` | Altera status de um agendamento |

### Pacientes (3)

| Tool MCP | Endpoint API | Descrição |
|---|---|---|
| `pacientes_listar` | `POST /Pacientes` | Lista pacientes (paginado, sem filtro) |
| `pacientes_pesquisar` | `POST /Pacientes` | Pesquisa por nome/CPF/telefone (server-side + fallback) |
| `paciente_detalhar` | `GET /Pacientes/Detalhar/{codigo}` | Detalha cadastro de um paciente |

### Usuários (2)

| Tool MCP | Endpoint API | Descrição |
|---|---|---|
| `usuarios_listar` | `POST /Usuarios` | Lista todos os usuários |
| `usuario_detalhar` | `GET /Usuarios/Detalhar/{codigo}` | Detalha um usuário específico |

### Procedimentos + Tabelas (3)

| Tool MCP | Endpoint API | Descrição |
|---|---|---|
| `procedimentos_pesquisar` | `POST /Procedimentos` | Pesquisa procedimentos por tabela/nome/código |
| `procedimento_detalhar` | `GET /Procedimentos/Detalhar/{tabela}/{codigo}` | Detalha um procedimento |
| `tabelas_procedimentos_listar` | `GET /TabelasProcedimentos` | Lista tabelas de procedimentos disponíveis |

## Integração com IDEs

O servidor é executado via STDIO. Configure seu cliente MCP apontando para:

```json
{
  "mcpServers": {
    "prodoctor": {
      "command": "node",
      "args": ["/caminho/absoluto/para/prodoctor-mcp-server/dist/index.js"],
      "env": {
        "PRODOCTOR_API_KEY": "sua_chave",
        "PRODOCTOR_API_PASSWORD": "sua_senha"
      }
    }
  }
}
```

Ou use o arquivo `.env` no diretório do servidor.

## Testes

```bash
node test-connection.js
```

Testa conexão direta com a API e o protocolo MCP via STDIO.

## Cobertura de Endpoints

Veja [ENDPOINTS-API.md](./ENDPOINTS-API.md) para o mapeamento completo de cobertura dos 66 endpoints da API. Módulos com cobertura total: **Agenda (10/10)**. Módulos parciais agora completos: **Pacientes (listar+detalhar)**, **Usuários (listar+detalhar)**, **Procedimentos (pesquisar+detalhar+tabelas)**. Módulos não-médicos ainda não implementados: Anamneses, Convênios, Domínios, Especialidades, Estoque, Exportações, Financeiro, Imagens, Impressos, Locais.

## Notas sobre campos presumidos

Campos inferidos sem spec oficial confirmada estão marcados no código-fonte com `// PRESUMIDO`. Eles facilitam o uso imediato mas podem divergir da API real — ajuste ao validar com a spec oficial.

## Autenticação e Rate Limit

- Headers: `X-APIKEY`, `X-APIPASSWORD`, `X-APITIMEZONE`, `X-APITIMEZONENAME`
- Limite da API: **120 requisições/minuto** — gerenciado automaticamente pelo token-bucket