D1DX/airtable-skill

O que airtable-skill faz?

Habilidade Airtable para agentes de IA — MCP, API REST, API web interna, Omni AI, script, fórmulas, webhooks, automações e pegadinhas.

Visão Geral

Este guia consolida o conhecimento sobre a plataforma Airtable, com foco em como agentes de IA podem interagir com ela de forma eficiente. Inclui conexão via MCP (Model Context Protocol), chamadas REST diretas, a API web interna (Web API) para ações de interface, Omni AI para consultas em linguagem natural, scripts (Scripting), fórmulas poderosas, webhooks para reações a eventos, automações visuais e uma lista de pegadinhas (gotchas) que podem pegar desprevenidos.

Suporte a Plataformas

• Agentes: Claude Code, Cursor, Codex, GitHub Copilot, e qualquer agente que suporte MCP ou chamadas HTTP.
• Ferramentas: Airtable (qualquer plano), ferramentas de automação (Zapier, Make), e editores de script.

Funcionalidades Principais

1. MCP (Model Context Protocol)

O Airtable expõe um servidor MCP oficial (ainda em beta) que permite listar bases, tabelas, registros e realizar operações CRUD. Para usar:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["@airtable/mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "sua_chave_api"
      }
    }
  }
}

Ferramentas expostas:

• list_bases()
• list_tables(base_id)
• list_records(base_id, table_id, options)
• get_record(base_id, table_id, record_id)
• create_record(base_id, table_id, fields)
• update_record(base_id, table_id, record_id, fields)
• delete_record(base_id, table_id, record_id)

2. API REST

A API REST do Airtable é simples e direta. Base URL: https://api.airtable.com/v0/.

Autenticação: Cabeçalho Authorization: Bearer <chave_api>.

Exemplo de requisição (GET) para listar registros:

curl "https://api.airtable.com/v0/appXXXXXX/tblYYYYYY" \
  -H "Authorization: Bearer patZZZZZZ.xxxxxxxx"

Parâmetros úteis:

• maxRecords – limite de registros retornados (padrão 100, máximo 100000).
• view – filtra pela visualização nomeada.
• filterByFormula – filtra usando uma fórmula Airtable.
• sort – ordena campos (?sort[0][field]=Nome&sort[0][direction]=asc).
• fields – limita campos retornados.

3. API Web Interna (Web API)

A Web API (não documentada, mas estável) permite ações de interface como criar visualizações, alterar configurações de células e acionar ações de automação. Requer headers como x-airtable-application-id.

Endpoint: https://airtable.com/v0.3/

Exemplo de uso: Criar uma visualização em grade:

fetch('https://airtable.com/v0.3/view/create', {
  method: 'POST',
  headers: {
    'x-airtable-application-id': 'appXXXXXXXX',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ tableId: 'tblYYYYYY', name: 'Nova Visualização', type: 'grid' })
})

4. Omni AI

Omni AI é o assistente nativo do Airtable para consultas em inglês simples. Exemplo: "Mostre todos os pedidos atrasados do último mês". Ele traduz a consulta para fórmulas e filtros.

5. Scripting

Airtable suporta scripts em JavaScript (usando Node.js) que rodam no servidor. Você pode automatizar tarefas complexas.

let table = base.getTable('Pedidos');
let query = await table.selectRecordsAsync({fields: ['Status', 'Data']});
for (let record of query.records) {
  if (record.getCellValue('Status') === 'Pendente') {
    await table.updateRecordAsync(record.id, { 'Status': 'Processando' });
  }
}

6. Fórmulas

Fórmulas Airtable são expressões que lembram Excel. Suportam operadores, funções (IF, SUM, DATEADD, RECORD_ID()), e referências a campos.

Exemplo: Campo calculado que retorna "Atrasado" se a data de entrega passou:

IF(IS_AFTER(TODAY(), {Data de Entrega}), "Atrasado", "No prazo")

7. Webhooks

Webhooks disparam endpoints HTTP quando eventos ocorrem (criação, atualização, exclusão de registros). Configure no painel do Airtable ou via API REST.

Payload de exemplo (notificação de webhook):

{
  "base": {
    "id": "appXXXXXX",
    "name": "Minha Base"
  },
  "table": {
    "id": "tblYYYYYY",
    "name": "Pedidos"
  },
  "changedRecordsById": {
    "recZZZZZZ": {
      "current": {
        "cellValuesByFieldId": {
          "fldAAAA": "Processando",
          "fldBBBB": "2025-04-11"
        }
      }
    }
  }
}

8. Automações

Automações visuais (gatilhos + ações) podem ser criadas no Airtable sem código. Gatilhos incluem: "Quando um registro é criado", "Quando um campo é atualizado". Ações incluem enviar e-mail, criar registro no Salesforce, ou chamar webhook.

9. Pegadinhas (Gotchas)

Algumas coisas que podem te pegar:

• Limite de taxa (Rate limit): 5 requisições por segundo por base no plano gratuito; planos pagos têm limites maiores.
• Campos anexos: A API retorna objetos complexos, não URLs diretas.
• Tipos de dados: Números podem ser retornados como strings em alguns contextos (especialmente via webhook).
• Fórmulas: Não atualizam em tempo real; precisam de uma mudança para recalcular.
• IDs: IDs de registro (rec...) são estáveis, mas IDs de tabela (tbl...) podem mudar se a tabela for recriada.
• Campos obrigatórios: Ao criar registros via API, campos marcados como obrigatórios devem ser fornecidos, caso contrário ocorre erro 422.

Conclusão

Esta habilidade fornece uma base sólida para agentes de IA trabalharem com Airtable. Use o MCP para operações padrão, a API REST para mais controle, e fique atento às pegadinhas para evitar surpresas.