Documentação

O Foral dá aos seus agentes de IA capacidades tipadas e governadas sobre os sistemas em que sua equipe já faz login — sem API pública, sem marionete de browser, sem código gerado que apodrece. Aqui está o que você ganha e como usar.

O que o Foral dá aos seus agentes

Um contrato: uma descrição declarativa, versionada e com fingerprint do que um sistema faz. Seus agentes chamam essas capacidades como tools tipadas via MCP — o mesmo sistema que um humano usa vira algo que um agente lê e opera, com segurança.

Você autoriza uma vez contra um sistema ao qual tem acesso; a partir daí seus agentes falam com ele pelo contrato, não por um script frágil de UI.

Leituras que simplesmente funcionam — sem browser em execução

As capacidades de leitura rodam direto contra a API interna do próprio sistema, com a sua sessão autorizada — sem Chromium, sem scraping, sem clique. Voltam como linhas tipadas, com identidade estável por registro, pro seu agente sincronizar sem reler o mundo.

Capacidades de um único registro são reutilizáveis e parametrizadas — uma tool serve qualquer registro daquele tipo, não só o que você olhou.

Escritas que permanecem aprovadas por humano

O Foral também aprende as operações de escrita do sistema. Toda escrita nasce DESLIGADA: nunca executa sem um humano aprovar a ação exata antes. O harness do seu app decide onde essa aprovação acontece; o Foral garante que a escrita não dispara em silêncio.

O Foral guarda só o shape da escrita — a operação e os nomes dos campos — nunca os valores.

O piso é inviolável

Fail-closed por padrão: uma capacidade que não valida não carrega — nunca degrada num sucesso vazio e errado.

Sua senha é digitada no formulário do seu próprio sistema. Ela nunca toca no Foral.

O Foral guarda o contrato — rotas e nomes de campo — nunca os valores dos seus dados.

Menor privilégio: o agente só faz o que o contrato permite explicitamente; leitura nunca vira escrita.

Um contrato que continua vivo

Cada capacidade carrega um fingerprint do seu shape. Quando o sistema muda, a próxima leitura traz um alarme — antes de dado torto entrar. Uma versão corrigida é re-cartografada, e você a adota explicitamente — nunca em silêncio.

Adote a nova versão com foral update SEU_SISTEMA --from <url> — ela valida o novo contrato antes de aplicar, e nunca troca um contrato que funciona por um quebrado.

Instale e rode — três comandos

1) Instale o runner uma vez: pipx install --include-deps 'foral[login]' && playwright install chromium. Só servir, sem login (ex.: servidor headless): pipx install foral, ou npm i -g @foral/cli.

2) Aponte pro contrato que você baixou: foral init ~/Downloads/SEU_SISTEMA.yaml. O primeiro uso se configura sozinho em ~/.foral — tenant por instalação, chave de cifra (criada uma vez, só o dono lê) e as pastas de contratos e sessões. Nada pra definir, nada pra adivinhar.

3) Faça login uma vez e sirva: foral login SEU_SISTEMA abre o login do seu sistema no browser — a sessão fica na sua máquina, cifrada (~30 dias). Depois foral serve SEU_SISTEMA é o servidor MCP ao qual o agente conecta. foral serve ~/Downloads/SEU_SISTEMA.yaml também funciona.

Times e CI podem sobrescrever qualquer default com variáveis de ambiente — FORAL_TENANT, SESSION_ENCRYPTION_KEY, CONTRATOS_DIR, SESSION_DATA_DIR, FORAL_HOME — o explícito sempre vence.

Configure cada agente

Claude Code: claude mcp add foral -- foral serve SEU_SISTEMA

Cursor (~/.cursor/mcp.json): {"mcpServers":{"foral":{"command":"foral","args":["serve","SEU_SISTEMA"]}}}

Codex (~/.codex/config.toml): [mcp_servers.foral] command = "foral" args = ["serve","SEU_SISTEMA"]

Seu próprio app: conecte no mesmo servidor MCP com qualquer SDK cliente de MCP — o agente então chama as capacidades do sistema como tools tipadas.

Ou entregue o setup ao seu agente

Você não precisa fazer os passos de terminal na mão — eles são exatamente o trabalho de um agente de código. Só dois momentos ficam humanos, por desenho: cartografar no sandbox (você loga no SEU sistema) e digitar sua senha quando o foral login abre o browser.

Depois de baixar o contrato, cole isto no Claude Code, Codex ou Cursor (troque NAME; o prompt vai em inglês — é para o agente): Set up Foral (docs: https://foral.dev/docs) on this machine for the system NAME: install the runner (pipx install --include-deps 'foral[login]' && playwright install chromium; install pipx first if missing); run foral init ~/Downloads/NAME.yaml; run foral login NAME — a browser opens and I sign in MYSELF, wait for me; register the foral MCP server in your own MCP config with command foral and args [serve, NAME] — no environment variables needed; tell me when to restart you; then list the foral tools and run one test read, showing me the typed rows.

Mantenha a sessão viva

O Foral lê usando a sessão capturada pelo foral login — ele nunca pede nem guarda sua senha. Essa sessão dura cerca de 30 dias.

Quando expira, as leituras param e você só roda foral login SEU_SISTEMA de novo. A sessão vive só na sua infraestrutura; nunca é enviada ao Foral.

Cartografe seu sistema, depois mantenha

No sandbox hospedado, aponte o Foral pro seu sistema e faça login. Aperte Descobrir e ele mapeia seu sistema sozinho — as leituras pelo app e a forma das escritas que ele declara (formulários e ações). Ao terminar, aperte de novo: cada passada alcança mais.

O mapa de cobertura mostra o que foi alcançado e os links que faltam — uma rota atrás de um registro específico, ou uma ação. Clique num link pra navegar até lá você mesmo; conforme navega e age, o Foral captura o que a passada automática não alcança sozinha — inclusive as escritas, que só disparam pela sua própria mão, nunca pela do Foral.

Quando estiver bom, baixe o contrato, instale o runner na sua infraestrutura, e seus agentes ficam com as capacidades pra sempre.