Numbers Native

Numbers Native

Website · Download · Italiano · MCP Registry · Support

Ferramentas nativas do Apple Numbers para Codex, por Viames Marino. Código aberto sob a Licença MIT.

O Numbers Native permite que o Codex crie, inspecione e edite documentos .numbers reais por meio do aplicativo Apple Numbers. O Numbers realiza os cálculos e salva seu próprio formato nativo. Sem conversão para Excel, biblioteca XLSX, gravador de arquivos com engenharia reversa, serviço MCP remoto ou chave adicional da API OpenAI.

A versão 0.5.0 é uma prévia. A verificação nativa local e as verificações de portabilidade não estabelecem compatibilidade em todos os Macs. Consulte verificação e cobertura de recursos.

Requisitos

• Um Mac com Apple Numbers instalado, em uma sessão gráfica com login ativo.
• Node.js 22 ou posterior, disponível no PATH do host do Codex.
• Um ambiente Codex que suporte servidores MCP stdio locais e marketplaces de plugins.
• Permissão para o host real exibido pelo macOS controlar o Numbers em Ajustes do Sistema → Privacidade e Segurança → Automação.

Esta versão usa Apple Events e não requer permissão de Acessibilidade. Ela não pode executar suas ferramentas nativas em um executor Linux/Windows ou em nuvem isolada.

Instalar no Codex

codex plugin marketplace add viames/numbers-native
codex plugin add numbers-native@viames-numbers

Inicie uma nova tarefa local do Codex e execute a skill de configuração. Você também pode adicionar https://github.com/viames/numbers-native por meio de Adicionar marketplace de plugins em clientes desktop compatíveis.

O exemplo sintético mostra um gráfico nativo atualizando para Materiali 150 EUR, total 265 EUR e residual 35 EUR.

Baixar uma versão

Descompacte o marketplace release em um diretório permanente. Ele contém .agents/plugins/marketplace.json e plugins/numbers-native/. O servidor empacotado inclui suas dependências JavaScript, portanto os usuários não precisam executar npm install.

Com um Codex CLI recente, a partir do diretório extraído:

codex plugin marketplace add .
codex plugin add numbers-native@viames-numbers

Inicie uma nova sessão do Codex e invoque @Numbers Native ou sua skill Numbers/setup. Em clientes desktop que suportam marketplaces de repositórios, abra este diretório extraído como um projeto e selecione o marketplace Viames Numbers em Plugins. Versões do host e políticas de espaço de trabalho podem afetar a descoberta do marketplace; o registro via CLI é explícito.

Se o seu host desktop não conseguir encontrar node, instale o Node.js e garanta que ele esteja no PATH desse host. Alternativamente, você pode registrar o servidor MCP diretamente na configuração MCP de um cliente compatível, usando o caminho absoluto do servidor extraído:

{
  "mcpServers": {
    "numbers-native": {
      "command": "node",
      "args": ["/absolute/path/to/numbers-native/plugins/numbers-native/dist/server.mjs"]
    }
  }
}

A configuração MCP bruta é um fallback para clientes que suportam MCP stdio; ela não instala as skills do plugin. Configure a conexão MCP direta do Codex com seu formato TOML nativo se usar essa rota. Não cole JSON em config.toml.

Execute a configuração e depois tente:

Crie um documento nativo do Numbers na minha pasta escolhida, com duas tabelas independentes e fórmulas para um orçamento mensal. Leia os totais e salve o arquivo .numbers.

Inspecione o documento do Numbers que eu identificar, encontre a tabela Expenses e atualize apenas os valores que eu fornecer.

Cobertura e limites

O plugin expõe 38 ferramentas MCP tipadas para documentos, modelos, planilhas, tabelas, leituras/gravações de intervalos, fórmulas nativas, formatação, limpar/mesclar, classificar/transpor, linhas/colunas, seleção, pesquisa, texto/formas/imagens e geometria de objetos existentes. Exportações opcionais de PDF/CSV são realizadas pelo próprio Numbers.

A versão 0.5.0 adiciona edições de células em múltiplas tabelas com proteção, verificações somente leitura de resultados nativos e anexação/upsert tipado de CSV/TSV. Consulte fluxos de dados. A versão 0.4.0 adicionou backup nativo/complementar completo, restauração e mover/renomear, prévias nativas de PDF/PNG (incluindo imagens guiadas de antes/depois) e diagnósticos locais de compatibilidade. Consulte fluxos de arquivo/prévia. A preservação de formato compatível, protótipos personalizados e atualizações guiadas de origem permanecem disponíveis. Ele mantém os 11 perfis de gráficos de modelos nativos. Consulte o novo fluxo. Gráficos de coluna, barra, pizza, rosca, radar, coluna interativa, coluna empilhada, área, eixo duplo, dispersão e bolha são suportados. Consulte o fluxo de gráficos. Gráficos de eixo duplo, dispersão e bolha mantêm legendas de eixo fixas (clima, consumo de combustível e vendas); use seus significados de dados documentados. Os perfis são verificados para Numbers 14.5 e falham explicitamente em versões não verificadas ou estruturas de modelo alteradas.

As chamadas de leitura/gravação são limitadas a 2.000 células, e as chamadas de inserir/excluir linhas/colunas a 100 itens. Navegue por tabelas grandes. Strings simples são texto literal, incluindo = inicial e zeros à esquerda. Fórmulas exigem { "formula": "=SUM(B2:B5)" }. Datas exigem { "date": "2026-10-18T10:30:00Z" }. Booleanos usam células de caixa de seleção nativas. O Numbers pode retornar fórmulas e valores formatados no idioma atual do documento.

Gráficos podem ser criados em novos documentos a partir de perfis de modelo verificados, com até 100 pontos e limites específicos de perfil de 1 a 10 colunas numéricas. As células de origem permanecem editáveis com as ferramentas normais do Numbers; o Numbers atualiza o gráfico conectado. Tipo de gráfico, referências de série, cores, título interno e inserção arbitrária em documentos existentes não são expostos. Um cabeçalho opcional é um item de texto nativo separado. Criação de tabela dinâmica, regras condicionais, comentários, colaboração, senhas, formatos numéricos detalhados e duplicação nativa permanecem sem suporte.

O Numbers salva automaticamente. As gravações não são atômicas e podem ser aplicadas parcialmente. Várias chamadas em um servidor e entre servidores de plugins cooperantes são serializadas, mas o usuário e outros aplicativos ainda podem editar simultaneamente. Inspecione o estado após erros; nunca repita automaticamente mutações com tempo esgotado. O plugin deixa documentos não relacionados abertos.

Privacidade e execução local

A ponte MCP não faz solicitações de rede, não escuta em uma porta de rede, não coleta telemetria nem envia documentos para um serviço separado. Entradas e resultados passam pelo Codex e podem ser enviados ao seu modelo de acordo com as políticas do host. Automação local não significa que todos os dados da planilha permanecem no dispositivo.

Por padrão, as ferramentas podem acessar caminhos locais explicitamente selecionados e documentos abertos identificados. Para restringir o acesso, defina NUMBERS_NATIVE_ALLOWED_ROOTS no ambiente do servidor MCP como um array JSON de diretórios absolutos existentes:

{ "NUMBERS_NATIVE_ALLOWED_ROOTS": "[\"/Users/your-user/Documents/Numbers\"]" }

Os caminhos são canonicalizados para rejeitar escapes de symlink. Esta é uma verificação adicional da ponte, não uma sandbox do SO para o Numbers em si. O Numbers pode resolver suas próprias dependências de arquivo. Detalhes de privacidade.

Desenvolver e verificar

npm ci
npm test
npm run build
npm run test:native
npm run test:charts
npm run test:guided
npm run test:files
npm run test:workflows
npm run package

test:native inicia o Numbers, cria seus próprios documentos temporários e testa seus resultados nativos. Ele nunca usa documentos do usuário como fixtures. Ele precisa de permissão de GUI/Automação e é separado do CI portátil. Os testes de unidade/MCP são executados em outros sistemas operacionais; as operações nativas não.

O processo de lançamento cria um ZIP de marketplace e um ZIP de plugin autônomo com runtime empacotado, skills, worker nativo, avisos e licença, além de somas de verificação SHA-256. Os mantenedores reconstroem a partir do lockfile fixado. O código-fonte não empacotado também é incluído no plugin autônomo para inspeção; o ZIP do marketplace contém o repositório de código-fonte completo.

Distribuição pública

O marketplace de código-fonte público é viames/numbers-native. As versões versionadas incluem o ZIP do marketplace do Codex, o ZIP do plugin autônomo, um pacote .mcpb do macOS, metadados de registro e somas de verificação SHA-256. Os clientes MCPB recebem as mesmas ferramentas nativas; o plugin do Codex também inclui skills. A identidade oficial do MCP Registry é io.github.viames/numbers-native; verifique seu registro ao vivo em vez de assumir que um envio de registro foi bem-sucedido. A distribuição por repositório/registro é separada da listagem no diretório oficial da OpenAI.

Conforme verificado em 18 de outubro de 2026, as regras de envio somente para desktop da OpenAI restringem envios MCP locais a parceiros aprovados e exigem que a organização que envia esteja na lista de permissões. Um pacote funcional não é prova de elegibilidade ou aprovação no diretório. Consulte etapas de publicação.

O Numbers Native é um projeto independente e não é afiliado ou endossado pela Apple ou OpenAI. O Apple Numbers é necessário e não está incluído.