@synqlet/mcp

Synqlet（ローコード / iPaaS）の REST API をラップする MCP サーバー（TypeScript / Node / stdio）。 AIエージェント（Claude Code 等）が「認証情報を追加して」「◯◯するフローを作って」といった指示で、 Synqlet のフロー・ファンクション・認証情報・環境変数などを作成・テスト・公開できるようにします。

前提

• ローカル（または対象環境）の Synqlet API が稼働していること（ローカル既定: http://localhost:4000）。
• Synqlet の APIキー（形式 sk_synqlet_<id>_<secret>）。画面「設定 > APIキー」から発行できます（作成時に1度だけ表示）。
• Node v24.14.1（.node-version 参照）。

セットアップ（ビルド）

cd mcp
npm install
npm run build      # tsc -p tsconfig.build.json → dist/

その他のスクリプト:

| script | 内容 | | ------------------- | -------------------------------- | | npm run typecheck | 型チェック（src + test） | | npm test | vitest（ノード変換の単体テスト） | | npm run prettier | フォーマットチェック | | npm run format | フォーマット適用 | | npm run start | node dist/index.js（手動起動） | | npm run smoke | エンドツーエンド動作確認（後述） |

環境変数

| 変数 | 必須 | 既定 | 説明 | | ------------------------- | ---- | ----------------------- | --------------------------------------------------- | | SYNQLET_API_KEY | ✅ | — | APIキー（sk_synqlet_<id>_<secret>） | | SYNQLET_API_URL | | http://localhost:4000 | API のベースURL | | SYNQLET_ORGANIZATION_ID | | current-user から自動 | 組織ID。未指定なら起動後 auth/current-user で解決 |

stdout は MCP プロトコル専用です。ログはすべて stderr（console.error）に出力します。

Claude Code への登録

claude mcp add synqlet \
  --env SYNQLET_API_URL=http://localhost:4000 \
  --env SYNQLET_API_KEY=sk_synqlet_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -- node /absolute/path/to/synqlet/mcp/dist/index.js

登録後、まず get_context と get_scripting_guide を呼ぶと、組織・ランナー・認証情報の状況と スクリプトの書き方が分かります。

動作確認（smoke）

MCP SDK の Client + StdioClientTransport でサーバーを spawn し、代表ツールを実際に呼んで エンドツーエンド（ファンクション作成 → test-run が Done、フロー作成 → 公開 → webhook fire → ジョブ完了、 認証情報の暗号化作成）を検証します。

npm run build
SYNQLET_API_KEY=sk_synqlet_... npm run smoke

ツール一覧（41）

コンテキスト

| ツール | 説明 | | --------------------- | ------------------------------------------------------------------------------- | | get_context | 組織・ロール・ランナー（稼働判定）・認証情報タイプ/鍵・環境変数名をまとめて返す | | get_scripting_guide | フロー / ファンクション / 認証情報 / TypeField の書き方ガイド |

フロー

| ツール | 説明 | | ------------------------ | --------------------------------------------------------------- | | list_flows | フロー一覧（nameIncludes / archived で絞り込み） | | get_flow | フロー1件取得（webhook URL 付き） | | create_flow | フロー作成（nodes にトリガー＋スクリプトを渡せば1手で完成） | | update_flow | フロー更新（nodes 指定時は全置換） | | delete_flow | フロー削除 | | publish_flow_revision | リビジョンを作成して公開（アクティブ化） | | list_flow_revisions | リビジョン一覧 | | activate_flow_revision | リビジョンのアクティブ化 / ロールバック | | test_run_flow | フローをテスト実行（test ジョブ）→ 完了まで待って結果を返す | | fire_http_trigger | アクティブなHTTPトリガーを発火 → ジョブ完了まで待って結果を返す | | list_flow_jobs | フロージョブ一覧 | | get_flow_job | フロージョブ1件 + 紐づくランナージョブの result/logs |

ファンクション

| ツール | 説明 | | --------------------------- | ----------------------------------------------------------- | | list_functions | ファンクション一覧（公開済みなら import 文付き） | | get_function | ファンクション1件（コード全文 + import 文付き） | | create_function | ファンクション作成 | | update_function | ファンクション更新 | | delete_function | ファンクション削除 | | test_run_function | playground を deno run → RunnerJob 完了まで待って結果を返す | | test_function_code | testCode を deno test → RunnerJob 完了まで待って結果を返す | | publish_function_revision | リビジョン公開（semver、公開後の import 文付き） | | list_function_revisions | リビジョン一覧 |

認証情報

| ツール | 説明 | | ----------------------- | ------------------------------------------------------------ | | list_credential_types | 認証情報タイプ一覧（apiKey / oauth） | | list_credential_keys | 認証情報の鍵一覧 | | list_credentials | 認証情報一覧（タイプ名 + コピペ用 import 文付き） | | create_credential | 認証情報作成（平文 secret を暗号化、コピペ用 import 文付き） | | delete_credential | 認証情報削除 |

環境変数

| ツール | 説明 | | ----------------------------- | -------------------------------------- | | list_environment_variables | 環境変数一覧（コピペ用 import 文付き） | | create_environment_variable | 環境変数作成（コピペ用 import 文付き） | | update_environment_variable | 環境変数更新（コピペ用 import 文付き） | | delete_environment_variable | 環境変数削除 |

ランナー

| ツール | 説明 | | --------------- | ------------------------------------------ | | list_runners | ランナー一覧（稼働判定つき） | | create_runner | ランナー作成（runnerKey と起動コマンド例） | | delete_runner | ランナー削除 |

ジョブ・通知

| ツール | 説明 | | ---------------------------- | ----------------------------------------------------- | | list_runner_jobs | ランナージョブ一覧（flowJobId / functionId 絞り込み） | | get_runner_job | ランナージョブ1件（logs 切り詰め） | | list_mails | 送信メール履歴 | | list_result_mail_settings | 結果メール通知設定一覧 | | create_result_mail_setting | 結果メール通知設定の作成 | | delete_result_mail_setting | 結果メール通知設定の削除 |

SimplifiedNode（フローノードの簡易表現）

create_flow / update_flow の nodes は SimplifiedNode 配列で渡します。 この型は zod で完全に定義されており、MCP クライアントから見える JSON Schema に各フィールドの名前・型・説明が出ます。 （コピペできる完全な例は get_scripting_guide(topic="flow")。）

各ノードは timeTrigger / httpRequestTrigger / formTrigger / script のうちちょうど1つを持ちます。

{
  "id": "省略時はUUID自動採番",
  "name": "ノード名",
  "memo": "（任意）",
  // 以下のうちちょうど1つ:
  "timeTrigger": { "cron": "0 23 * * *", "timezone": "JST", "active": true },
  "httpRequestTrigger": { "customizeResponse": false }, // secret は自動生成
  "formTrigger": { "typeFields": [], "submitLabel": "送信" },
  "script": {
    "code": "export default async function (p) { return {}; }",
    "permissions": { "net": true }, // net 許可（fetch する場合）
    "maxAttempts": 1,
  },
}

• スクリプトノードの nextNodeId 省略時は「配列内の次の script ノード」へ自動リンクされます。
• トリガーは先頭の script ノードへ自動接続されます。
• 実行起点となるスクリプトノードが先頭に来るよう、出力時にスクリプトノードをトリガーノードより前に並べ替えます。
• permissions は net/read/write/env/sys/run/ffi。true=全許可、string[]=指定許可、省略=全拒否。

HTTPトリガー付きフローを1手で作る

create_flow に nodes を渡すだけで、トリガー＋スクリプトのフローが完成します （update_flow で作り直す必要はありません）。

// create_flow の引数
{
  "name": "Webhookで受け取って処理するフロー",
  "nodes": [
    { "name": "Webトリガー", "httpRequestTrigger": {} },
    {
      "name": "受信処理",
      "script": {
        "code": "export default (p) => ({ ok: true, body: p.request.jsonBody })",
        "permissions": { "net": true },
      },
    },
  ],
}

作成後 publish_flow_revision で公開すると webhook が有効になり、fire_http_trigger で発火できます。

synqlet: import 文の自動生成

スクリプト内で他リソースを参照する synqlet: import 文は、各ツールのレスポンスにコピペ可能な形で含まれます。

| ツール | 返す import | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | create_environment_variable / list_/update_environment_variable | import value from 'synqlet:environment-variables/<id>'; | | create_credential / list_credentials | import credential from 'synqlet:credentials/<id>'; + const token = await credential(); | | publish_function_revision / list_functions / get_function | 公開済みなら import fn from 'synqlet:functions/<id>@~<version>';（未公開なら公開を促す注記） |

認証情報の暗号化について

create_credential は平文の secret を、鍵（RSA-OAEP-256 公開鍵 JWK）でハイブリッド暗号化して送信します。

• 使い捨ての AES-256-GCM 鍵で平文を暗号化（→ encryptedCredential + iv）
• その AES 鍵を RSA-OAEP(SHA-256) で wrapKey（→ encryptedKey）
• すべて base64。method = 'TextPlain'、平文は文字列そのまま（JSON 化しない）

この方式は web/src/features/credential/@hook/encrypt.ts と runner/execute-template/credential.ts の実装に一致しています。 復号にはランナーへ対応する秘密鍵ファイルの配置が必要です。

スキル（skills/）

MCP ツールを使った作業の手順書（Agent Skills / SKILL.md 形式）を skills/ に同梱しています。

• synqlet-flow-builder — フロー/ファンクションの作成・テスト・公開の進め方と落とし穴
• synqlet-credentials — 認証情報のセットアップ（タイプ・鍵・ランナーの関係）

インストール方法・配布の注意は skills/README.md を参照してください。

npm への公開（手動）

公開は手動で行う。files 許可リストにより、tarball には dist/ skills/ README.md のみが含まれる（src/・scripts/・テストは同梱されない）。

cd mcp
npm run build          # prepublishOnly でも自動実行される
npm run publish:dry    # 同梱物を確認（npm publish --dry-run）
npm run publish:npm    # 公開（npm publish）

公開前のチェックリスト:

• npm run publish:dry の Tarball Contents に シークレット（APIキー・.env・秘密鍵）が含まれていないこと
• package.json の version を更新（semver。破壊的変更はメジャー）
• publishConfig.access は public（一般公開）。非公開にする場合は restricted に変更する（npm org の有料プラン Teams が必要）
• npm アカウントで 2要素認証（2FA） を有効にしておく。publish には Granular Access Token（「Bypass two-factor authentication」有効・@synqlet スコープに Read/Write）を ~/.npmrc に設定するか、npm publish --otp=<6桁> を使う
• 利用者には本番でのバージョン固定（npx @synqlet/mcp@<version> 等）を案内する