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

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)

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:

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