Paxaver

Adaptador MCP para a plataforma comunitária escolar Paxaver — pedido de almoço dos alunos com verificação de alergias e preferências alimentares, carteiras, calendários escolares, voluntariado, associações e pagamentos. Mais de 25 ferramentas via Streamable HTTP com OAuth 2.1 + PKCE.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Paxaver

Adaptador voltado para IA sobre a plataforma comunitária escolar Paxaver. Implementa o Model Context Protocol (MCP) no Cloudflare Workers com validação de JWT RS256, autorização baseada em capacidades e transporte HTTP Streamable.

O que é isto

O servidor MCP Paxaver permite que assistentes de IA (ChatGPT, Claude, Perplexity e qualquer cliente compatível com MCP) ajam em nome de um usuário Paxaver: consultar um cardápio de almoço, fazer pedido de almoço, inscrever-se em eventos de arrecadação, ser voluntário e — para administradores escolares — gerenciar restaurantes, itens de cardápio, eventos e pedidos diários.

É um adaptador leve. Não contém lógica de negócio e nunca acessa diretamente o banco de dados, Stripe ou e-mail. Cada ação é delegada à API privada do backend Paxaver por meio de um service binding do Cloudflare (mesma região, sem salto de rede pública). As únicas responsabilidades do servidor MCP são:

Tratamento do protocolo MCP (JSON-RPC 2.0, Streamable HTTP)
Validação de JWT RS256 via JWKS do worker central de autenticação Paxaver
Política de capacidades por ferramenta e controle de papéis
Mapeamento de erros sanitizado e seguro para o usuário

A autenticação é tratada pelo worker de autenticação Paxaver (auth.paxaver.com), que atua como servidor de autorização OAuth 2.0 / OIDC. O servidor MCP valida os JWTs RS256 resultantes e os encaminha ao backend. O próprio servidor MCP não é um servidor de autorização.

Arquitetura

┌───────────────┐     MCP (Streamable HTTP)      ┌──────────────────────┐
│   AI Client   │ ─────────────────────────────▶ │   Paxaver MCP Worker │
│ ChatGPT/Claude│ ◀───────────────────────────── │  (this repo)         │
│  /Perplexity  │     RS256 JWT + JSON-RPC 2.0   │  Hono + jose         │
└───────────────┘                                └──────────┬───────────┘
                                                            │
                                          Cloudflare service binding
                                          (PAXAVER_API, same region)
                                                            │
                                                            ▼
                                                 ┌──────────────────────┐
                                                 │  Paxaver API Worker  │
                                                 │  (private backend)   │
                                                 │  D1 · Stripe · SES   │
                                                 └──────────────────────┘

O worker MCP nunca vincula D1, Stripe ou SES. O service binding carrega um JWT de curta duração (TTL de 120s, audiência paxaver-internal) que o backend confia como uma chamada interna, ainda assim atribuindo a ação ao usuário Paxaver autenticado. Consulte docs/architecture.md para o panorama completo.

Início rápido

Instalação

npm install @paxaver/mcp

Desenvolvimento local

# 1. Install dependencies (Node >= 22)
npm install

# 2. Run the worker locally (Miniflare)
npm run dev

# 3. Typecheck, lint, and test
npm run typecheck
npm run lint
npm test

O servidor de desenvolvimento local inicia em http://localhost:8787. Os endpoints de descoberta ficam em /.well-known/; o endpoint MCP é POST /mcp.

Observação: O desenvolvimento local sem o service binding PAXAVER_API usa como fallback HTTPS autenticado contra API_BASE_URL (padrão http://localhost:8787). Para testes de integração completos, execute o worker do backend Paxaver localmente e aponte API_BASE_URL para ele.

Implantação

Dois ambientes, cada um com um Worker separado e domínio personalizado próprio:

Ambiente	Nome do Worker	Domínio
`staging`	`paxaver-mcp-staging`	`mcp.paxaver.dev`
`production`	`paxaver-mcp`	`mcp.paxaver.com`

O worker de produção atende usuários do CA e dos EUA por meio de um único endpoint (mcp.paxaver.com). A região do usuário é resolvida pela claim tenant_id do JWT, e o worker roteia para o backend regional correto via service bindings (PAXAVER_API_CA, PAXAVER_API_US). A moeda é determinada pela escola do usuário, não pelo endpoint MCP.

npm run deploy:staging   # wrangler deploy --env staging
npm run deploy:prod      # wrangler deploy --env production

O worker não requer segredos. Consulte docs/deployment.md.

Ferramentas

O servidor expõe 26 ferramentas agrupadas em seis categorias. A visibilidade em tools/list é filtrada pelos papéis do chamador; cada chamada é reautorizada antes do envio, e o backend revalida o acesso em nível de dados (defesa em profundidade).

Categoria	Ferramentas
Usuário / conta	`get_user_info`
Carteira	`get_wallet_balance`, `get_wallet_status`
Pedidos e cardápio	`order_lunch`, `get_orders`, `get_daily_menu`, `get_daily_orders`, `get_monthly_orders`, `create_draft_order`, `finalize_order`, `cancel_order`
Eventos	`get_upcoming_events`, `create_event`, `update_event`, `cancel_event`, `register_event`, `sign_up_to_volunteer`
Admin / restaurante	`list_school_restaurants`, `create_restaurant`, `list_menu_items`, `create_menu_item`, `update_menu_item`, `set_menu_item_price`, `delete_menu_item`, `set_daily_menu`

Ferramentas financeiras e destrutivas são sinalizadas e exigem confirmação do usuário. Referência completa: docs/tools.md. Política de autorização: docs/authorization.md.

Privacidade

Nenhuma informação de contato pessoal (e-mail, telefone, endereço) é coletada ou retornada pelas ferramentas MCP. A ferramenta get_user_info retorna apenas o nome do usuário, escola, alunos e papéis. Os dados dos alunos são limitados a IDs, nomes e slugs de escola. Alergias, anotações, data de nascimento e outros dados pessoais não são expostos nas respostas de leitura. O servidor MCP não registra dados do usuário.

Documentação

Documento	Tópico
docs/architecture.md	Arquitetura do sistema, limite do service binding, isolamento regional
docs/authentication.md	Validação de JWT, JWKS, delegação do worker de autenticação, formato do token
docs/authorization.md	Tabela de política de capacidades, controle de papéis, defesa em profundidade
docs/tools.md	Referência completa de ferramentas com esquemas de entrada e classificações
docs/deployment.md	Configuração do Wrangler, ambientes, segredos, domínios personalizados
docs/security.md	Modelo de segurança, CORS, CSRF, sanitização de erros, cabeçalhos
docs/compatibility.md	Versão do protocolo MCP, transportes, clientes de IA compatíveis
docs/migration.md	Migração do `mcp-server/` legado no monorepo privado
CHANGELOG.md	Histórico de versões
SECURITY.md	Política de relato de vulnerabilidades
CONTRIBUTING.md	Configuração de desenvolvimento e processo de contribuição

Pilha tecnológica

Runtime: Cloudflare Workers (compatibility_date: 2026-08-01, nodejs_compat)
Framework: Hono v4
JWT: jose v6 (RS256 via JWKS)
Protocolo: MCP 2025-06-18, Streamable HTTP
Autenticação: Validação de JWT RS256 via worker central de autenticação (auth.paxaver.com)
Build/implantação: Wrangler v4
Testes: Vitest v2 (pool de Workers + pool de Node)

Paxaver

Documentação

Servidor MCP Paxaver

O que é isto

Arquitetura

Início rápido

Instalação

Desenvolvimento local

Implantação

Ferramentas

Privacidade

Documentação

Pilha tecnológica

Licença