Tags: goshippo/ai
Tags
AI-331: bridge 3.0.4 - pretty slugs, dxt packing fix + latest refresh… …, dispatch-only npm STAGE (OIDC) (#29) 3.0.4 metadata (canonical docs slugs, DXT manifest version sync) plus release-flow hardening: fix the .dxt packing so the extension contains its entry point (with a CI integrity gate), create bridge releases with --latest=false and auto-refresh the .dxt on the latest release, carry the .dxt forward onto new plugin releases, and a dispatch-only OIDC npm STAGE job (CI can stage but never release). npm 3.0.4 was already published from a byte-verified tarball. AI-331.
AI-275: @shippo/shippo-mcp v3 local bridge (stdio proxy to hosted, OA… …uth default + API-key) (#23) * feat(shippo-mcp): scaffold v3 bridge package and user-agent module * fix(shippo-mcp): enable allowImportingTsExtensions so the strict TS project type-checks * feat(shippo-mcp): cli config parsing and validation * feat(shippo-mcp): api-key auth headers * feat(shippo-mcp): per-host on-disk store for oauth state * feat(shippo-mcp): oauth provider, loopback callback, browser open * fix(shippo-mcp): handle browser-open and callback-listen errors so the bridge never crashes at sign-in * feat(shippo-mcp): stdio-to-http bridge with client-info user agent * fix(shippo-mcp): make bridge shutdown recursion-safe and preserve message order across upstream startup * feat(shippo-mcp): entrypoint wiring, oauth completion, signal handling * fix(shippo-mcp): unref the oauth callback listener so stdin EOF drains the bridge * test(shippo-mcp): opt-in dev-qa integration smoke * chore(shippo-mcp): readme, publish workflow, registry local variant, scheme pin recorded * fix(shippo-mcp): harden oauth flow and cli per final review (windows url quoting, stable callback port, state check, key-door 401 message, sign-in failure exit, credential invalidation) * chore(shippo-mcp): package metadata, license in tarball, pr test workflow, npm ci, registry runtime hint * docs(shippo-mcp): correct closeCounterpart comment to match the promise-only guard * AI-275: surface upstream errors, guard --url, drop dead code (review) Structural-review fixes ahead of the Wednesday publish: - C1 (blocker): the bridge caught upstream failures to stderr and never answered the pending request id, so a 429, a 5xx, or the api-key key-door 401 hung the client for its full 60s request timeout with no signal, and silently defeated the key-door guidance message the code already composes. runBridge now, on a failed forward of a message that has an id, sends a JSON-RPC error back downstream (code -32603, upstream message, and the HTTP status in error.data); notifications (no id) stay stderr-only. Regression tests cover a 429, the key-door 401 message reaching the model, and the notification case. - I2: parseConfig now refuses a non-https --url to a non-local host (credentials are sent to it) and rejects an unparseable --url with a clear error; https and localhost http overrides still pass. Tested. - I1: README leads the api-key quickstart with SHIPPO_API_KEY (keeps the key out of the process list); the --api-key flag is documented as the throwaway-test path. - Deleted the unused exported AuthContext interface. 53 tests (52 pass, 1 gated skip), typecheck clean, pack unchanged at 4 files. * AI-275: use pure-x placeholder key forms so the secret-shape guard passes The validate check flags shippo_test_/shippo_live_ literals with non-placeholder suffixes (shippo_test_XXXX uppercase, shippo_test_abc, shippo_live_xyz, shippo_test_flag, shippo_live_env) as suspicious.exposed_secret_literal shapes. Rewrite all doc examples and test fixtures to the sanctioned pure-x forms (shippo_test_xxxxx / shippo_live_xxxxx). The flag-beats-env precedence test still distinguishes its two keys via the test_/live_ prefixes. No behavior change; 53 tests green. * AI-275: angle-bracket placeholder in the README env example (assignment shape is banned) The validate guard's pattern 1 flags any VARNAME=shippo_test_/live_ assignment shape regardless of suffix, so SHIPPO_API_KEY=shippo_test_xxxxx still failed. Use the sanctioned form: SHIPPO_API_KEY=<your-shippo-key>. Verified all three guard greps (assignment shape, real-looking suffix, token leak) clean locally using the workflow's exact patterns. * AI-275: headless/UA/401 hardening + DXT packaging Hardening: - isHeadless() now also flags SSH sessions and non-Linux hosts with no display, so OAuth fails fast with actionable guidance instead of opening a browser that cannot complete the loopback. A desktop MCP client (piped stdio, working GUI) stays interactive. Tested across the platform matrix. - isHttp401 matches the transport 401 or the stable key-door signature rather than a bare "401" that could appear incidentally in an unrelated error message. - The User-Agent built from the downstream client's clientInfo is stripped of control characters, so a client whose name carries CR/LF connects with a cleaned UA instead of undici rejecting the header. DXT packaging (Claude Desktop one-click install), mirroring stripe/ai: manifest.json, build-dxt.js (esbuild self-contained ESM bundle + pack), .dxtignore, .node-version, icon, and a build-dxt script. OAuth-default so install needs no config; optional API-key field for later. 62 tests (61 pass, 1 opt-in dev-qa skip), typecheck clean, npm build and DXT build both verified (npm and DXT bundles print v3.0.0 and speak MCP). Jira: https://shippo.atlassian.net/browse/AI-275 Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-275: rebuild npm package README on the shippo-mcp-standalone base The prior README was thin. Rebuild it on the richer shippo-mcp-standalone structure (Summary, Requirements, ToC, per-client Quick Start, Configuration, Updating, Troubleshooting, Features, Security, Support, About Shippo), with every command corrected for the v3 OAuth bridge: no `start` subcommand, no `--api-key-header`/`--shippo-api-version`; OAuth by default via `npx -y @shippo/shippo-mcp`, API-key fallback via SHIPPO_API_KEY. Adds the Shippo logo asset and a v3 Cursor deeplink. Only the npm package README (tools/modelcontextprotocol/README.md) changes; the repo root README is untouched. Jira: https://shippo.atlassian.net/browse/AI-275 Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-275: point DXT button at the tagged release + attach .dxt in CI The README "Add to Claude Desktop" button pointed at releases/latest, which on this monorepo resolves to the newest repo-wide release (the Shippo plugin, not the DXT) and 404s. Point it at the versioned tag asset (releases/download/shippo-mcp-v3.0.0/shippo.dxt) instead. To make that URL resolve, the publish workflow (on a shippo-mcp-v* tag) now builds the .dxt and creates/updates the matching GitHub release with it attached. Needs contents: write. Skipped on workflow_dispatch (no tag). If you publish npm by hand, create the release manually: npm run build-dxt && gh release create shippo-mcp-v3.0.0 shippo.dxt Jira: https://shippo.atlassian.net/browse/AI-275 Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-275: hide API-key auth verbiage (keep the code path live) Per request, comment out all user-facing API-key auth verbiage until the hosted key door ships, while leaving the functionality in the code: - cli.ts: drop the --api-key line from --help USAGE; parseConfig still parses --api-key / SHIPPO_API_KEY (restore note left in a comment). - README.md: API-key sections (Configuration, flags row, headless troubleshooting, Security key management/getting-a-key/best-practices, and the intro paragraph) wrapped in <!-- API-KEY-AUTH --> HTML comments; OAuth-only text stays visible. - manifest.json: removed the optional shippo_api_key user_config + its env mapping so the DXT is OAuth-only. JSON has no comments, so the exact block to restore is stashed in build-dxt.js. Functionality unchanged: --api-key/SHIPPO_API_KEY still select apiKey mode, buildApiKeyHeaders and the key-door 401 path are intact, and their tests still pass (62 tests, 61 pass + 1 skip). --help no longer mentions --api-key; DXT manifest still validates without user_config. Jira: https://shippo.atlassian.net/browse/AI-275 Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-275: remove npm publish from the tag workflow; npm publishing is manual Owner decision: GitHub Actions must not publish to npm. The tag workflow now only verifies the tagged code (ci/typecheck/test/build) and publishes the GitHub release with the .dxt asset the README button links to. npm publish runs manually from a verified local checkout (prepublishOnly still rebuilds). Dropped registry-url and the NPM_TOKEN_SHIPPO secret use; job renamed publish -> release. * AI-275: 3.0.1 - npm-compatible README note syntax, badge points at v3.0.1 release npmjs.com does not render GitHub alert syntax ([!NOTE] appeared as literal text on the 3.0.0 page); use a plain bold Note blockquote that renders on both GitHub and npm. Point the .dxt badge at the shippo-mcp-v3.0.1 release we will actually cut. The header logo needs no change: it is an absolute raw URL into main that 404s only until this PR merges, then heals on the existing 3.0.x npm pages at view time. server.json pin follows to 3.0.1. * AI-275: 3.0.2 - live-CDN logo + yellow NOTE badge (npm renders neither repo-relative pre-merge assets nor styled callouts) The header logo now uses the stable marketing-CDN SVG that is live today instead of the repo raw URL that 404s until this PR merges. npm strips all CSS/styling from README markdown, so a yellow blockquote background is not possible there; a yellow shields.io NOTE badge leads the callout instead, rendering colored on both GitHub and npm. The .dxt badge follows the version to the shippo-mcp-v3.0.2 release. * AI-275: 3.0.3 - drop the header logo, restore the plain bold Note callout Per review: no logo in the README header (renders wrong on npm), and the callout reads best as the plain bold Note blockquote. The .dxt badge follows to the shippo-mcp-v3.0.3 release. * ci: continue-on-error on the cosmetic PR-summary post step The validate check failed 3x tonight with all validation steps passing: the final github-script step 503'd fetching PR comments during a GitHub API incident (RequestError: <!DOCTYPE html> / Unicorn page). The sticky comment is a nicety; the validation steps above are the gate, so a comment-post flake must not red the check.
AI-302: batch skill - clarify per-shipment label retrieval (GetTransa… …ction), sibling to AI-301 (#25) * AI-302: add per-shipment batch label-retrieval guidance to batch-shipping skill Sibling to AI-301, which fixed the same nuance in the hosted MCP spec. A purchased batch does not expose each label URL inline; the batch-level label_url is a merged multi-label PDF (up to 100 labels/file) that cannot be split per order. To get a single shipment's label_url and tracking_number, call GetTransaction on batch_shipments[].transaction. - skills/batch-shipping/SKILL.md: new "Retrieving batch labels" note after the PURCHASED reporting step. - skills/shippo/references/tool-reference.md: same note under PurchaseBatch; plus GetBatch object_results filter (creation_failed/creation_succeeded/ purchase_failed/purchase_succeeded) and the INVALID batch_shipments[].messages pointer, mirroring AI-301. - Regenerated provider mirrors via `npm run sync` (claude, codex, clawhub SKILL.md + references, knowledge-pack). No hand edits to generated files. Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-302: bump ClawHub bundle version 1.4.3->1.4.4 so the skill change publishes The batch-label-retrieval edit changed the ClawHub bundle content; publish-clawhub only ships on a version bump, so the validate gate rejected 1.4.3==registry-latest. Bump the template version and regenerate the bundle. Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-302: bump app-plugin version 1.5.2->1.5.3 so release.yml re-cuts the plugin zip The batch-skill edit changed the claude/codex plugin skill files; release.yml only cuts a new shippo-plugin.zip on a version bump. Bump package.json and propagate via sync into marketplace.json + the claude/codex plugin.json. Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm * AI-302: add "Fixing an INVALID batch" recovery playbook to the batch skill The skill polled until VALID but had no branch for INVALID, leaving an agent stuck. Add a step-by-step recovery loop (find failures via object_results=creation_failed / batch_shipments[].messages / the errors roll-up; drop via RemoveShipmentsFromBatch or fix+re-add via AddShipmentsToBatch; re-poll until VALID; then purchase) and branch CSV step 6/7 on INVALID. Mirrors the op-level guidance already in AI-301. No version bump (the PR's existing 1.4.4/1.5.3 bumps cover this content). Claude-Session: https://claude.ai/code/session_01NMbdLFs6qSiBam885vyfLm
AI-295: correct by-id parameter casing across the skill; add 403/404 … …do-not-retry guidance (#24) * AI-295: correct by-id parameter casing across the skill; add 403/404 do-not-retry guidance The hosted server validates by-id parameter names case-sensitively, and the skill documented nearly all of them in snake_case (shipment_id, transaction_id, order_id, carrier_account_id, ...). Clients following our own docs hit 'Missing required field(s)' rejections, one of the most common live error classes (~5/day family measured for AI-292). tool-reference.md: all 24 by-id Required entries corrected to the exact deployed spelling (ShipmentId, OrderId, TransactionId, BatchId, CarrierAccountId, CarrierParcelTemplateToken, UserParcelTemplateObjectId, ServiceGroupId, ShippoAccountId, AddressId, Carrier/TrackingNumber on GetTrack, CurrencyCode, CarrierAccountObjectId on InitiateOauth2Signin; exceptions webhookId and v2 address_id). Parameter-naming note added; UpdateServiceGroup corrected to body object_id (PUT /service-groups has no path parameter). error-reference.md: documents the hosted validation-failure shape (isError:true 'Parameter validation failed ...' text) with casing guidance, keeps -32602 as the legacy note; adds 403 permission-denied and generic gateway-relay entries with do-not-retry-identical-inputs recovery. shippo-best-practices: two new critical rules (exact casing; never retry 403/404 with unchanged arguments). Version bumps per release guards: plugin 1.5.1 -> 1.5.2, ClawHub bundle 1.4.2 -> 1.4.3; CHANGELOG updated; all providers/ artifacts regenerated via npm run sync (guards pass). * AI-295: fix InitiateOauth2Signin redirect field to redirect_uri The InitiateOauth2Signin tool-reference entry documented `redirect_url`, but the hosted server's schema requires `redirect_uri` (required: ["redirect_uri","CarrierAccountObjectId"]). A client following the doc gets "Missing required field(s): 'redirect_uri'", exactly the failure class this PR set out to remove. Corrected the canonical skills/shippo/references/tool-reference.md and regenerated all provider mirrors (claude, codex, clawhub, knowledge-pack) via `npm run sync`. Added a matching note to the CHANGELOG 1.5.2 Fixed entry. Claude-Session: https://claude.ai/code/session_01B2T6GkH62Qv6uqZjNVe8a5
Release app-plugin v1.5.1 (re-cut stale Claude plugin zip with curren… …t content) (#15) * Release app-plugin v1.5.1 (re-cut with current content) Bumps package.json + marketplace.json + claude plugin.json + codex plugin.json 1.5.0 -> 1.5.1 (four-way version match) so release.yml re-cuts the Claude app-plugin release. The published v1.5.0 shippo-plugin.zip went stale: plugin content (README + 7 skills/references, the community-resubmission prep) landed on main after v1.5.0 without a version bump, and release.yml only re-cuts on a version bump, so the published asset never refreshed. Bumping to 1.5.1 ships the documented Fixed items. No skill/content change in this commit; version fields + CHANGELOG only. * ci: re-trigger required checks (validate + eval)
Add shippo-support-ticket skill: classified support-ticket builder (#2) * Add shippo-support-ticket skill: classified support-ticket builder New canonical skill that turns a single shipment identifier (tracking # + carrier, transaction/label ID, shipment ID, or order #/email) into an auto-classified support package for the Shippo support team: - A copy-paste human ticket block, and - A routing-tagged structured JSON block for the ticketing pipeline. Read-only: it documents and recommends (e.g. "refund this label") and never calls a write op. Classifies into one of eight canonical issue types (lost/delayed, unused-label refund, billing adjustment, address exception, customs, carrier-account, tracking-webhook, other), runs issue-type-specific Shippo MCP lookups, computes a triage timeline, and minimizes PII (object IDs + coarse geography only — no names/street lines). Audience is Shippo support agents. Conformed to repo conventions: name+description-only frontmatter (no per-skill version field — versioning stays in package.json), no manual INSTALL block (sync.js owns the derived-file banner), single-line description, provenance stamp drops the frontmatter-version read. Wiring: - skills/shippo-support-ticket/{SKILL.md,README.md} (canonical) - Synced 1:1 into the Claude Code and Codex plugin mirrors - Added a "Support Ticket Builder" section to the ClawHub digest template (bundle 1.3.4 -> 1.4.0) - Bumped package.json 1.4.0 -> 1.5.0 (propagated to both manifests), brings the skill count to 9 (1 Decide / 7 Do / 1 Maintain) in both READMEs, and added a CHANGELOG entry. * Replace em/en dashes with standard punctuation..the repo has a hard no-em-dash rule. Swap all 51 em dashes + 2 en dashes in the shippo-support-ticket SKILL.md and 9 em dashes in its README for commas/colons/semicolons/periods/parens, then regenerate the provider mirrors via npm run sync. * update ListTransactions has no server-side tracking_number filter, page and match tracking_number client-side. * increment skill count from 8 to 9 * add shippo-support-ticket to SKILL_NAMES and add test block for should and should-not trigger prompts * Drop unreliable order-number anchor; surface order ref + shipment extras in output --------- Co-authored-by: Joseph Friedrich <joseph.friedrich@Joseph-Friedrich-K9X1DVQLWR.local> Co-authored-by: Wyatt Shippo <wyatt.reid@shippo.com>
Shippo AI: Agent Skills and multi-surface distribution Canonical Agent Skills for Shippo shipping workflows (rate shopping, address validation, label purchase with customs, tracking, batch, cost analysis, best-practices routing, and SDK/API upgrades), distributed to Claude Code, OpenAI Codex, ClawHub, and the Claude apps, plus the hosted Shippo MCP (mcp.shippo.com, per-user OAuth). See README.md.