Tiendanube MCP

tiendanube-mcp

Tiendanube と Nuvemshop のアプリやインテグレーションを開発するための MCP サーバーです。

インストール

claude mcp add tiendanube -- npx -y @commenteme/tiendanube-mcp

Node >= 18 が必要です。クライアントは npx でサーバーを実行するため、インストールは不要です。Claude Desktop、Cursor、Windsurf、VS Code などのクライアントについては、その他のクライアントをご覧ください。

クイックスタート

クライアントを再起動し、自然言語で必要なことを尋ねてください。アシスタントがツールを選択します。

• 「POST /orders/{id}/fulfillment-orders/{id}/tracking-events に必要なスコープは何ですか？」
• 「署名検証付きで、order/paid と app/uninstalled のウェブフック受信処理を作成して」
• 「アプリ 1234 の OAuth インストールフローを生成して」
• 「フルフィルメント注文にはどんなウェブフックイベントがありますか？」
• 「NubeSDK のチェックアウトスロットはどのように機能しますか？」

含まれる内容

パートナーアプリや独自のインテグレーションを開発する方向けです。Admin API、OAuth、ウェブフック、NubeSDK、Admin アプリ、テーマに対応しています。

• 最新の公式ドキュメント：search-docs と read-doc は、nuvemshop.dev がエージェント向けに公開している Markdown ページを、英語、ポルトガル語、スペイン語で読み込みます。各回答にはページの URL が含まれます。
• ネットワーク接続不要の Admin API 2025-03 インデックス：228 個のエンドポイントと必要なスコープおよび参照ページ、18 個の OAuth スコープグループ、57 個のウェブフックイベントを収録しています。必須のプライバシー関連イベント 3 個は別途記載しています。
• スキャフォールディング：ウェブフック受信処理（生のボディに対する x-linkedstore-hmac-sha256 署名、即時の 200 応答、テスト付き）と OAuth フロー（state 付きリダイレクト、JSON ボディでの code 交換）。ツールは、クライアントが書き込めるよう、ファイル（パスと内容）を返します。
• 認証情報不要：ストアのトークンを要求せず、ディスクへの書き込みも行いません。接続先は nuvemshop.dev と tiendanube.dev のみです。

Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、GitHub Copilot、VS Code、Windsurf、および stdio トランスポートを使うあらゆる MCP クライアントで動作します。

開発の背景

Tiendanube には、会話しながらストアを操作するための公式 Admin MCP があります。商品作成、在庫や価格の調整、注文の確認、クーポンやプロモーションの管理ができます。ストアの操作が目的なら、そちらをご利用ください。プラットフォーム上で開発する人向けのサーバーはありませんでした。このサーバーは、使用するエンドポイント、スコープ、イベントを案内し、どのアプリにも必要となるコードを提供します。tiendanube-skills のスキルと併用できます。

ドキュメント

その他のクライアント

claude_desktop_config.json（Claude Desktop）、~/.cursor/mcp.json または .cursor/mcp.json（Cursor）、~/.codeium/windsurf/mcp_config.json（Windsurf）に設定します。

{
  "mcpServers": {
    "tiendanube": {
      "command": "npx",
      "args": ["-y", "@commenteme/tiendanube-mcp"]
    }
  }
}

VS Code の場合は .vscode/mcp.json に設定します。

{
  "servers": {
    "tiendanube": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@commenteme/tiendanube-mcp"]
    }
  }
}

Codex は CLI を使用します（設定は ~/.codex/config.toml に保存されます）。

codex mcp add tiendanube -- npx -y @commenteme/tiendanube-mcp

または、~/.codex/config.toml か、プロジェクトの .codex/config.toml に手動で設定します。

[mcp_servers.tiendanube]
command = "npx"
args = ["-y", "@commenteme/tiendanube-mcp"]

Gemini CLI は CLI を使用します（-s user を指定すると ~/.gemini/settings.json に保存されます。指定しない場合は、プロジェクトの .gemini/settings.json に保存されます）。

gemini mcp add -s user tiendanube npx -y @commenteme/tiendanube-mcp

GitHub Copilot CLI は ~/.copilot/mcp-config.json またはプロジェクトの .mcp.json に、上記と同じ mcpServers の JSON を設定します。VS Code では、Copilot は .vscode/mcp.json を使用します。

stdio トランスポートを使うクライアントであれば利用できます。コマンドは npx、引数は -y @commenteme/tiendanube-mcp です。Claude Code では、--scope project を指定すると設定が .mcp.json に保存され、チームと共有できます。

ツール

ツール	機能	ネットワーク
search-docs	ドキュメントの llms.txt インデックスを検索し、最初の3ページから最適なセクションを引用します。	はい
read-doc	URLまたはサイト内のパスを指定して、ページまたはセクションを読み込みます。他のドメインは拒否されます。	はい
lookup-endpoint	パス（実際のID、バージョン、ストアIDを指定可能）、リソース、またはキーワードから、完全なURL、スコープ、参照先を検索します。	いいえ
lookup-scope	OAuthスコープと、それらがアクセスするリソースを調べます。また、リソースまたはパスのスコープも調べられます。	いいえ
lookup-webhook-event	グループ別にWebhookイベントを調べ、登録方法と検証方法を確認します。	いいえ
scaffold-webhook-handler	署名検証と node:test によるテストを備えた、TypeScript の Express レシーバーを生成します。	いいえ
scaffold-oauth-callback	Express でのOAuthセットアップを生成します。state、codeの交換、アプリとストアごとの登録に対応します。	いいえ

データの出どころ

nuvemshop.dev のドキュメントにはオープンライセンスがないため、パッケージには含まれていません。search-docs と read-doc はドキュメントをその都度読み込み、プロセスの実行中のみメモリに保存します。data/ 内のファイルは、これらのページから scripts/ingerir.ts が作成した事実のインデックスです。メソッド、パス、リソース名、スコープ名、イベント名、および各ページへのリンクが含まれます。ドキュメントのテキストはパッケージに一切含まれません。ドキュメント内で見つかった矛盾は、tiendanube-skills/docs/divergencias.md に記載されています。

開発

git clone https://github.com/commentemeapp/tiendanube-mcp.git
cd tiendanube-mcp
npm ci
npm run check

npm run check が必須のチェックです。Prettier、型チェック、ビルド、テスト（ドキュメント用ツールは test/fixtures/ の合成ページを読み込み、ネットワークには接続しません）、クライアントとしてstdio経由でサーバーを起動する probar-mcp、および痕跡の検索を実行します。クライアントでテストするには、次のようにします。

claude mcp add tiendanube-local -- node /ruta/a/tiendanube-mcp/build/index.js

インデックスの更新

npm run ingerir を実行します。バージョン 2025-03 のリソースページ、llms.txt、認証、Webhookを取得し、data/ を書き換えます。その後、npm run check を実行し、data/ をコミットしてください。パッケージに必要です。

ブランチと公開

作業は dev から作成したブランチで行い、PRは dev に対して作成します。ローカルでテストした後、ブランチ全体をマージして dev を main に昇格させます。CIではNode 18、20、22で npm run check を実行します。

公開するには、package.json、server.json、CHANGELOG.md のバージョンを更新し、v* タグをプッシュします。publish.yml ワークフローが必須チェックを実行し、provenance 付きで npm に公開し、GitHub Releaseを作成して、server.json をMCP Registryに公開します。各バージョンの変更内容は CHANGELOG.md に記載されています。

貢献 · ライセンス

dev に対して、Conventional Commits に準拠し、npm run check が成功した状態でPRを作成してください。

MIT。パッケージに含まれるものと含まれないものについては、NOTICE をご覧ください。

---

commente.me が作成 · [email protected]