Construa para o Ecossistema com Seu Próprio Agente

Construa extensões do SOIS com o agente de IA que você já usa (Claude, ChatGPT, Cursor, Gemini, ou qualquer ferramenta compatível com MCP). Você conecta seu agente ao servidor MCP do SOIS, constrói a extensão na sua própria máquina, depois faz o upload para análise e publicação. Você usa sua própria IA; o SOIS não cobra nada para construir.

Este é o caminho do ecossistema. Qualquer pessoa pode construir para o marketplace e ganhar com seus aplicativos. Você não precisa do portal do desenvolvedor para construir uma extensão personalizada; conectar seu agente é suficiente. O portal é onde você publica no marketplace e gerencia seus pagamentos. Veja Monetize seus apps para o modelo de receita.

Como funciona

  1. Conecte seu agente ao servidor MCP do seu workspace (OAuth, ou um token).
  2. Construa localmente contra a especificação do SOIS que seu agente lê via MCP.
  3. Valide com uma verificação estática gratuita até ficar limpo.
  4. Faça o upload do pacote. Ele é protegido, controlado e colocado na fila para análise.
  5. Analise e publique. Uma vez aprovado, sua extensão fica ativa no marketplace.

Conecte seu agente

As ferramentas de construção ficam no servidor MCP do seu próprio workspace, o mesmo endpoint abordado em MCP Server. Não existe um servidor de construção separado para configurar: você conecta uma vez e, como sua conta pode construir, as ferramentas de construção aparecem automaticamente na lista de ferramentas do seu agente. Elas são controladas por admin, então só aparecem para contas com capacidade de construção.

Server:     https://<your-workspace-host>/api/mcp
Discovery:  https://<your-workspace-host>/.well-known/mcp.json

Conectando: o caminho recomendado é OAuth. Adicione a URL do MCP ao seu cliente (Claude, ChatGPT, Cursor e outros); ele descobre o login e conecta sem nada para colar. Um token Bearer mais um cabeçalho X-Api-Key também funciona para clientes que não fazem OAuth. Veja MCP Server para o fluxo completo de conexão e detalhes de descoberta.

Seu agente então tem as ferramentas de construção disponíveis. Comece toda construção pedindo que ele leia as regras.

As ferramentas de construção

Tool O que ele faz
getExtensionRules O manifesto canônico, migração, permissão, toolkit, i18n, UI e regras de segurança. Chame isso primeiro.
getExtensionFrameSpec O contrato do frame do host para visualização local: a assinatura de montagem, tokens de tema, formato da API REST e do bundle.
createExtensionProject Cria um novo projeto de app. Retorna um project_id.
validateExtensionBundle Executa a verificação estática gratuita nos seus arquivos e retorna os problemas para corrigir. Execute quantas vezes quiser.
uploadExtensionBundle Envia seu bundle. Ele é protegido, controlado e, em caso de aprovação, colocado na fila para análise.
getExtensionStatus O status do ciclo de vida e o relatório de validação mais recente de um projeto.
listExtensionProjects Seus projetos e seus status.

Formato do bundle

Uma extensão é um pequeno pacote de arquivos:

File Finalidade
manifest.json A única fonte da verdade: id, entidades, modelo de dados, permissões, arquivos.
index.js A UI, escrita como um IIFE vanilla JavaScript que monta via window.AppExtension.mount. Nenhum framework no bundle.
toolkit.js Ferramentas opcionais do agente, seguindo o padrão examiner.
permissions.json Chaves de permissão que correspondem aos nomes das suas rotas.
migrations/ Tabelas de banco de dados chamadas ext_{name}_{table} com um id e uma coluna JSON data.
lang/ Arquivos de localidade, toda chave prefixada com ext_{name}.

Regras principais que seu agente aplica a partir de getExtensionRules:

  • Campos de negócio ficam dentro da coluna JSON data, não como colunas separadas.
  • Sem chaves estrangeiras entre extensões, sem DROP, TRUNCATE ou dropColumn em uma migração up(), sem SQL bruto, sem acesso a shell ou sistema de arquivos.
  • Estilize a UI com os tokens de tema --ext-* para combinar com o SOIS. Nunca codifique cores ou textos voltados ao usuário.

Valide antes de fazer o upload

validateExtensionBundle executa o mesmo portão estático gratuito que o servidor executa no upload, para que você possa corrigir problemas localmente primeiro. Ele verifica tipos de arquivo, segurança de migração, estrutura do manifesto, nomenclatura e i18n. O portão do lado do servidor é sempre autoritativo: passar localmente é uma conveniência, não uma garantia.

Upload, análise, publicação

Quando uploadExtensionBundle relata uma aprovação, seu bundle é armazenado em uma área de análise privada e seu projeto passa para análise. Um revisor verifica e ou aprova, o que publica no marketplace, ou devolve com feedback para você corrigir e enviar novamente.

Próximos passos