Shippo MCP

Shippo AI

Este repositorio es la ventanilla única para crear integraciones de envío impulsadas por IA con Shippo.

Contiene:

• 9 Habilidades de Agente: Conocimiento de flujos de trabajo para asistentes de IA que cubren comparación de tarifas, validación de direcciones, compra de etiquetas (con aduanas), seguimiento de paquetes, envío por lotes, análisis de costos de envío, redacción de tickets de soporte, mejores prácticas de integración y actualizaciones de SDK/API. Escritas una vez y distribuidas en múltiples superficies de IA.
• Plugin de Claude Code (providers/claude/plugin/): Instala mediante --plugin-dir o el mercado de plugins (/plugin marketplace add goshippo/ai).
• Plugin de OpenAI Codex (providers/codex/plugin/): Instala a través del mercado de plugins de Codex; incluye las habilidades y el servidor MCP OAuth.
• Habilidad de ClawHub (providers/clawhub/skills/shippo/): Instala mediante openclaw skills install @shippo/shippo.
• Aplicaciones de Claude (claude.ai / Desktop / Cowork): Todo el plugin está empaquetado como un único ZIP listo para subir (shippo-plugin.zip), adjunto a cada lanzamiento de GitHub. Una sola subida aprovisiona todas las habilidades.
• Paquete de conocimiento (ChatGPT y otros asistentes de chat) (providers/knowledge-pack/shippo-knowledge-pack.md): Un único markdown consolidado para asistentes que no cargan carpetas SKILL.md. Un usuario lo coloca en un chat, en el Conocimiento de un GPT personalizado o en un Proyecto como contexto. Proporciona el conocimiento de envío; las acciones en vivo aún usan el conector MCP alojado.

¿Qué es una habilidad?

Una habilidad es una carpeta que contiene un archivo SKILL.md, frontmatter YAML (como mínimo: name y description) además de instrucciones en markdown que le indican a un asistente de IA cómo realizar una tarea específica. Las habilidades también pueden incluir documentos de referencia, scripts y plantillas.

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

Los agentes cargan habilidades mediante divulgación progresiva en tres etapas:

1. Descubrimiento: al inicio, el agente carga solo el name y description de cada habilidad, lo suficiente para saber cuándo podría ser relevante.
2. Activación: cuando una solicitud del usuario coincide con la descripción de una habilidad, el agente carga el cuerpo completo de SKILL.md en el contexto.
3. Ejecución: el agente sigue las instrucciones, cargando opcionalmente archivos referenciados (shippo/references/*.md) mientras trabaja.

Agent Skills es un estándar abierto desarrollado originalmente por Anthropic. El mismo SKILL.md funciona en Claude Code, Cursor, OpenAI Codex, GitHub Copilot, VS Code y más de 30 otros agentes.

En este repositorio, las 9 habilidades en skills/ son la fuente canónica. Se propagan a providers/claude/plugin/skills/ y providers/codex/plugin/skills/ (espejos 1:1), providers/clawhub/skills/shippo/ (resumen consolidado) y providers/knowledge-pack/shippo-knowledge-pack.md (un paquete de conocimiento único listo para subir para ChatGPT y otros asistentes que no cargan habilidades) automáticamente mediante los scripts de sincronización.

Protocolo de Contexto de Modelo (MCP)

Shippo aloja un servidor MCP remoto con OAuth por usuario. Cada usuario se autoriza una vez a través de Shippo, no hay clave API que copiar. Los plugins de Claude Code y OpenAI Codex apuntan a este endpoint y activan el inicio de sesión en el primer uso.

URL	Transporte	Autenticación
https://mcp.shippo.com	Streamable HTTP	OAuth de Shippo por usuario

Para la semántica y el uso por herramienta, consulta la documentación del servidor MCP de Shippo.

¿Construyendo sobre OpenAI? Consulta Uso del MCP de Shippo desde la API de Respuestas de OpenAI / SDK de Agentes para la configuración del desarrollador (no se requiere envío).

Capacidades

Las 9 habilidades de este repositorio están organizadas por modo de interacción: lo que el usuario está haciendo, no por superficie de producto. El asistente de IA hace coincidir la intención del usuario con uno de tres modos y luego carga la habilidad adecuada.

Decidir, "¿por dónde empiezo?"

Habilidad	Qué hace
shippo-best-practices	Enrutador de decisiones para integraciones de Shippo, qué API usar, disciplina de modo de prueba vs. producción, manejo de respuestas, reglas críticas

Hacer, "ejecutar este flujo de trabajo"

Habilidad	Qué hace
address-validation	Validar, analizar y estandarizar direcciones de EE. UU. e internacionales
rate-shopping	Comparar tarifas entre USPS, UPS, FedEx, DHL y más de 30 transportistas
label-purchase	Comprar etiquetas de envío nacionales e internacionales con manejo de aduanas
tracking	Rastrear paquetes entre transportistas con historial de estados, códigos de subestado y webhooks
batch-shipping	Procesar archivos CSV de envíos y generar etiquetas en lote
shipping-analysis	Analizar costos, optimizar dimensiones de paquetes, comparar transportistas, revisar gastos históricos
shippo-support-ticket	Crear un ticket de soporte auto-clasificado y etiquetado con enrutamiento (humano + JSON) para un solo envío o etiqueta; solo lectura, para agentes de soporte de Shippo

Mantener, "actualizar o migrar"

Habilidad	Qué hace
upgrade-shippo	Guía para actualizar versiones de SDK, actualizaciones del servidor MCP, migración de cambios importantes

Un usuario que ya conoce el flujo de trabajo que necesita ("comprar una etiqueta", "rastrear este paquete") va directamente a una habilidad de Hacer. Un usuario que empieza desde cero ("Estoy creando un flujo de pago con envío, ¿por dónde empiezo?") llega a la habilidad de Decidir, que lo enruta a la habilidad de Hacer correcta. El mantenimiento tiene su propia habilidad para que las preguntas de preparación para producción no compitan con el contenido del flujo de trabajo.

Las 9 habilidades se apoyan en 11 documentos de referencia compartidos en skills/shippo/references/ (transportistas, aduanas, formato CSV, referencia de errores, etc.). Las habilidades cargan referencias bajo demanda, la IA no trae los 11 al contexto, solo los que necesita un flujo de trabajo determinado.

Instalación

Claude Code

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

O instala desde el mercado de plugins:

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

En el primer uso, ejecuta /mcp, selecciona el servidor de Shippo e inicia sesión para autorizar el MCP mediante OAuth (no hay clave API que copiar).

Las habilidades están bajo el espacio de nombres /shippo:: invócalas directamente con /shippo:rate-shopping, /shippo:label-purchase, /shippo:tracking, etc., o simplemente describe lo que estás haciendo en lenguaje natural.

OpenAI Codex

Codex instala el plugin de Shippo (habilidades + MCP OAuth) desde el mercado de plugins de este repositorio:

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

Consulta providers/codex/plugin/ para más detalles. (Para extraer solo el contenido de las habilidades sin el plugin, el skill-installer de Codex también puede instalar un único directorio providers/codex/plugin/skills/<name>).

ClawHub

openclaw skills install @shippo/shippo

(Publicado como @shippo/shippo en el registro de ClawHub.)

Aplicaciones de Claude (claude.ai / Desktop / Cowork)

Las aplicaciones de Claude cargan el plugin como un único ZIP. shippo-plugin.zip (todo el plugin: manifiesto, configuración MCP OAuth y todas las habilidades) se adjunta a cada lanzamiento de GitHub. Descárgalo y agrégalo mediante la interfaz de Plugins de la aplicación. Un administrador de Team/Enterprise puede aprovisionarlo en toda la organización en un solo paso: Configuración de la organización → Plugins → subir shippo-plugin.zip → establecer "Instalado por defecto" (o asignarlo a un grupo), y todas las habilidades estarán disponibles para los miembros. (La ejecución de código debe estar habilitada en la Configuración de la organización).

Para crear el ZIP localmente: npm run build:app-plugin (salida en dist/app-plugin/).

Cuenta de Shippo

Necesitarás una cuenta de Shippo. Obtener tarifas y validar direcciones no tiene costo; comprar una etiqueta usa las tarifas de transportista con descuento de Shippo y se carga a tu cuenta. Los plugins de Claude Code y Codex autorizan por usuario mediante OAuth en el primer uso, por lo que no hay clave API que copiar.

Cómo funciona

Este plugin incluye dos cosas, con una división deliberada del trabajo entre ellas:

• Habilidades (este repositorio): narrativa de flujo de trabajo entre herramientas: decisiones de enrutamiento (checkout vs etiqueta única vs lote), puertas de UX ("preguntar antes de comprar una etiqueta en modo producción"), ingesta de CSV, secuenciación de validación, disciplina de modo prueba/producción, reglas de manejo de respuestas. Se cargan al activarse cuando la solicitud del usuario coincide con la descripción de una habilidad.
• Servidor MCP (docs): semántica por herramienta: nombre de la herramienta, parámetros, forma de retorno, restricciones de llamada única. Cada descripción de herramienta es concisa, una frase verbal, una herramienta. La guía de flujo de trabajo no se duplica aquí intencionalmente.

Las habilidades le enseñan al asistente cómo enviar a través de múltiples llamadas API. El servidor MCP le da al asistente la verdad por llamada sobre cada herramienta. Las dos superficies están separadas por diseño, el mismo precedente que usa Stripe (descripciones de herramientas concisas de mcp.stripe.com, habilidades ricas de stripe/agents): así los usuarios de MCP puro obtienen semántica precisa por herramienta y los usuarios con habilidades instaladas obtienen además la narrativa del flujo de trabajo, sin contradicción.

Estructura del repositorio

• skills/: contenido canónico de habilidades (9 habilidades + 11 referencias compartidas). Edita aquí; todo lo demás fluye desde aquí.
• providers/claude/plugin/: distribución del plugin de Claude Code. Espejo 1:1 del canónico mediante scripts/sync.js.
• providers/codex/plugin/: plugin de OpenAI Codex. skills/ es un espejo 1:1 del canónico mediante scripts/sync.js; .codex-plugin/plugin.json + .mcp.json (escritos a mano) contienen el manifiesto y la configuración del MCP OAuth. Catalogado desde .agents/plugins/marketplace.json en la raíz del repositorio.
• providers/clawhub/skills/shippo/: distribución del paquete de ClawHub. El SKILL.md se genera automáticamente desde SKILL.md.template (marco curado a mano) + cuerpos de habilidades canónicas mediante scripts/compose-clawhub-digest.js. Las referencias se sincronizan automáticamente mediante scripts/build-clawhub-bundle.js.
• dist/app-plugin/: el único shippo-plugin.zip para las aplicaciones de Claude, construido desde providers/claude/plugin/ por scripts/build-app-plugin.js (no se confirma; se produce bajo demanda y en cada lanzamiento).
• scripts/: ayudantes de sincronización, composición y compilación.

Autoría

# 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 ejecuta todos los pasos de sincronización (espejos de Claude Code + Codex, composición del resumen de ClawHub, sincronización de referencias de ClawHub) y verifica que el resultado sea internamente consistente. CI ejecuta el mismo comando. No se necesita npm install, el repositorio no tiene dependencias de terceros, solo scripts.

Previsualiza tu edición

• Claude Code: ejecuta claude --plugin-dir ./providers/claude/plugin desde la raíz del repositorio para lanzar Claude Code con el plugin local cargado. Los cambios en skills/<name>/SKILL.md se reflejan inmediatamente. Las habilidades están bajo el espacio de nombres /shippo: (por ejemplo, /shippo:rate-shopping).
• Resumen de ClawHub: después de que npm test se ejecute, la salida renderizada está en providers/clawhub/skills/shippo/SKILL.md: léela directamente para ver lo que obtendrán los usuarios con ClawHub instalado. No hay vista previa de servidor local hoy.

Consulta CONTRIBUTING.md para conocer la disciplina completa de autoría, incluidas las reglas de incremento de versión y la regla de redacción de referencias cruzadas para el contenido de las habilidades.

Licencia

MIT