Calenpro API Tool para LLMs

Esta ferramenta permite que Modelos de Linguagem Grande (LLMs) interajam diretamente com a API de agendamentos Calenpro a partir da linha de comando. Ela fornece uma interface simples para realizar operações de agendamento como listar serviços, verificar disponibilidade e criar agendamentos.

MCP Server para Integração com n8n

Além da ferramenta de linha de comando, este projeto inclui um servidor MCP (Model Context Protocol) que permite a integração com n8n e outras ferramentas compatíveis com o protocolo MCP.

Instalação

# Clone o repositório
git clone <url-do-repositório>
cd mcp-calenpro

# Instale as dependências
npm install

# Compile o projeto
npm run build

# Link o pacote globalmente (opcional)
npm link

Uso

Você pode usar esta ferramenta diretamente com npx ou após vinculá-la globalmente:

# Usando npx
npx mcp --apiKey SUA_CHAVE_API --function <nomeDaFunção> [parâmetros]

# Ou se vinculado globalmente
mcp --apiKey SUA_CHAVE_API --function <nomeDaFunção> [parâmetros]

Opções de Linha de Comando

• -k, --apiKey: Sua chave de API do Calenpro (obrigatória)
• -u, --apiUrl: URL da API (padrão: https://api.calenpro.com)
• -f, --function: Função a ser chamada (obrigatória)
• -o, --output: Arquivo de saída para salvar os resultados (opcional)
• -h, --help: Exibir mensagem de ajuda

Funções Disponíveis

Listar Serviços

npx mcp --apiKey SUA_CHAVE_API --function listServices

Listar Profissionais

npx mcp --apiKey SUA_CHAVE_API --function listProfessionals [--serviceId "id-do-serviço"]

Verificar Disponibilidade

npx mcp --apiKey SUA_CHAVE_API --function checkAvailability --professionalId "id-do-profissional" --date "2025-03-25" [--serviceId "id-do-serviço"]

Criar Agendamento

npx mcp --apiKey SUA_CHAVE_API --function createBooking --professionalId "id-do-profissional" --serviceId "id-do-serviço" --date "2025-03-25" --time "10:00" --clientName "Nome do Cliente" --clientEmail "[email protected]" [--clientPhone "123456789" --notes "Observações"]

Atualizar Agendamento

npx mcp --apiKey SUA_CHAVE_API --function updateBooking --bookingId "id-do-agendamento" [--date "2025-03-26" --time "11:00" --clientName "Novo Nome" --clientEmail "[email protected]" --clientPhone "987654321" --notes "Novas observações"]

Cancelar Agendamento

npx mcp --apiKey SUA_CHAVE_API --function cancelBooking --bookingId "id-do-agendamento"

Obter Detalhes do Agendamento

npx mcp --apiKey SUA_CHAVE_API --function getBooking --bookingId "id-do-agendamento"

Listar Ferramentas Disponíveis

npx mcp --apiKey SUA_CHAVE_API --function list_tools [--category "Categoria da Ferramenta"]

Esta função lista todas as ferramentas disponíveis na API Calenpro, incluindo:

• Nome e descrição da ferramenta
• Categoria da ferramenta
• Parâmetros necessários e opcionais
• Schema completo da API para cada ferramenta, incluindo:
  • Endpoint da API
  • Método HTTP (GET, POST, PUT, DELETE)
  • Parâmetros de caminho ou consulta
  • Formato da requisição
  • Formato da resposta

Isso permite que LLMs entendam como usar cada ferramenta baseado no contexto da solicitação do usuário.

Exemplo:

# Listar todas as ferramentas
npx mcp --apiKey SUA_CHAVE_API --function list_tools

# Listar apenas ferramentas de uma categoria específica
npx mcp --apiKey SUA_CHAVE_API --function list_tools --category "Gerenciamento de Serviços"

Integração com LLMs

Esta ferramenta foi projetada para ser facilmente utilizada por Modelos de Linguagem Grande como GPT-4. Veja como um LLM pode usar esta ferramenta:

1. O LLM deve identificar a operação de agendamento necessária com base na solicitação do usuário
2. Ele deve construir o comando apropriado com os parâmetros necessários
3. Pode executar o comando usando a chave de API do usuário

Exemplo de prompt para um LLM:

Por favor, use a API Calenpro para verificar a disponibilidade do Dr. Silva na próxima semana para uma consulta.

Resposta do LLM:

Vou verificar a disponibilidade do Dr. Silva para a próxima semana. Vou executar:

npx mcp --apiKey SUA_CHAVE_API --function checkAvailability --professionalId "drsilva123" --date "2025-03-24"

Notas de Segurança

• Nunca codifique sua chave de API em scripts ou compartilhe-a publicamente
• A chave de API pode ser fornecida via linha de comando ou variável de ambiente
• Quando usado com LLMs, certifique-se de que medidas de segurança adequadas estejam em vigor para proteger sua chave de API

Chave de API de Teste

Para fins de teste, você pode usar a seguinte chave de API:

7R1ywRlpX3zE4RGS0v7a4RBFWzF_JGPc7HsvdEbINzM

Esta é apenas uma chave de demonstração e deve ser substituída pela chave real do usuário em ambiente de produção.

Uso com Docker

Construir e Executar Localmente

# Construir a imagem Docker
docker build -t calenpro-mcp .

# Executar o container
docker run -p 3010:3010 -e CALENPRO_API_KEY=7R1ywRlpX3zE4RGS0v7a4RBFWzF_JGPc7HsvdEbINzM calenpro-mcp

Ou usando docker-compose:

docker-compose up

Usar Imagem do Docker Hub

docker pull jussiesouto/calenpro-mcp
docker run -p 3010:3010 -e CALENPRO_API_KEY=sua_chave_api jussiesouto/calenpro-mcp

Configuração no n8n

No n8n, configure o cliente MCP (STDIO) com:

{
  "mcpServers": {
    "calenpro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CALENPRO_API_KEY",
        "jussiesouto/calenpro-mcp"
      ],
      "env": {
        "CALENPRO_API_KEY": "SUA_CHAVE_API_AQUI"
      }
    }
  }
}

Publicação no GitHub e Docker Hub

Publicar no GitHub

# Inicializar repositório Git (se ainda não existir)
git init

# Adicionar arquivos
git add .

# Commit das alterações
git commit -m "Implementação do servidor MCP para Calenpro"

# Adicionar repositório remoto
git remote add origin https://github.com/jussiesouto/calenpro-mcp.git

# Enviar para o GitHub
git push -u origin main

Publicar no Docker Hub

# Fazer login no Docker Hub
docker login

# Construir a imagem com a tag correta
docker build -t jussiesouto/calenpro-mcp:latest .

# Enviar para o Docker Hub
docker push jussiesouto/calenpro-mcp:latest