Wazza Test Server

Servidor HTTP simples para validar a infraestrutura MCP do Wazza como cliente MCP. Ele expõe endpoints HTTP simples para descoberta e chamada de ferramentas e também aceita MCP JSON-RPC 2.0 via POST /, permitindo testar o fluxo de cadastro, tools/list, persistência, exibição, tools/call, retorno ao IA Agent e observabilidade/replay no Wazza.

Stack

• Python 3.11+
• FastAPI
• Uvicorn
• Pydantic
• Docker

Ferramentas disponíveis

• echo: repete o texto enviado.
• get_business_hours: retorna o horário de atendimento.
• calculate: calcula expressões aritméticas simples com +, -, *, / e parênteses, sem uso de eval.
• calendar_list_events: lista eventos simulados do calendário.
• calendar_create_event: cria um evento simulado no calendário em memória.
• calendar_check_availability: verifica horários disponíveis simulados.
• calendar_delete_event: remove um evento simulado pelo event_id.

Instalação local

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Execução local

PORT=8080 uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload

A aplicação ficará disponível em http://localhost:8080.

Deploy no Railway

1. Crie um novo projeto no Railway apontando para este repositório.
2. Confirme que o Railway detectou o Dockerfile.
3. Defina a variável de ambiente PORT se necessário. O servidor usa PORT e faz fallback para 8080.
4. Faça o deploy.
5. Cadastre a URL pública gerada pelo Railway na tela de Integrações de IA do Wazza.

Interfaces suportadas

O servidor mantém duas formas de integração:

• Endpoints HTTP simples:
  • GET / para health check.
  • POST /tools/list para listar ferramentas.
  • POST /tools/call para chamar uma ferramenta.
• MCP JSON-RPC 2.0 via POST / para clientes que enviam os métodos MCP diretamente para a raiz do servidor.

Exemplos curl

GET /

curl http://localhost:8080/

Resposta esperada:

{
  "status": "ok",
  "server": "wazza-mcp-test-server"
}

POST /tools/list

curl -X POST http://localhost:8080/tools/list

POST /tools/call echo

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"echo","arguments":{"text":"Olá mundo"}}'

POST /tools/call get_business_hours

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"get_business_hours","arguments":{}}'

POST /tools/call calculate

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"calculate","arguments":{"expression":"5 * (3 + 2)"}}'

Resposta esperada:

{
  "content": [
    {
      "type": "text",
      "text": "25"
    }
  ]
}

POST /tools/call calendar_list_events

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"calendar_list_events","arguments":{"date":"amanhã"}}'

Resposta esperada:

{
  "content": [
    {
      "type": "text",
      "text": "Nenhum evento simulado encontrado em amanhã."
    }
  ]
}

POST /tools/call calendar_create_event

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"calendar_create_event","arguments":{"title":"Reunião com João","date":"amanhã","time":"14:00","duration_minutes":60}}'

Resposta esperada:

{
  "content": [
    {
      "type": "text",
      "text": "Evento criado: Reunião com João em amanhã às 14:00 por 60 minutos."
    }
  ]
}

POST /tools/call calendar_check_availability

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"calendar_check_availability","arguments":{"date":"amanhã","duration_minutes":60}}'

Resposta esperada:

{
  "content": [
    {
      "type": "text",
      "text": "Horários disponíveis em amanhã: 09:00, 10:30, 14:00 e 16:00."
    }
  ]
}

POST /tools/call calendar_delete_event

curl -X POST http://localhost:8080/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"name":"calendar_delete_event","arguments":{"event_id":"evt_1"}}'

Resposta esperada:

{
  "content": [
    {
      "type": "text",
      "text": "Evento evt_1 removido com sucesso."
    }
  ]
}

POST / MCP JSON-RPC initialize

curl -X POST http://localhost:8080/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Resposta esperada:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "wazza-mcp-test-server",
      "version": "1.0.0"
    }
  }
}

POST / MCP JSON-RPC tools/list

curl -X POST http://localhost:8080/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

POST / MCP JSON-RPC tools/call

curl -X POST http://localhost:8080/ \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"text":"Olá"}}}'

Resposta esperada:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Olá"
      }
    ]
  }
}

Erros

Erros de métodos JSON-RPC não relacionados à execução de ferramenta continuam retornando error no envelope JSON-RPC. Erros de tools/call retornam content e structuredContent.ok=false, conforme o exemplo na seção de respostas estruturadas.

Respostas estruturadas MCP

Todas as ferramentas mantêm compatibilidade com o formato MCP textual em content[].text e também retornam structuredContent para facilitar respostas naturais do IA Agent.

Exemplo calculate

{
  "content": [
    {
      "type": "text",
      "text": "O resultado é 699678."
    }
  ],
  "structuredContent": {
    "ok": true,
    "tool": "calculate",
    "result": {
      "expression": "1234 * 567",
      "value": 699678
    }
  }
}

Exemplo get_business_hours

{
  "content": [
    {
      "type": "text",
      "text": "Atendemos de segunda a sexta, das 08h às 18h."
    }
  ],
  "structuredContent": {
    "ok": true,
    "tool": "get_business_hours",
    "result": {
      "days": "segunda a sexta",
      "opens": "08:00",
      "closes": "18:00",
      "timezone": "America/Sao_Paulo"
    }
  }
}

Exemplo calendar_create_event

{
  "content": [
    {
      "type": "text",
      "text": "Evento criado: Reunião com João em amanhã às 14:00 por 60 minutos."
    }
  ],
  "structuredContent": {
    "ok": true,
    "tool": "calendar_create_event",
    "result": {
      "event_id": "evt_1",
      "title": "Reunião com João",
      "date": "amanhã",
      "time": "14:00",
      "duration_minutes": 60,
      "attendees": [],
      "description": ""
    }
  }
}

Exemplo calendar_list_events

{
  "content": [
    {
      "type": "text",
      "text": "Eventos simulados:\n- evt_1: Reunião com João em amanhã às 14:00 por 60 minutos."
    }
  ],
  "structuredContent": {
    "ok": true,
    "tool": "calendar_list_events",
    "result": {
      "date": "amanhã",
      "events": [
        {
          "event_id": "evt_1",
          "title": "Reunião com João",
          "date": "amanhã",
          "time": "14:00",
          "duration_minutes": 60
        }
      ]
    }
  }
}

Exemplo calendar_check_availability

{
  "content": [
    {
      "type": "text",
      "text": "Horários disponíveis em amanhã: 09:00, 10:30, 14:00 e 16:00."
    }
  ],
  "structuredContent": {
    "ok": true,
    "tool": "calendar_check_availability",
    "result": {
      "date": "amanhã",
      "duration_minutes": 60,
      "available_slots": ["09:00", "10:30", "14:00", "16:00"]
    }
  }
}

Exemplo calendar_delete_event

{
  "content": [
    {
      "type": "text",
      "text": "Evento evt_1 removido com sucesso."
    }
  ],
  "structuredContent": {
    "ok": true,
    "tool": "calendar_delete_event",
    "result": {
      "event_id": "evt_1",
      "deleted": true
    }
  }
}

Exemplo de erro de ferramenta

{
  "content": [
    {
      "type": "text",
      "text": "Não foi possível executar a ferramenta: Expressão inválida: divisão por zero não é permitida."
    }
  ],
  "structuredContent": {
    "ok": false,
    "tool": "calculate",
    "error": {
      "code": "tool_error",
      "message": "Expressão inválida: divisão por zero não é permitida."
    }
  }
}