shippo-mcp

Shippo AI

このリポジトリは、Shippo を使った AI 搭載の配送連携を構築するための総合的なリソースです。

以下が含まれています。

• 9 個のエージェントスキル：料金の比較、住所の検証、ラベルの購入（税関手続き込み）、荷物の追跡、一括配送、配送コストの分析、サポートチケットの下書き、連携のベストプラクティス、SDK／API のアップグレードを網羅する、AI アシスタント向けのワークフロー知識です。一度作成し、複数の AI 環境に配布しています。
• Claude Code プラグイン（providers/claude/plugin/）：--plugin-dir またはプラグインマーケットプレイス（/plugin marketplace add goshippo/ai）からインストールできます。
• OpenAI Codex プラグイン（providers/codex/plugin/）：Codex プラグインマーケットプレイスからインストールできます。スキルと OAuth MCP サーバーがバンドルされています。
• ClawHub スキル（providers/clawhub/skills/shippo/）：openclaw skills install @shippo/shippo でインストールできます。
• Claude アプリ（claude.ai／Desktop／Cowork）：プラグイン全体を、アップロード可能な単一の ZIP（shippo-plugin.zip）にパッケージ化し、すべての GitHub リリースに添付しています。アップロードすれば、すべてのスキルが利用可能になります。
• ナレッジパック（ChatGPT およびその他のチャットアシスタント）（providers/knowledge-pack/shippo-knowledge-pack.md）：SKILL.md フォルダーを読み込まないアシスタント向けの、統合された単一の Markdown ファイルです。ユーザーはこれをチャット、Custom GPT の Knowledge、または Project にコンテキストとして追加できます。配送に関する知識を提供し、実際の操作には引き続きホスト型 MCP コネクターを使用します。

スキルとは？

スキルとは、SKILL.md ファイル、YAML フロントマター（少なくとも name と description）、および AI アシスタントに特定のタスクの実行方法を指示する Markdown 形式の手順を含むフォルダーです。スキルには、参考ドキュメント、スクリプト、テンプレートをバンドルすることもできます。

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

エージェントは、段階的な開示によって、次の 3 段階でスキルを読み込みます。

1. 検出：起動時に、エージェントは各スキルの name と description のみを読み込み、関連する可能性があるかを判断するのに必要な情報だけを取得します。
2. 有効化：ユーザーのプロンプトがスキルの説明に一致すると、エージェントは SKILL.md の本文全体をコンテキストに読み込みます。
3. 実行：エージェントは手順に従い、作業中に参照ファイル（shippo/references/*.md）を必要に応じて読み込みます。

Agent Skills は、Anthropic が当初開発したオープンスタンダードです。同じ SKILL.md が Claude Code、Cursor、OpenAI Codex、GitHub Copilot、VS Code、および 30 以上の他のエージェントで動作します。

このリポジトリでは、skills/ にある 9 個のスキルが正式なソースです。同期スクリプトによって、これらは providers/claude/plugin/skills/ と providers/codex/plugin/skills/（1 対 1 のミラー）、providers/clawhub/skills/shippo/（統合ダイジェスト）、および providers/knowledge-pack/shippo-knowledge-pack.md（ChatGPT やその他のスキルを読み込まないアシスタント向けの、アップロード可能な単一のナレッジパック）へ自動的に反映されます。

Model Context Protocol（MCP）

Shippo は、ユーザーごとの OAuth を使うリモート MCP サーバーをホストしています。各ユーザーは Shippo を通じて一度認証するだけで、コピーする API キーはありません。Claude Code および OpenAI Codex のプラグインはこのエンドポイントを参照し、初回使用時にサインインを開始します。

URL	トランスポート	認証
https://mcp.shippo.com	Streamable HTTP	ユーザーごとの Shippo OAuth

各ツールの仕様と使い方については、Shippo MCP サーバーのドキュメントをご覧ください。

OpenAI で構築していますか？開発者向け設定（申請不要）については、OpenAI Responses API／Agents SDK から Shippo MCP を使用するをご覧ください。

機能

このリポジトリにある9つのスキルは、利用モード、つまり製品の画面ではなくユーザーが何をしているかに基づいて整理されています。AI アシスタントはユーザーの意図を3つのモードのいずれかに対応付け、適切なスキルを読み込みます。

判断：「どこから始めればよいですか？」

スキル	機能
shippo-best-practices	Shippo との連携、使用する API、テストモードとライブモードの使い分け、レスポンスの処理、重要なルールに関する判断を支援します

実行：「このワークフローを実行する」

スキル	機能
address-validation	米国および国際住所を検証、解析、標準化します
rate-shopping	USPS、UPS、FedEx、DHL、および30以上の配送業者の料金を比較します
label-purchase	通関処理を含む国内および国際配送ラベルを購入します
tracking	配送業者をまたいで荷物を追跡し、ステータス履歴、サブステータスコード、Webhook を確認します
batch-shipping	発送データの CSV ファイルを処理し、ラベルを一括生成します
shipping-analysis	コストを分析し、荷物の寸法を最適化し、配送業者を比較して、過去の支出を確認します
shippo-support-ticket	単一の発送またはラベルに関する、自動分類されルーティングタグが付いたサポートチケット（人間向け＋JSON）を作成します。読み取り専用で、Shippo のサポートエージェント向けです

メンテナンス：「アップグレードまたは移行する」

スキル	機能
upgrade-shippo	SDK バージョンのアップグレード、MCP サーバーの更新、互換性を破る変更への移行を案内します

必要なワークフロー（「ラベルを購入する」「この荷物を追跡する」など）がすでに分かっているユーザーは、実行用のスキルに直接進みます。初めて利用するユーザー（「配送を含むチェックアウトフローを構築しています。どこから始めればよいですか？」など）は、判断用のスキルから始め、適切な実行用スキルへ案内されます。本番環境の準備に関する質問がワークフローの内容と競合しないよう、メンテナンス用に独立したスキルを用意しています。

9つのスキルは、skills/shippo/references/ にある11個の共通リファレンスドキュメント（配送業者、通関、CSV 形式、エラーリファレンスなど）を活用します。スキルは必要に応じてリファレンスを読み込み、AI が11個すべてをコンテキストに取り込むのではなく、各ワークフローで必要なものだけを読み込みます。

インストール

Claude Code

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

または、プラグインマーケットプレイスからインストールします。

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

初回利用時に /mcp を実行し、Shippo サーバーを選択して、OAuth 経由で MCP を認証するためにサインインします（コピーが必要な API キーはありません）。

スキルは /shippo: 名前空間にあります。/shippo:rate-shopping、/shippo:label-purchase、/shippo:tracking などを使って直接呼び出すか、何をしているかを自然な言葉で説明してください。

OpenAI Codex

Codex は、このリポジトリのプラグインマーケットプレイスから Shippo プラグイン（スキル＋OAuth MCP）をインストールします。

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

詳細については、providers/codex/plugin/ を参照してください。（プラグインを使わずスキルの内容だけを取得する場合は、Codex の skill-installer で providers/codex/plugin/skills/<name> ディレクトリを個別にインストールすることもできます。）

ClawHub

openclaw skills install @shippo/shippo

（ClawHub registry では @shippo/shippo として公開されています。）

Claude アプリ（claude.ai / Desktop / Cowork）

Claude アプリでは、プラグインを1つの ZIP として読み込みます。shippo-plugin.zip（マニフェスト、OAuth MCP 設定、すべてのスキルを含むプラグイン全体）は、すべての GitHub Release に添付されています。ダウンロードして、アプリのプラグイン UI から追加してください。Team／Enterprise の管理者は、組織全体に一括でプロビジョニングできます。手順は、Organization settings → Plugins → shippo-plugin.zip をアップロード → 「Installed by default」を設定（またはグループに割り当て）です。これにより、すべてのスキルがメンバーに利用可能になります。（Organization settings でコード実行を有効にする必要があります。）

ZIP をローカルでビルドするには、npm run build:app-plugin を実行します（出力先は dist/app-plugin/ です）。

Shippo アカウント

Shippo アカウントが必要です。料金の取得と住所の検証は無料です。ラベルを購入すると、Shippo の割引配送業者料金が適用され、アカウントに請求されます。Claude Code および Codex のプラグインは、初回利用時に OAuth 経由でユーザーごとに認証されるため、コピーが必要な API キーはありません。

仕組み

このプラグインには、役割を意図的に分けた2つの要素が含まれています。

• スキル（このリポジトリ）：ツールをまたいだワークフローの説明です（チェックアウト、単一ラベル、バッチ処理のどれにするかの判断、「ライブモードのラベルを購入する前に確認する」といった UX の確認手順、CSV の取り込み、検証の順序、テストモードとライブモードの使い分け、レスポンスの処理ルールなど）。ユーザーのリクエストがスキルの説明に一致すると、スキルが有効化されて読み込まれます。
• MCP サーバー（ドキュメント）：ツールごとの意味を示します（ツール名、パラメーター、戻り値の形式、単一呼び出しに関する制約など）。各ツールの説明は簡潔で、1つの動詞句につきツールは1つです。ワークフローのガイダンスは、意図的にここでは重複させていません。

スキルは、複数の API 呼び出しを通じてどのように配送するかをアシスタントに教えます。MCP サーバーは、各ツールを呼び出す際の正確な情報をアシスタントに提供します。この2つの領域は、設計上、互いに重複しません。Stripe が採用している前例（簡潔な mcp.stripe.com のツール説明と、充実した stripe/agents のスキル）と同様です。そのため、MCP を直接利用するユーザーはツールごとの正確な意味を把握でき、スキルをインストールしたユーザーは矛盾のないワークフローの説明も利用できます。

リポジトリの構成

• skills/：スキルの標準コンテンツ（9つのスキルと11個の共有リファレンス）。ここを編集してください。それ以外はすべて、ここから生成されます。
• providers/claude/plugin/：Claude Code プラグインの配布用ファイル。scripts/sync.js によって標準コンテンツを1対1でミラーリングします。
• providers/codex/plugin/：OpenAI Codex プラグイン。skills/ は scripts/sync.js によって標準コンテンツを1対1でミラーリングします。手動で作成する .codex-plugin/plugin.json と .mcp.json には、マニフェストと OAuth MCP の接続設定を記述します。リポジトリルートの .agents/plugins/marketplace.json に登録されています。
• providers/clawhub/skills/shippo/：ClawHub バンドルの配布用ファイル。SKILL.md は、SKILL.md.template（手動で整えた導入部分）と標準のスキル本文から、scripts/compose-clawhub-digest.js によって自動生成されます。リファレンスは scripts/build-clawhub-bundle.js によって自動同期されます。
• dist/app-plugin/：Claude アプリ向けの単一の shippo-plugin.zip。providers/claude/plugin/ から scripts/build-app-plugin.js でビルドします（コミット対象外。必要に応じて、またリリース時に生成されます）。
• scripts/：同期、生成、ビルドを補助するスクリプトです。

作成

# 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 はすべての同期処理（Claude Code と Codex のミラーリング、ClawHub ダイジェストの生成、ClawHub リファレンスの同期）を実行し、結果に一貫性があることを検証します。CI でも同じコマンドを実行します。リポジトリにはサードパーティの依存関係がなく、スクリプトだけが含まれているため、npm install は不要です。

編集内容のプレビュー

• Claude Code： リポジトリのルートから claude --plugin-dir ./providers/claude/plugin を実行すると、ローカルプラグインを読み込んだ状態で Claude Code が起動します。skills/<name>/SKILL.md の編集内容はすぐに反映されます。スキルには /shippo: 名前空間が付いています（例：/shippo:rate-shopping）。
• ClawHub ダイジェスト： npm test の実行後、生成されたファイルは providers/clawhub/skills/shippo/SKILL.md にあります。直接開いて、ClawHub からインストールしたユーザーに表示される内容を確認してください。現在、ローカルサーバーでのプレビューには対応していません。

バージョン更新のルールやスキルコンテンツの相互参照の表現ルールなど、作成時の規約について詳しくは CONTRIBUTING.md を参照してください。

ライセンス

MIT