Shippo MCP

Shippo AI

Este repositório é o balcão único para construir integrações de envio com IA com a Shippo.

Ele contém:

• 9 Habilidades de Agente: Conhecimento de fluxo de trabalho para assistentes de IA cobrindo cotação de tarifas, validação de endereço, compra de etiquetas (com alfândega), rastreamento de pacotes, envio em lote, análise de custos de envio, redação de tickets de suporte, melhores práticas de integração e atualizações de SDK/API. Escritas uma vez e distribuídas em múltiplas superfícies de IA.
• Plugin Claude Code (providers/claude/plugin/): Instale via --plugin-dir ou no marketplace de plugins (/plugin marketplace add goshippo/ai).
• Plugin OpenAI Codex (providers/codex/plugin/): Instale via o marketplace de plugins do Codex; inclui as habilidades e o servidor MCP OAuth.
• Habilidade ClawHub (providers/clawhub/skills/shippo/): Instale via openclaw skills install @shippo/shippo.
• Aplicativos Claude (claude.ai / Desktop / Cowork): Todo o plugin é empacotado como um único ZIP pronto para upload (shippo-plugin.zip), anexado a cada GitHub Release. Um upload provisiona todas as habilidades.
• Pacote de Conhecimento (ChatGPT e outros assistentes de chat) (providers/knowledge-pack/shippo-knowledge-pack.md): Um único markdown consolidado para assistentes que não carregam pastas SKILL.md. O usuário o insere em um chat, no Conhecimento de um GPT Personalizado ou em um Projeto como contexto. Ele fornece o conhecimento de envio; ações ao vivo ainda usam o conector MCP hospedado.

O que é uma habilidade?

Uma habilidade é uma pasta contendo um arquivo SKILL.md, frontmatter YAML (no mínimo: name e description) além de instruções em markdown que dizem a um assistente de IA como executar uma tarefa específica. Habilidades também podem incluir documentos de referência, scripts e modelos.

rate-shopping/
├── SKILL.md           # required: metadata + instructions
└── README.md          # optional: human-facing orientation

Os agentes carregam habilidades por divulgação progressiva em três etapas:

1. Descoberta: na inicialização, o agente carrega apenas o name e o description de cada habilidade, apenas o suficiente para saber quando ela pode ser relevante.
2. Ativação: quando um prompt do usuário corresponde à descrição de uma habilidade, o agente carrega o corpo completo do SKILL.md no contexto.
3. Execução: o agente segue as instruções, opcionalmente carregando arquivos referenciados (shippo/references/*.md) enquanto trabalha.

Agent Skills é um padrão aberto originalmente desenvolvido pela Anthropic. O mesmo SKILL.md funciona em Claude Code, Cursor, OpenAI Codex, GitHub Copilot, VS Code e mais de 30 outros agentes.

Neste repositório, as 9 habilidades em skills/ são a fonte canônica. Elas são propagadas para providers/claude/plugin/skills/ e providers/codex/plugin/skills/ (espelhos 1:1), providers/clawhub/skills/shippo/ (resumo consolidado) e providers/knowledge-pack/shippo-knowledge-pack.md (um pacote de conhecimento único pronto para upload para ChatGPT e outros assistentes que não carregam habilidades) automaticamente pelos scripts de sincronização.

Model Context Protocol (MCP)

A Shippo hospeda um servidor MCP remoto com OAuth por usuário. Cada usuário autoriza uma vez através da Shippo, não há chave de API para copiar. Os plugins Claude Code e OpenAI Codex apontam para esse endpoint e acionam o login no primeiro uso.

URL	Transporte	Autenticação
https://mcp.shippo.com	Streamable HTTP	OAuth Shippo por usuário

Para semântica e uso por ferramenta, consulte a documentação do servidor Shippo MCP.

Construindo com OpenAI? Veja Usando o Shippo MCP a partir da API Responses / Agents SDK da OpenAI para a configuração do desenvolvedor (nenhum envio necessário).

Capacidades

As 9 habilidades neste repositório são organizadas por modo de engajamento: o que o usuário está fazendo, não pela superfície do produto. O assistente de IA corresponde a intenção do usuário a um dos três modos e então carrega a habilidade certa.

Decidir, "por onde começo?"

Habilidade	O que faz
shippo-best-practices	Roteador de decisão para integrações Shippo, qual API usar, disciplina de modo de teste vs. ao vivo, tratamento de respostas, regras críticas

Fazer, "executar este fluxo de trabalho"

Habilidade	O que faz
address-validation	Validar, analisar e padronizar endereços dos EUA e internacionais
rate-shopping	Comparar tarifas entre USPS, UPS, FedEx, DHL e mais de 30 transportadoras
label-purchase	Comprar etiquetas de envio domésticas e internacionais com tratamento alfandegário
tracking	Rastrear pacotes entre transportadoras com histórico de status, códigos de subestado e webhooks
batch-shipping	Processar arquivos CSV de remessas e gerar etiquetas em lote
shipping-analysis	Analisar custos, otimizar dimensões de pacotes, comparar transportadoras, revisar gastos históricos
shippo-support-ticket	Criar um ticket de suporte auto-classificado e com tags de roteamento (humano + JSON) para uma única remessa ou etiqueta; somente leitura, para agentes de suporte da Shippo

Manter, "atualizar ou migrar"

Habilidade	O que faz
upgrade-shippo	Guia para atualizar versões de SDK, atualizações do servidor MCP, migração de mudanças que quebram compatibilidade

Um usuário que já sabe o fluxo de trabalho que precisa ("comprar uma etiqueta", "rastrear este pacote") vai direto para uma habilidade de Fazer. Um usuário começando do zero ("Estou construindo um fluxo de checkout com envio, por onde começo?") encontra a habilidade de Decidir, que o direciona para a habilidade de Fazer correta. A manutenção tem sua própria habilidade para que perguntas de prontidão para produção não concorram com o conteúdo do fluxo de trabalho.

As 9 habilidades dependem de 11 documentos de referência compartilhados em skills/shippo/references/ (transportadoras, alfândega, formato CSV, referência de erros, etc.). As habilidades carregam referências sob demanda, a IA não puxa todos os 11 para o contexto, apenas os que um determinado fluxo de trabalho precisa.

Instalação

Claude Code

git clone https://github.com/goshippo/ai.git
claude --plugin-dir ./ai/providers/claude/plugin

Ou instale pelo marketplace de plugins:

/plugin marketplace add goshippo/ai
/plugin install shippo@shippo

No primeiro uso, execute /mcp, selecione o servidor Shippo e faça login para autorizar o MCP via OAuth (nenhuma chave de API para copiar).

As habilidades são namespaced sob /shippo:: invoque diretamente com /shippo:rate-shopping, /shippo:label-purchase, /shippo:tracking, etc., ou apenas descreva o que você está fazendo em linguagem natural.

OpenAI Codex

O Codex instala o plugin Shippo (habilidades + MCP OAuth) do marketplace de plugins deste repositório:

codex plugin marketplace add goshippo/ai
codex plugin add shippo@shippo   # install the "shippo" plugin
codex mcp login shippo           # authorize the remote MCP over OAuth

Veja providers/codex/plugin/ para detalhes. (Para puxar apenas o conteúdo da habilidade sem o plugin, o skill-installer do Codex também pode instalar um único diretório providers/codex/plugin/skills/<name>.)

ClawHub

openclaw skills install @shippo/shippo

(Publicado como @shippo/shippo no registro ClawHub.)

Aplicativos Claude (claude.ai / Desktop / Cowork)

Os aplicativos Claude carregam o plugin como um único ZIP. shippo-plugin.zip (todo o plugin: manifesto, configuração MCP OAuth e todas as habilidades) está anexado a cada GitHub Release. Baixe-o e adicione-o via a interface de Plugins do aplicativo. Um administrador de Team/Enterprise pode provisioná-lo para toda a organização em uma única etapa: Configurações da organização → Plugins → enviar shippo-plugin.zip → definir "Instalado por padrão" (ou atribuir a um grupo), e todas as habilidades ficam disponíveis para os membros. (A execução de código deve estar habilitada nas Configurações da organização.)

Para construir o ZIP localmente: npm run build:app-plugin (saída em dist/app-plugin/).

Conta Shippo

Você precisará de uma conta Shippo. Obter tarifas e validar endereços não tem custo; comprar uma etiqueta usa as tarifas de transportadora com desconto da Shippo e cobra na sua conta. Os plugins Claude Code e Codex autorizam por usuário via OAuth no primeiro uso, então não há chave de API para copiar.

Como funciona

Este plugin agrupa duas coisas, com uma divisão deliberada de trabalho entre elas:

• Habilidades (este repositório): narrativa de fluxo de trabalho entre ferramentas: decisões de roteamento (checkout vs etiqueta única vs lote), portões de UX ("perguntar antes de comprar uma etiqueta em modo ao vivo"), ingestão de CSV, sequenciamento de validação, disciplina de modo de teste/ao vivo, regras de tratamento de respostas. Carregadas na ativação quando a solicitação do usuário corresponde à descrição de uma habilidade.
• Servidor MCP (docs): semântica por ferramenta: nome da ferramenta, parâmetros, formato de retorno, restrições de chamada única. Cada descrição de ferramenta é concisa, uma frase de verbo, uma ferramenta. A orientação de fluxo de trabalho é intencionalmente NÃO duplicada aqui.

As habilidades ensinam ao assistente como enviar em múltiplas chamadas de API. O servidor MCP dá ao assistente a verdade por chamada sobre cada ferramenta. As duas superfícies são disjuntas por design, mesmo precedente que a Stripe usa (descrições de ferramentas mcp.stripe.com concisas, habilidades stripe/agents ricas): assim, usuários MCP puros obtêm semântica precisa por ferramenta e usuários com habilidades instaladas obtêm adicionalmente a narrativa de fluxo de trabalho, sem contradição.

Estrutura do repositório

• skills/: conteúdo canônico das habilidades (9 habilidades + 11 referências compartilhadas). Edite aqui; todo o resto flui daqui.
• providers/claude/plugin/: distribuição do plugin Claude Code. Espelho 1:1 do canônico via scripts/sync.js.
• providers/codex/plugin/: plugin OpenAI Codex. skills/ é um espelho 1:1 do canônico via scripts/sync.js; .codex-plugin/plugin.json + .mcp.json (escritos à mão) carregam o manifesto e a configuração do MCP OAuth. Catalogado a partir de .agents/plugins/marketplace.json na raiz do repositório.
• providers/clawhub/skills/shippo/: distribuição do pacote ClawHub. O SKILL.md é gerado automaticamente a partir de SKILL.md.template (enquadramento curado manualmente) + corpos de habilidades canônicas via scripts/compose-clawhub-digest.js. As referências são sincronizadas automaticamente via scripts/build-clawhub-bundle.js.
• dist/app-plugin/: o único shippo-plugin.zip para os aplicativos Claude, construído a partir de providers/claude/plugin/ por scripts/build-app-plugin.js (não commitado; produzido sob demanda e no lançamento).
• scripts/: auxiliares de sincronização, composição e construção.

Autoria

# 1. Edit canonical content
vim skills/<skill-name>/SKILL.md
# (or skills/shippo/references/<name>.md, or providers/clawhub/skills/shippo/SKILL.md.template
#  if you're changing ClawHub-only framing)

# 2. Sync + verify (one command)
npm test

# 3. Commit canonical edits AND synced output together
git add -A && git commit -m "..."

npm test executa todas as etapas de sincronização (espelhos Claude Code + Codex, composição do resumo ClawHub, sincronização de referências ClawHub) e verifica se o resultado é internamente consistente. O CI executa o mesmo comando. Nenhum npm install é necessário, o repositório não tem dependências de terceiros, apenas scripts.

Visualize sua edição

• Claude Code: execute claude --plugin-dir ./providers/claude/plugin a partir da raiz do repositório para iniciar o Claude Code com o plugin local carregado. Edições em skills/<name>/SKILL.md são refletidas imediatamente. As habilidades são namespaced sob /shippo: (por exemplo, /shippo:rate-shopping).
• Resumo ClawHub: após npm test ser executado, a saída renderizada fica em providers/clawhub/skills/shippo/SKILL.md: leia diretamente para ver o que os usuários com ClawHub instalado obterão. Não há pré-visualização de servidor local hoje.

Veja CONTRIBUTING.md para a disciplina completa de autoria, incluindo as regras de incremento de versão e a regra de redação de referências cruzadas para conteúdo de habilidades.

Licença

MIT