mcpField
S
square-automation

square-automation

github.com/sickn33その他48.7k66 回インストール1 日前に更新
リポジトリ

square-automation について

square-automationは、ComposioのSquareツールキットとRube MCPを通じて、Squareの決済、注文、店舗、請求書を扱うスキルです。IDの特定、権限の確認、変更後の検証を重視するワークフロー向けです。

主な機能

  1. 01決済の一覧表示と監視
  2. 02注文の検索と更新
  3. 03店舗の一覧表示
  4. 04請求書の一覧表示と管理
  5. 05ページネーションとバージョン確認

活用シーン

  1. 01決済履歴とステータスの確認
  2. 02Square店舗の注文検索
  3. 03条件を満たす請求書の確認やキャンセル
  4. 04許可された注文や決済の変更

MCP 対応

Rube MCPで最新のツールスキーマを取得し、ComposioのSquareツールキットにアクセスします。利用には有効なSquare接続が必要です。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill square-automation

インストール後、Claude Code で/square-automationを入力して読み込まれたか確認します。

詳細

Rube MCP による Square の自動化

Rube MCP を介して Composio の Square ツールキットを利用し、Square の決済処理、注文管理、請求書発行を自動化します。

前提条件

  • Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
  • square ツールキットを指定した RUBE_MANAGE_CONNECTIONS による Square への有効な接続
  • 最新のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP を取得する：クライアントの設定で https://rube.app/mcp を MCP サーバーとして追加します。現在の MCP とサービスの認証状態を確認してください。エンドポイントを追加するだけでは、認証済みの接続は確立されません。

  1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確認します
  2. ツールキット square を指定して RUBE_MANAGE_CONNECTIONS を呼び出します
  3. 接続が ACTIVE でない場合は、返された認証リンクを開いて Square OAuth を完了します
  4. ワークフローを実行する前に、接続ステータスが ACTIVE と表示されることを確認します

効果の境界

操作を行う前に、対象のアカウント、環境、IDを正確に特定してください。読み取り専用の一覧取得は、決済のキャンセル、注文や請求書の変更を許可するものではありません。具体的な操作の結果を事前に確認し、ユーザーが許可した操作のみを実行してください。返されたIDとステータスを記録し、書き込み結果が不明確な場合は再試行する前に状態を照合してください。また、リクエストが受理されたことを完了とみなさず、最終状態を確認してください。

主なワークフロー

1. 決済の一覧表示と監視

使用する場面：ユーザーが決済履歴の表示や決済ステータスの確認を希望する場合

ツールの順序：

  1. SQUARE_LIST_PAYMENTS - オプションのフィルターを使って決済を取得します［必須］
  2. SQUARE_CANCEL_PAYMENT - 必要に応じて保留中の決済をキャンセルします［任意］

主なパラメーター：

  • begin_time / end_time：日付範囲のフィルタリングに使用する RFC 3339 形式のタイムスタンプ
  • sort_order：時系列の並べ替えに使用する 'ASC' または 'DESC'
  • cursor：前回のレスポンスから取得したページネーションカーソル
  • location_id：特定のロケーションで決済を絞り込みます

注意点：

  • タイムスタンプは RFC 3339 形式で指定する必要があります（例：'2024-01-01T00:00:00Z'）
  • 結果が大量にある場合はページネーションが必要です。cursor がなくなるまで取得してください
  • キャンセルできるのは保留中の決済のみです。完了済みの決済には返金が必要です
  • SQUARE_CANCEL_PAYMENT には、一覧結果に含まれる正確な payment_id が必要です
2. 注文の検索と管理

使用する場面：ユーザーが条件に基づく注文の検索や注文詳細の更新を希望する場合

ツールの順序：

  1. SQUARE_LIST_LOCATIONS - 絞り込みに使うロケーションIDを取得します［前提条件］
  2. SQUARE_SEARCH_ORDERS - フィルターを指定して注文を検索します［必須］
  3. SQUARE_RETRIEVE_ORDER - 特定の注文の詳細を取得します［任意］
  4. SQUARE_UPDATE_ORDER - 注文の状態や詳細を変更します［任意］

主なパラメーター：

  • location_ids：検索対象のロケーションIDの配列（検索に必須）
  • query：日付範囲、状態、フルフィルメント種別を指定する検索フィルターオブジェクト
  • order_id：取得または更新する特定の注文ID
  • cursor：検索結果のページネーションカーソル

注意点：

  • SEARCH_ORDERS には location_ids が必須です。先に LIST_LOCATIONS でIDを取得してください
  • 注文の状態には OPEN、COMPLETED、CANCELED、DRAFT があります
  • UPDATE_ORDER では、競合を防ぐために現在の version フィールドが必要です
  • 検索結果はページ分割されています。cursor がなくなるまで取得してください
3. ロケーションの管理

使用する場面：ユーザーがビジネスロケーションの表示や詳細の取得を希望する場合

ツールの順序：

  1. SQUARE_LIST_LOCATIONS - すべてのビジネスロケーションを一覧表示します［必須］

主なパラメーター：

  • 必須パラメーターはありません。アクセス可能なすべてのロケーションが返されます
  • レスポンスには id、name、address、status、timezone が含まれます

注意点：

  • ほとんどの Square 操作（注文、決済）ではロケーションIDが必要です
  • 呼び出しの重複を避けるため、初回取得後はロケーションIDを必ずキャッシュしてください
  • 無効なロケーションも結果に含まれる場合があります。status フィールドを確認してください
4. 請求書管理

使用する場合: ユーザーが請求書の一覧表示、閲覧、またはキャンセルを希望する場合

ツールの実行順序:

  1. SQUARE_LIST_LOCATIONS - フィルタリング用のロケーション ID を取得します [前提条件]
  2. SQUARE_LIST_INVOICES - ロケーションの請求書を一覧表示します [必須]
  3. SQUARE_GET_INVOICE - 請求書の詳細情報を取得します [任意]
  4. SQUARE_CANCEL_INVOICE - 予定済みまたは未払いの請求書をキャンセルします [任意]

主要パラメーター:

  • location_id: 請求書の一覧表示に必須です
  • invoice_id: 取得/キャンセル操作に必須です
  • cursor: 一覧結果のページネーションカーソルです
  • limit: 1 ページあたりの結果数です

注意点:

  • LIST_INVOICES には location_id が必須です。まず LIST_LOCATIONS で解決してください
  • キャンセルできるのは SCHEDULED、UNPAID、または PARTIALLY_PAID の請求書のみです
  • CANCEL_INVOICE では競合状態を防ぐために請求書の version が必要です
  • キャンセルされた請求書はキャンセルを取り消せません

一般的なパターン

ID の解決

ロケーション名 -> ロケーション ID:

1. Call SQUARE_LIST_LOCATIONS
2. Find location by name in response
3. Extract id field (e.g., 'L1234ABCD')

注文の検索:

1. Call SQUARE_SEARCH_ORDERS with location_ids and query filters
2. Extract order_id from results
3. Use order_id for RETRIEVE_ORDER or UPDATE_ORDER
ページネーション
  • レスポンスの cursor フィールドを確認します
  • 次のリクエストの cursor パラメーターにカーソル値を渡します
  • cursor が存在しないか空になるまで続けます
  • limit を使用してページサイズを制御します
日付範囲のフィルタリング
  • RFC 3339 形式を使用します: 2024-01-01T00:00:00Z
  • 支払いの場合: begin_time および end_time パラメーター
  • 注文の場合: date_time_filter を使用したクエリフィルターを使用します
  • すべてのタイムスタンプは UTC です

既知の注意点

ID の形式:

  • ロケーション ID は英数字の文字列です (例: 'L1234ABCD')
  • 支払い ID と注文 ID はより長い英数字の文字列です
  • 他の操作を行う前に、必ずロケーション名を ID に解決してください

バージョン管理:

  • UPDATE_ORDER と CANCEL_INVOICE には現在の version フィールドが必要です
  • まずリソースを取得して現在のバージョンを取得します
  • バージョンの不一致は 409 Conflict エラーを返します

レート制限:

  • Square API にはエンドポイントごとのレート制限があります
  • 一括操作にはバックオフを実装します
  • 大規模なデータセットの場合、ページネーションに短い遅延を含めるようにします

レスポンスの解析:

  • レスポンスは data キーの下にデータをネストする場合があります
  • 金額は最小通貨単位です (USD の場合はセント)
  • 任意のフィールドにはフォールバックを用意して防御的に解析します

クイックリファレンス

タスクツールスラッグ主要パラメーター
支払いの一覧表示SQUARE_LIST_PAYMENTSbegin_time, end_time, location_id, cursor
支払いのキャンセルSQUARE_CANCEL_PAYMENTpayment_id
注文の検索SQUARE_SEARCH_ORDERSlocation_ids, query, cursor
注文の取得SQUARE_RETRIEVE_ORDERorder_id
注文の更新SQUARE_UPDATE_ORDERorder_id, version
ロケーションの一覧表示SQUARE_LIST_LOCATIONS(なし)
請求書の一覧表示SQUARE_LIST_INVOICESlocation_id, cursor
請求書の取得SQUARE_GET_INVOICEinvoice_id
請求書のキャンセルSQUARE_CANCEL_INVOICEinvoice_id, version

使用する場合

このスキルは、概要で説明されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

  • タスクが上記で説明した範囲に明確に一致する場合にのみ、このスキルを使用してください。
  • 出力を、環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
  • 必要な入力、権限、安全上の境界、または成功基準が欠けている場合は、停止して明確化を求めてください。

コメント

Markdown 対応