npm package: @jussiesouto/server-calenpro
Description: MCP Server para integração com a API Calenpro
Author: Jussie Souto
Latest version: 1.0.0

# 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

```bash
# 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:

```bash
# 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

```bash
npx mcp --apiKey SUA_CHAVE_API --function listServices
```

#### Listar Profissionais

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

#### Verificar Disponibilidade

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

#### Criar Agendamento

```bash
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 "cliente@exemplo.com" [--clientPhone "123456789" --notes "Observações"]
```

#### Atualizar Agendamento

```bash
npx mcp --apiKey SUA_CHAVE_API --function updateBooking --bookingId "id-do-agendamento" [--date "2025-03-26" --time "11:00" --clientName "Novo Nome" --clientEmail "novo@exemplo.com" --clientPhone "987654321" --notes "Novas observações"]
```

#### Cancelar Agendamento

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

#### Obter Detalhes do Agendamento

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

#### Listar Ferramentas Disponíveis

```bash
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:
```bash
# 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

```bash
# 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:

```bash
docker-compose up
```

### Usar Imagem do Docker Hub

```bash
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:

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

```bash
# 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

```bash
# 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
```