mcpField
R
recoup-platform-api-access

recoup-platform-api-access

github.com/recoupable生産性95.0k 回インストール1 日前に更新
リポジトリ

recoup-platform-api-access について

Recoupへのアクセス手順を示すエージェント向けスキルです。MCPを優先し、必要に応じてREST API、アーティスト名簿の確認、外部コネクター操作を行います。

主な機能

  1. 01Recoup MCPツールを優先
  2. 02REST APIで操作を補完
  3. 03アーティスト名簿とIDを確認
  4. 04コネクター操作とスキーマを参照
  5. 05Recoup経由でメールを送信

活用シーン

  1. 01名簿のアーティストとSNS情報を確認
  2. 02MCPにないAPI操作を実行
  3. 03コネクターの状態確認とデータ取得
  4. 04Recoupからレポートや通知を送信

MCP 対応

ホストが提供するRecoup MCPツールを先に確認し、対応できない操作にはREST APIを使うよう案内します。OAuthはホストが管理し、すべてのRESTエンドポイントや外部コネクターにMCPの対応機能があるわけではありません。

インストール

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

$npx skills add https://github.com/recoupable/skills --skill recoup-platform-api-access

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

詳細

Recoup — API アクセス

プラットフォームのアクセスレイヤーです。認証を行い、Recoup REST API と通信し、外部コネクターを呼び出します。ベース URL は https://api.recoupable.dev/api、ドキュメントは https://docs.recoupable.dev（/llms.txt、/llms-full.txt、OpenAPI JSON）です。

認証済み MCP ツールを優先する

まず、ホストの Recoup MCP カタログを確認してください。実際のスキーマと結果で要求された操作をカバーできる場合は、該当するツールを使用してください。プレフィックスはホストによって異なります。アーティストの一覧を確認するには list_artists を使用し、後続のリクエストは返された ID に紐付けてください。すべての REST エンドポイントや外部コネクターに、MCP の同等機能があると推測しないでください。

OAuth はホストが管理します。トークンを取り出したり、提示を求めたり、REST リクエストに含めたりしないでください。動作中の MCP 接続に環境変数は必要ありません。限定的なカタログしか利用できない場合は、mcp:tools の同意を得て再接続し、ホストのツールを更新してください。ツールが利用可能だからという理由だけで、送信、公開、削除、有料の作業を開始しないでください。

MCP にない操作には、以下に記載する REST ワークフローを引き続き使用してください。REST の認証情報が不足している場合は、その具体的な制限を説明してください。Recoup 接続全体が壊れていると主張したり、その場しのぎのアカウントを作成したりしないでください。

REST のフォールバック — Bearer ヘッダーを 1 つだけインラインで使用

すべての REST 呼び出しで同じヘッダーを使用し、セットアップ手順を挟まず curl に直接記述します。サンドボックスでは 2 つの変数のうちいずれか 1 つが設定され、API は Bearer を通じて recoup_sk_ キーまたは Privy JWT を受け付けます。

curl -sS -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  "https://api.recoupable.dev/api/artists/{id}/socials"

どちらの変数も設定されていない場合は、該当する接続済み MCP ツールを使用するか、不足している機能について別途 REST のセットアップを依頼してください。認証なしで再試行しないでください。

まずアーティストのモードを選択してください（推測すると架空のアーティストを作り出すことになります）

  • A — 任意のアーティストを調査（名前を指定。ロスターの検索は不要）→ 調査エンドポイント。
  • B — 自分のロスターを閲覧 → ロスターの検出（以下を参照）。
  • C — ロスター内の特定のアーティスト → ロスターを検出し、名前を照合して、アーティストの account_id を取得します（現在のリストの id はそのエイリアスです）。
  • D — アーティストを追加 → recoup-roster-add-artist を使用します。

ロスターの検出： GET /accounts/id → GET /artists（自分のロスターです。org_id は任意です。組織が空の場合もよくあるため、organizations が [] でも処理を止めないでください）。

すべての /artists/{id}/* サブリソースでは、アーティストのアカウント UUID を使用してください。 現在のロスターの行では、この UUID は account_id と id の両方に返されます。内部のプロフィール行キー、Spotify ID、または不透明な調査 ID は使用しないでください。保存済みの古い ID は、現在の認証済みロスターと照合してください。 ソーシャル情報は /artists のレスポンス内に account_socials として埋め込まれています（username、followerCount、profile_url）。/artists/{account_id}/socials を呼び出す前に、そこで確認してください。

停止ルール — ロスターを絶対に捏造しないでください： GET /accounts/id の結果が agent+…@recoupable.com のメールアドレスの場合、それは使い捨てキーです。その旨を伝え、実アカウントのキー（または recoup-platform-connect-account）を求めてください。処理を続けるためにアーティストやロスターを捏造してはいけません。

停止ルール — 指標やデータを絶対に捏造しないでください： 今回の実行で成功した呼び出しから取得した数値のみを報告してください。呼び出しでエラーが発生した場合や結果が空の場合、または指標に対応するコネクターがない場合（GET /connectors/actions → isConnected を確認）、その旨を伝えて省略してください。推定したり、「業界平均」を使ったり、サンプル値やプレースホルダーの数値で不足分を埋めたりしてはいけません。水増しされた架空のレポートより、短くても正確なレポートのほうが適切です。

データが見つからなくても諦める前に、取得するか、接続リンクを返してください。 指標のデータソースが未接続の場合、省略する前に以下を順に実行してください。

  1. 取得できる公開データをスクレイピングする — POST /api/socials/{social_id}/scrape（プロフィール1件）または POST /api/artist/socials/scrape（アーティストの全プロフィール）。TikTok／Instagram／X／YouTube／Threads／Facebook に対応しています。実際の公開数値を報告してください。
  2. 接続状況を確認する — GET /api/connectors → 各コネクターの isConnected を確認します。
  3. 接続リンクを生成する — POST /api/connectors {"connector":"youtube"} は { redirectUrl }（Composio の OAuth URL）を返します。ユーザー自身で接続できるよう、呼び出し元にリンクを提示します。「CPM／収益の確認には YouTube Analytics が必要です。こちらから接続してください：{redirectUrl}」

実際の公開データと接続リンクの両方を返してください。架空のレポートを返す場合や、何も返さず省略する場合より適切です。

ドキュメントマップ（必要なセクションを取得し、パスを推測しないでください）

アカウントと ID · アーティストとコンテンツ · 調査（Songstats ＋ Web） · ソーシャル連携 · チャットとエージェント · 開発者／インフラストラクチャ。正確なパスとパラメーターは、該当領域の llms-full.txt を grep するか、OpenAPI JSON を取得して確認してください。例：

curl -s https://docs.recoupable.dev/llms-full.txt | grep -A 30 -i "similar artists"
curl -s https://docs.recoupable.dev/api-reference/openapi/research.json | jq '.paths | keys'

地域情報は audience から、発見情報は similar と web から取得します。

コネクターのアクション（Google Docs／Sheets／Drive、Gmail、TikTok、Instagram）

Recoup 以外の読み取り／書き込みには、以下を使用します。

  • GET /connectors/actions — カタログ（各アクションの slug、parameters スキーマ、connectorSlug、isConnected）。
  • POST /connectors/actions {actionSlug, parameters} — アクションを1つ実行します。

スラッグは UPPERCASE_SNAKE_CASE 形式です（例：GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN、GMAIL_FETCH_EMAILS）。実行前に、必ずカタログからパラメータースキーマを取得してください。形式はアクションごとに異なります。実行の目安：貼り付けられた docs.google.com／drive.google.com／sheets.google.com の URL、または「このドキュメントを編集」「メールを送信」「TikTok に投稿」などの依頼です。

メールを送信する（Recoup 経由）

POST /api/emails は、Recoup 経由で Agent by Recoup <[email protected]> からメールを送信します。API キーがあればヘッドレスで動作し、Gmail コネクターは不要です。レポート、アラート、スケジュールされたタスクの出力に使用してください。

bash で実行してください（web_fetch ではありません。応答が表示されず、宛先を確認できないためです）。

curl -sS -X POST -H "Authorization: Bearer ${RECOUP_API_KEY:-$RECOUP_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"to":["[email protected]"],"subject":"Weekly report","text":"# Summary\n…"}' \
  "https://api.recoupable.dev/api/emails"
# → {"success":true,"message":"Email sent successfully … to [email protected].","id":"<resend-id>"}

to はメールアドレス文字列の JSON 配列です（["[email protected]"]。文字列単体や [{"email":…}] ではありません）。使用できるキーは to、cc、subject、text、html、chat_id、account_id のみです。不明なキー（例：recipients）は破棄され、to はアカウント自身のメールアドレスにデフォルト設定されます。そのため、メッセージが気づかないうちに誤った宛先へ送信されます。subject は任意です。応答を読み、message に意図した宛先が記載されていることを確認してください。支払い方法が登録されていない場合、to／cc はアカウント自身のメールアドレスに制限されます（403）。ユーザー自身の Gmail から送信するには、代わりに GMAIL_SEND_EMAIL を使用してください。

トラブルシューティング

401 = トークンがない、または期限切れです（認証情報を確認してください）。403 = 組織またはアーティストへのアクセス権がありません。404 = Docs マップを再確認してください（エンドポイントが移動または名称変更されています）。5xx = 1 回再試行し、その後ステータスを表示してください。

使用しない場合

  • サンドボックス内のファイル → ファイルシステムツール。
  • アーティストのワークスペースのオンボーディング／運用 → recoup-roster-* スキル。
  • ドメイン固有のタスク（リサーチ／コンテンツ／リリース／取引／楽曲） → 独自に API を呼び出す該当ドメインのスキル。

コメント

Markdown 対応