Developer & Agent Hub

Pipocando Festas — Portal do Desenvolvedor e Agentes de IA

Centro de integração técnica da Pipocando Festas e Eventos. Esta página reúne especificações de máquina, endpoints REST e o servidor MCP (Model Context Protocol) para que assistentes de IA (Claude, ChatGPT, Perplexity, Gemini) e sistemas externos consumam nossos serviços de recreação infantil e festas no Rio de Janeiro.

      MCP Server online: https://pipocando.org/api/mcp — Streamable HTTP, protocolo 2024-11-05. Compatível com Claude Desktop, Cursor, e qualquer cliente MCP.
    

1. MCP Server — Model Context Protocol

O Pipocando MCP Server é um servidor JSON-RPC 2.0 que expõe ferramentas e recursos da Pipocando diretamente a agentes de IA. Suporta o transporte Streamable HTTP e SSE conforme a especificação MCP 2024-11-05.

Endpoint e Manifesto

GET

https://pipocando.org/api/mcp — Descoberta: lista tools e resources
Manifesto: /.well-known/mcp/manifest.json

POST

https://pipocando.org/api/mcp — JSON-RPC 2.0 (initialize, resources/list, tools/call…)

Ferramentas Disponíveis (tools/list)

list_combos — Lista todos os combos prontos de recreação no RJ
check_date_availability — Verifica disponibilidade de equipes por data e bairro
calculate_quote — Calcula estimativa de pacote e equipe por número de crianças
get_party_faqs — FAQs sobre duração, chuva, pagamento e cobertura

Recursos Disponíveis (resources/list)

pipocando://catalog/combos — Catálogo JSON com 6 combos detalhados
pipocando://guide/teen-kits — Guia Markdown dos 5 kits teen
pipocando://guide/inflatable-safety — Normas de segurança de infláveis

Exemplo de handshake (cURL)

# Initialize
curl -sS -X POST https://pipocando.org/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# List resources
curl -sS -X POST https://pipocando.org/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/list"}'

2. CLI Oficial — `npx pipocando`

A Pipocando CLI é uma ferramenta de linha de comando para desenvolvedores e agentes consultarem combos, disponibilidade e FAQs sem escrever integrações manuais.

Instalação e Uso

# Sem instalação — rodar direto via npx
npx pipocando combos
npx pipocando services
npx pipocando check-date 2026-12-25 "Barra da Tijuca"
npx pipocando faq
npx pipocando docs
npx pipocando --version

npm Pacote: pipocando

3. OpenAPI 3.1 — Especificação da API REST

A especificação OpenAPI completa da Pipocando Festas API v1 está disponível em: https://pipocando.org/openapi.json

OpenAPI 3.1.0

Especificação com schemas tipados, operationIds únicos e exemplos de resposta para cada endpoint.

Acessar /openapi.json →

Manifesto MCP

Manifesto oficial /.well-known/mcp/manifest.json com tools e resources declarados.

Acessar manifesto →

Instruções para Agentes

Quando e como acionar a Pipocando, parâmetros recomendados e casos de uso.

agent-instructions.md →

LLMs Guide (llms.txt)

Arquivo semântico padrão para modelos de linguagem e crawlers de busca generativa.

Ver /llms.txt →

4. Endpoints REST Públicos — API v1

Todos os endpoints respondem em application/json; charset=utf-8 com CORS aberto:

GET

/api/v1/services — Catálogo geral de serviços
curl -s https://pipocando.org/api/v1/services

GET

/api/v1/combos — Combos prontos promocionais
curl -s https://pipocando.org/api/v1/combos

GET

/api/v1/availability — Disponibilidade e bairros cobertos
curl -s https://pipocando.org/api/v1/availability

GET

/api/v1/faq — Perguntas e respostas validadas
curl -s https://pipocando.org/api/v1/faq

POST

/api/mcp — MCP JSON-RPC 2.0 (ver seção 1 acima)

5. Rate Limiting, Versionamento e Deprecação

Todas as respostas da API incluem os headers de rate limit RFC padrão para que agentes possam auto-throttle:

RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 60
RateLimit-Policy: 120;w=60
API-Version: 1.0.0
Sunset: Wed, 31 Dec 2031 23:59:59 GMT
Deprecation: @2031-12-31

Ver política completa de versionamento e rate limiting →

6. Suporte Técnico — Pipocando Festas e Eventos

Dúvidas sobre integrações, novos endpoints ou parcerias técnicas: contato@pipocando.org | WhatsApp +55 (21) 98826-9004

Site oficial: pipocando.org