integrate-anything

セルフインテグレーション

あらゆる外部アプリに接続し、操作を実行します。Membrane CLI を使用します。

必ず Membrane 経由で接続してください。 ベンダーの API を直接呼び出さないでください。Membrane は認証済みの接続を介してすべてのリクエストをプロキシし、認証情報の透過的な更新も含め、適切な認証ヘッダーを挿入します。

外部アプリの認証情報を自分で扱わないでください。 OAuth トークン、API キー、リフレッシュトークンは、Membrane がサーバー側で保存・管理します。connectionKey（または connectionId）を渡すと、ツールがユーザーに代わってベンダーを呼び出します。

ワークフロー

1. Membrane で認証します（マシンごとに一度）。
2. 外部アプリへの接続を確保します。既存の接続を探すか、切断された接続を再接続するか、新しく作成します。
3. 接続を使用して操作を実行するか、アプリの API を呼び出します。

以降では、この 3 つの手順を詳しく説明します。

認証

npx @membranehq/cli login --tenant

--tenant はテナントスコープのトークン（ワークスペース＋顧客）を取得するため、以降の各コマンドで --workspaceKey と --tenantKey を渡す必要がありません。

コマンドを実行するとブラウザーが開きます。ヘッドレス環境では認証 URL が表示されます。ユーザーに URL を開いて認証フローを完了してもらい、コードを貼り付けてもらってから、次のコマンドで完了します。

npx @membranehq/cli login complete <code>

認証情報は ~/.membrane/credentials.json に保存されます。以降のコマンドはすべて、保存された認証情報を自動的に使用します。

npx の使用が難しい場合は、グローバルにインストールして、通常の membrane … コマンドを使用してください。npm i -g @membranehq/cli@latest。機械可読な出力を得るには、任意のコマンドに --json を追加します。

手順 1 — 接続を取得する

1a. 既存の接続を探す

npx @membranehq/cli connection list --json

各接続には id、key、integrationKey、state が含まれます。対象アプリを探し、state に応じて処理します。

• READY → 使用します。手順 2 に進みます。

• CLIENT_ACTION_REQUIRED（切断されており、再認証が必要）→ 新しい接続を作成せず、既存の接続を再接続します。

  npx @membranehq/cli connect --connectionId <id>
  

古い接続が CLIENT_ACTION_REQUIRED の状態で新しい接続を作成すると、孤立したレコードが残り、古い connectionKey を参照していたものが動作しなくなります。必ず再接続してください。

• 複数の候補がある場合（例：slack-work と slack-personal）→ どれを使用するかユーザーに確認します。推測で選ばないでください。
• 候補がない場合 → 新しい接続を作成します（手順 1b）。

1b. 新しい接続を作成する

URL またはドメインを指定する方法が最短です。

npx @membranehq/cli connection ensure "https://slack.com" --json
# also accepts a bare domain: "slack.com"

URL はドメインに正規化され、既知のアプリと照合されます。アプリが見つからない場合は、新しいアプリが作成され、コネクターが自動的に構築されます。

後から検索しやすいように、安定した人間が読めるキーを設定するには（特に slack-work と slack-personal のような複数アカウント構成の場合）、作成後に設定します。

npx @membranehq/cli connection patch <id> --data '{"connectionKey":"slack-work"}'

すでに接続済みのアプリに 2 つ目の接続を作成する場合は、connect を使用します。

npx @membranehq/cli connect --integrationKey slack \
  --connectionKey slack-personal --allowMultipleConnections

1c. 接続を READY に進める

1a の再接続または 1b の作成後、state を読み取り、次の状態遷移に従います。

• READY — 完了です。ステップ 2 に進みます。

• BUILDING — Membrane のビルダーエージェントが作業中です。待機します。

  npx @membranehq/cli connection get <id> --wait --json
  

  --wait はロングポーリングを行います（最大 --timeout 秒。デフォルトは 30 秒です）。

• CLIENT_ACTION_REQUIRED — ユーザーまたはエージェントが操作する必要があります。clientAction オブジェクトに必要な操作が記述されています。

  • clientAction.type — "connect"（認証フロー）または "provide-input"（追加フィールドが必要）。
  • clientAction.agentInstructions（任意）— 存在する場合は、記載された指示にそのまま従ってください。プロバイダー側のフローをプログラムで進める方法が、エージェント向けに示されています。「この URL を貼り付けてください」といった近道をしないでください。エージェントが処理することを前提としているため、この指示が用意されています。
  • clientAction.uiUrl（任意）— ユーザーが手動で操作を完了するための、Membrane がホストするページです。agentInstructions に表示するよう指示されている場合、または agentInstructions がない場合にのみ表示してください。
  • clientAction.description — 人が読める概要です。

  接続にデータを書き戻す必要がある操作（取得した OAuth 資格情報やカスタムパラメーターなど）の場合：

  npx @membranehq/cli connection patch <id> --data '{"connectorParameters":{...},"input":{...}}'
  

  ユーザーが操作を完了したら、state が変わるまで connection get <id> --wait --json でポーリングします。

• CONFIGURATION_ERROR / SETUP_FAILED — error フィールドの内容をユーザーに伝えます。これらは終端状態です。むやみに再試行しないでください。

ステップ 2 — 接続を使用する

実際の応答を最速で得るには、インラインディスパッチを指定して act を実行します。「アクションを作成 → 待機 → 実行」という手順は必要ありません。

act が受け付けるディスパッチ形式は、次の 4 種類のうち 1 つだけです。

ディスパッチ	使用する場面
--api '<json>'	新しい接続を作成した直後の最初の呼び出し、および単発の HTTP リクエスト。 Membrane が認証とベース URL を処理します。
--code '<js>'	小規模なロジック（ループ、変換、複数ステップ）が必要な場合。
--key <key>	この呼び出しを再利用可能なアクションとして保存済みの場合。
--id <id>	--key と同じですが、ID で指定します（アクションにキーがない場合のみ使用）。

2a. インラインの api（新しい接続後の最初の呼び出し、および単発の呼び出しに推奨）

新しい接続に対する最初の呼び出しでは、これをデフォルトとして使用してください。 接続が機能していることを確認し、ユーザーに実際の応答を返す最速の方法です。ビルド手順も、BUILDING 状態も、待機もありません。

HTTP 仕様を渡します。Membrane は接続の認証レイヤーとベース URL を介してリクエストをプロキシします。

npx @membranehq/cli act --connectionKey slack-work \
  --api '{"method":"POST","path":"/api/chat.postMessage","body":{"channel":"#general","text":"Hello"}}' \
  --json

仕様の形式：{ method, path, body?, headers?, query? }。コネクターのベース URL は自動的に先頭に付加されます。認証情報も自動的に挿入されます。

保存済みアクション（ステップ 3）への切り替えは、ユーザーが同じ呼び出しを繰り返し実行する場合に限ってください。保存することで繰り返し利用には大きなメリットがありますが、最初の呼び出しでの有効化には不要な遅延や失敗要因が増えます。

2b. インラインの code（HTTP 呼び出しだけでなくロジックが必要な場合）

npx @membranehq/cli act --connectionKey hubspot \
  --code 'module.exports = async ({ input, membrane }) => {
    const all = []
    let after
    do {
      const page = await membrane.api({ method: "GET", path: "/crm/v3/objects/contacts", query: { limit: 100, after } })
      all.push(...page.results)
      after = page.paging?.next?.after
    } while (after)
    return { count: all.length }
  }' \
  --input '{}' --json

関数には { input, membrane, connection, integration } が渡されます。関数内で認証済みの呼び出しを行うには、membrane.api({ method, path, ... }) を使用します。返された値が、そのままレスポンスの output になります。

2c. キーで再利用可能なアクションを実行（繰り返し利用する場合）

ユーザーが同じ呼び出しを繰り返し実行する場合は、一度保存して key で呼び出します。

npx @membranehq/cli act --key send-channel-message --connectionKey slack-work \
  --input '{"channel":"#general","text":"Hello"}' --json

保存済みアクションの作成方法については、以下のステップ 3を参照してください。

2d. 既存の再利用可能なアクションを検索する

該当するアクションがあるかどうかわからない場合：

# Ranked by semantic match against an intent
npx @membranehq/cli action list --connectionKey slack-work --intent "send a message" --limit 10 --json

# Catalog actions for one app (browse without a connection)
npx @membranehq/cli external-app list --search slack --json   # → externalAppId
npx @membranehq/cli action list --externalAppId <id> --json

各結果には id、key、name、description、inputSchema、outputSchema が含まれます。実行前に inputSchema を確認してください。これが正式な仕様です。

該当するものがなければ、インラインの api または code（上記）を使用するか、保存済みアクションを作成します（ステップ 3）。

ステップ 3 — 再利用可能なアクションを保存する（任意）

同じ act --api 呼び出しを 2 回目に行おうとしていることに気づいたら、保存しましょう。以降は、インラインで指定する代わりに act --key <key> を使って呼び出せます。

方法は 2 つあります。

意図を指定する場合 — 実行したい内容を説明すると、Membrane が設定を作成して検証します。

npx @membranehq/cli action create "send a message in a channel" --connectionKey slack-work --json

アクションは state: BUILDING の状態で返されます。完了するまで待ちます。

npx @membranehq/cli action get <id> --wait --json

仕様を明示する場合 — type と config を直接指定します。テスト済みのインライン api 呼び出しを保存済みアクションにする場合によく使われます。

npx @membranehq/cli action create \
  --key send-channel-message \
  --type api-request-to-external-app \
  --config '{"request":{"method":"POST","path":"/api/chat.postMessage"}}' \
  --integrationKey slack --json

スコープは、設定するフィールドによって決まります。

• connectionKey / connectionId → 接続レベル（1 つの接続に紐づきます）
• integrationKey / integrationId（接続の指定なし）→ インテグレーションレベル（そのインテグレーションのすべての接続で共有されます）

更新／削除：

npx @membranehq/cli action update <id-or-key> --data '<json-merge>'
npx @membranehq/cli action delete <id-or-key>

保存する前にユーザーに確認してください — アクションに名前や説明を付けるか、インラインのままにするかをユーザーが希望する場合があります。

エラーからの復旧

レスポンス本文を読み取ってください。HTTP ステータスだけで分岐してはいけません。エラーへの対応は 3 通りあります。

401 — Membrane の認証情報に問題があります

CLI セッションが無効か、期限切れです。membrane login --tenant を再度実行してください。

外部アプリとの接続が切断されている

ベンダーの認証が無効になっています（トークンの取り消し、OAuth の期限切れ、認証情報の変更など）。接続状態を読み取ります。

npx @membranehq/cli connection get <id-or-key> --json

state が CLIENT_ACTION_REQUIRED の場合、既存の接続を再接続してください（新しい接続は作成しないでください）。

npx @membranehq/cli connect --connectionId <id>

再認証後、元の act 呼び出しを再試行してください。

アクションが失敗した

すべての act レスポンスには、成功時もエラー時も actionRunId が含まれます。完全なログを取得します。

npx @membranehq/cli action-run-log get <actionRunId> --details --json

マッピング済みの入力、出力、エラーに加え、外部アプリとの生の HTTP 通信内容を確認できます。

CLI リファレンス

すべてのコマンドで --json を使用できます。プロジェクトのデフォルト設定を上書きするには、--workspaceKey <key> と --tenantKey <key> を追加します。

connection

npx @membranehq/cli connection ensure <appUrl> [--name <n>] [--json]                       # Find or create by URL
npx @membranehq/cli connection list [--json]
npx @membranehq/cli connection get <id-or-key> [--wait] [--timeout <n>] [--json]
npx @membranehq/cli connection patch <id> --data '<json>' [--json]
npx @membranehq/cli connect --connectionId <id>                                              # Reconnect existing
npx @membranehq/cli connect --integrationKey <k> [--connectionKey <k>] [--allowMultipleConnections]

act

npx @membranehq/cli act --connectionKey <k> --api  '<json>' [--input <json>] [--json]   # Inline HTTP
npx @membranehq/cli act --connectionKey <k> --code '<js>'   [--input <json>] [--json]   # Inline JS
npx @membranehq/cli act --connectionKey <k> --key  <k>      [--input <json>] [--json]   # Reusable
npx @membranehq/cli act --connectionKey <k> --id   <id>     [--input <json>] [--json]   # Reusable by id

action（保存済みアクションの管理）

npx @membranehq/cli action list   [--connectionKey <k>] [--externalAppId <id>] [--intent <t>] [--limit <n>] [--json]
npx @membranehq/cli action create <intent> --connectionKey <k> [--json]                       # Build by intent
npx @membranehq/cli action create --key <k> --type <t> --config '<json>' --integrationKey <k> [--json]   # Explicit spec
npx @membranehq/cli action get    <id-or-key> [--wait] [--timeout <n>] [--json]
npx @membranehq/cli action update <id-or-key> --data '<json>'                                  # Merge
npx @membranehq/cli action delete <id-or-key>

action-run-log

npx @membranehq/cli action-run-log get <actionRunId> [--details] [--json]                      # Diagnostics for any /act call

external-app / search

npx @membranehq/cli external-app list --search <query> --json
npx @membranehq/cli search <query> [--elementType <type>] [--limit <n>] [--json]

フォールバック：Raw API

CLI を利用できない場合は、API を直接呼び出してください。

ベース URL：https://api.getmembrane.com 認証ヘッダー：Authorization: Bearer $MEMBRANE_TOKEN

トークンは Membrane ダッシュボードから取得してください。

CLI コマンド	API の同等処理
connection ensure "<url>" --json	{"appUrl": "<url>"} を指定して POST /connections/ensure
connection list --json	GET /connections
connection get <id> --wait --json	GET /connections/:id?wait=true
connection patch <id> --data <json>	<json> を指定して PATCH /connections/:id
connect --connectionId <id>	POST /connections/:id/reconnect
act --connectionKey <k> --api <json>	{"connectionKey":"<k>","api":<json>} を指定して POST /act
act --connectionKey <k> --code <js>	{"connectionKey":"<k>","code":"<js>"} を指定して POST /act
act --connectionKey <k> --key <ak>	{"connectionKey":"<k>","key":"<ak>","input":<json>} を指定して POST /act
action list --connectionKey <k> --intent <t>	GET /actions?connectionKey=<k>&intent=<t>
action create <intent> --connectionKey <k>	{"intent":"<t>","connectionKey":"<k>"} を指定して POST /actions
action get <id> --wait	GET /actions/:id?wait=true
action-run-log get <actionRunId> --details	GET /action-run-logs/:id?details=true

外部エンドポイント

すべてのリクエストは Membrane API に送信されます。このスキルから他の外部サービスに直接接続することはありません。

エンドポイント	送信されるデータ
https://api.getmembrane.com/*	認証情報、接続パラメーター、アクションの入力、エージェントのプロンプト

セキュリティとプライバシー

• すべてのデータは HTTPS 経由で Membrane API に送信されます。
• CLI の認証情報は、ファイルのアクセス許可を制限したうえでローカルの ~/.membrane/ に保存されます。
• 接続の認証（OAuth、API キー）は Membrane が処理します。外部アプリの認証情報はローカルではなく、Membrane サービスによって保存されます。
• アクションの入力と出力は、Membrane API を経由して接続先の外部アプリに渡されます。

このスキルを使用すると、データが Membrane に送信されます。接続済みアプリへのアクセスを Membrane に許可できる場合にのみインストールしてください。