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.

Related MCP server: mcp-brasilapi

Instalação e Configuração

Pré-requisitos

• Node.js 18+

• npm

Instalar

npm install

Configurar credenciais

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

cp .env.example .env

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

npm run build
npm start

Ou em modo desenvolvimento:

npm run dev

Ferramentas Disponíveis (18 tools)

Agenda (10)

Pacientes (3)

Usuários (2)

Procedimentos + Tabelas (3)

Integração com IDEs

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

{
  "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

node test-connection.js

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

Cobertura de Endpoints

Veja 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