sapiom

@sapiom/mcp

Sapiom 用のローカル開発者向け MCP サーバーです。お使いのマシン上で、サーバー名 sapiom-dev として stdio 経由で動作します。現在は、コーディングエージェントに Sapiom エージェントのひな形作成、テスト、デプロイ、調査を行うツールと、Web アプリを稼働中のサンドボックス URL または永続的な App Link の背後に配置するツールを提供します。この名前空間は、今後ほかの開発者向けツールを追加できるようになっています。

機能の提供面ではありません。 これはリモートの「Sapiom」MCP（sapiom_sandbox_*、スクレイピング、検索などの機能ツールを備えたホスト型コネクター）ではありません。 sapiom-dev は直接利用できる機能ツールを公開しません。ローカルのチェックと Local Run の経路では、Sapiom の機能利用料が発生しないスタブ機能を使用します。一方、デプロイ、クラウドビルド、本番実行、シグナル、スケジュールは Sapiom のクラウド状態を操作し、利用料が発生する場合があります。どちらを使うべきかは、2 つの Sapiom MCP サーバーをご覧ください。

インストール

グローバルにはインストールせず、npx で必要に応じて実行します。

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

Claude Code では：

claude mcp add sapiom -- npx -y @sapiom/mcp

設定

デフォルトでは、サーバーは production 環境を対象にします。SAPIOM_ENVIRONMENT 環境変数で変更できます。

{
  "mcpServers": {
    "sapiom-dev": {
      "command": "npx",
      "args": ["-y", "@sapiom/mcp"],
      "env": { "SAPIOM_ENVIRONMENT": "staging" },
    },
  },
}

• production（別名 prod）→ app.sapiom.ai / api.sapiom.ai — デフォルトです。
• staging（別名 dev）→ app.sapiom.dev / api.sapiom.dev。

どちらも組み込みのプリセットから解決されるため、設定ファイルは不要です。カスタムターゲットは ~/.sapiom/credentials.json で定義できます（不明な環境名が指定されると、サーバーは想定される形式を表示します）。

API キーは https:// 経由、またはループバックホスト（localhost、*.localhost、127.0.0.1、[::1]）への通常の http:// 経由でのみ送信されます。それ以外の http:// ホストを指定したカスタムターゲットは、リクエスト送信前に拒否されます。信頼できるプライベートネットワークでは、サーバーの env に SAPIOM_ALLOW_INSECURE_HTTP=1 を設定してください。

認証

ネットワークを使う最初の呼び出し（link、deploy、run、inspect、signal）には Sapiom API キーが必要です。sapiom_authenticate を実行すると、サーバーがブラウザーのログインフローを開き、取得したキーを環境ごとに ~/.sapiom/credentials.json にキャッシュします。その後は再認証せずにツールを使用できます。sapiom_status は認証済みのユーザーを報告し、sapiom_logout はキャッシュされた認証情報を消去します。

ローカルでの作成ツール（scaffold、check、run_local）には Sapiom の認証は不要です。scaffold は最新の依存関係バージョンを確認するために npm に問い合わせる場合があります。check は定義をインポートし、run_local は作成者が記述した通常のローカルコードを実行します。スタブに置き換えられるのは ctx.sapiom.* の呼び出しだけです。作成者のコード内で直接行われるネットワーク、ファイルシステム、環境、プロセスへの作用は、実際に実行されます。

ツール

ツール	ネットワーク	機能
sapiom_authenticate	ブラウザー	ログインし、現在の環境用の API キーをキャッシュします
sapiom_status	—	認証状態を報告します
sapiom_logout	—	キャッシュされた認証情報を消去します
sapiom_send_feedback	✓	ユーザーからの製品フィードバックを Sapiom チームに伝えます
sapiom_dev_agents_scaffold	npm は任意	新しいエージェントプロジェクトを作成します。現在の依存関係のバージョンを npm に問い合わせる場合があります
sapiom_dev_agents_check	作成者のコードのみ	型チェック、インポート、バンドルを行い、定義とステップグラフを検証します
sapiom_dev_agents_run_local	作成者のコードのみ	ctx.sapiom.* の呼び出しをスタブ化してローカルで実行します（Sapiom の機能利用コストは発生しません）
sapiom_dev_agents_link	✓	ホストされたオーケストレーションを特定または作成し、その ID をキャッシュします
sapiom_dev_agents_clone	✓	ギャラリーのテンプレートをフォーク（またはフォークを再クローン）して、ローカルプロジェクトに取り込みます
sapiom_dev_agents_deploy	✓	現在のローカルソースをバンドルしてクラウドでビルドし、完了を待ちます
sapiom_dev_agents_run	✓	実際のクラウド実行を開始します
sapiom_dev_agents_inspect	✓	実行またはビルドを調査します（完了を待つこともできます）
sapiom_dev_agents_signal	✓	シグナルを送信して、一時停止中の実行を再開します
sapiom_dev_agents_emit_event	✓	カスタムイベントを発行します。このタイプのアクティブな event トリガーごとに実行を開始します（0..N）
sapiom_dev_agents_schedule	✓	トリガーを作成します：cron、単発、イベント（eventType）、または Webhook（URL + シークレット）
sapiom_dev_agents_schedule_inspect	✓	1 つのトリガー（発火履歴付き）を調査するか、エージェントのトリガーを一覧表示します
sapiom_dev_agents_schedule_cancel	✓	すべての種類のトリガーをキャンセルします（以降の発火をすべて停止します）
sapiom_dev_agents_schedule_secret	✓	Webhook トリガーの署名シークレットをローテーション、ローテーション完了、または取り消します
sapiom_dev_agents_cron_preview	✓	cron 式を検証し、次回以降の実行予定をプレビューします
sapiom_dev_sandbox_configure	—	検証済みの type: "sandbox" プレビューリソースを sapiom.json に書き込みます
sapiom_dev_sandbox_check	—	デプロイせずに、プロジェクトのサンドボックスリソースを検証します
sapiom_dev_sandbox_preview	✓	ttl の期限が切れるライブ URL 用に、アプリをサンドボックスにデプロイします
sapiom_dev_app_publish	✓	同じアプリを永続的な App Link（apps.sapiom.ai/{org}/{slug}）に公開します
sapiom_dev_app_list	✓	組織の App Link を一覧表示します：URL、公開範囲、Webhook、利用上限、ウェイク状態
sapiom_dev_app_settings	✓	リンクの webhooksEnabled、公開範囲、利用上限、ウェイクレート制限を変更します
sapiom_dev_app_delete	✓	リンクを削除します（URL は解決されなくなり、スラッグは解放されます）。confirm: true が必要です
sapiom_dev_map	任意	エージェントマップ：システム、エージェント、ステップ、およびコードで裏付けられたそれらの間のエッジ
一般的なループは、scaffold → ステップのコードを作成 → 緑色になるまで run_local → link
→ deploy → run → inspect です。

エージェントではなくウェブアプリの場合は、反復しながら sandbox_configure → sandbox_preview （サンドボックスとともに無効になる使い捨て URL）を実行し、リンクを恒久的なものにするか共有する段階で app_publish を実行します。app_publish は同じ sapiom.json サンドボックスリソースを読み込み、ソースを保存済みのテキストのみのバンドル （≤ 10 MiB）としてアップロードし、要求に応じてアプリを起動する永続的な https://apps.sapiom.ai/{org}/{slug} URL を返します。同じスラッグを再公開すると、その場で更新されます。ルーティングのルールについては sapiom-sandbox-preview スキルを参照してください。

リンクが作成されたら、app_list、app_settings、app_delete を使って、ターミナルを離れずに管理できます。Webhook はデフォルトで無効です。app_settings { slug, webhooksEnabled: true } を実行すると有効になり、その後、サードパーティは https://apps.sapiom.ai/{org}/{slug}/hook/<path> に POST できます（/hook プレフィックスは 取り除かれ、本文はバイト単位で正確に転送されるため、Slack／Stripe／GitHub の署名 チェックをアプリ内で実行できます）。これらの設定には org.write 権限が必要です。 公開権限だけでは不十分で、拒否された場合は権限とフィールド名を示すメッセージが返されます。エージェントは再試行せず、そのメッセージを伝えてください。

エージェントマップ

sapiom_dev_map は、Agent Studio が描画するマップを返します。呼び出しごとにコードから計算され、エージェントやエッジに関する情報は保存されません。プロジェクトフォルダー（root。デフォルトは作業ディレクトリ）を渡し、必要に応じて git の ref（HEAD、ブランチ、コミット）を指定すると、そのバージョンのマップが描画されます。

{ "root": "~/agents/support-desk", "ref": "HEAD" }

スキャンでは、sapiom.json または defineAgent があるすべてのフォルダーを検出し、以下を読み取ります。

• エッジ：エージェント間の接続です。接続を裏付けるファイルと行番号がそれぞれ記録されます。対象は、agents.run / agents.launch（launch）、別のエージェントに対する schedules.create（timer）、および events.emit と、そのイベントタイプによってトリガーされるエージェントとの対応（event）です。コードから宛先を特定できる場合、その宛先が対象になります。特定できるのは、リテラル、定数（ローカルまたはインポートされたもの）、実行時にインデックス参照される定数マップのすべての値、呼び出しが読み取る入力フィールドに設定された zod の .default()、または sapiom.json で設定された process.env キーです。それ以外は unresolved に記載されます。
• システム：これらのエッジからなる連結成分です。Vault キー、データベース、コネクターを共有するだけのエージェントは、同じシステムにはなりません。共有リソースは、各エージェントの shared リストに表示されます。コミット済みの .sapiom/map.json でシステム名を指定します：{ "systems": [{ "agent": "intake", "name": "Support desk" }] }。
• agents check によるステップ（エージェントの依存関係がインストールされている必要があります）。
• サインイン中のアカウントから取得するトリガーとデプロイ状態に加えて、fleet.json で宣言されたトリガーも含まれます。サインアウト中の場合はその旨が platform に示されますが、マップは引き続き描画されます。
• changedSinceRef：エージェントのフォルダーが ref と異なることを示します（作業コピーのマップを描画する場合は HEAD が基準です）。

スキャンせずに、自分で記述したエージェントをマップにするには、agents を渡します。

{
  "agents": [
    { "slug": "intake", "emits": [{ "eventType": "ticket.opened" }] },
    {
      "slug": "triage",
      "triggers": [{ "kind": "event", "eventType": "ticket.opened" }],
      "calls": [{ "to": "notify", "kind": "launch" }]
    },
    { "slug": "notify", "resources": ["connector:slack"] }
  ]
}

各エージェントには slug と、任意で path、description、deployed、steps（{ entry, steps: [{ id }], transitions: [{ from, to, kind }] }）、calls（{ to, kind: "launch" | "signal" | "timer", evidence? }）、emits、triggers、resources を指定します。同じシステムのルールが適用されます。

ラベル。 サインイン中の場合、このツールは Jev（jev-1.13.0。一括の decisions.evaluate 呼び出しを1回実行）に問い合わせ、記述した各エージェントの role（intake、worker、orchestrator、reporter、monitor、utility のいずれか）と、各 launch エッジまたは event エッジの label（作業を引き継ぐ、データを渡す、または監視する）を取得します。ラベルが表示されるのは、その確率 p が0.8以上の場合のみです。回答は、質問の事実のハッシュをキーとして <root>/.sapiom/cache/map-labels.json にキャッシュされます（フォルダー内からは Git の対象外。記述したマップの場合はメモリ内にキャッシュ）。そのため、変更のないエージェントについて再度問い合わせることはなく、ラベルが変わることもありません。スキャン対象のプロジェクトでは、エージェントが変更された場合も、新しい回答が異なり、かつ確率が0.8以上にならない限り、表示されていたラベルが維持されます。 サインアウト中、platform: false の場合、または Jev が失敗するか処理に5秒を超える場合、マップは labels: "unavailable" を含めて返されます。それ以外の内容は変わりません。

機能の位置づけ

ここで作成したエージェントは、@sapiom/tools（ctx.sapiom.*）を通じて Sapiom の機能（サンドボックス、リポジトリ、コーディングエージェント、検索、ストレージ、コンテンツ生成）を呼び出します。run_local ではスタブを使ってこれらの呼び出しを解決しますが、デプロイ時と本番環境での実行では、認証済みのクラウド処理が行われ、使用量が計測される場合があります。この MCP に機能ごとのツールが追加されることはありません。機能は @sapiom/tools とリモートの sapiom MCP にあります。ポリシーの全容については位置づけに関するドキュメントを参照してください。

フィードバックの送信

sapiom_send_feedback は、ユーザーからの製品フィードバック（バグ、使いにくい点、機能リクエスト）を Sapiom チームに伝えます。エージェントが送信するのはユーザーが述べた内容のみです。サーバーがパッケージのバージョン、プラットフォーム、アーキテクチャ、Node のバージョン、環境、タイムスタンプを付加するため、モデルがそれらをマシンから読み取る必要はありません。

このサーバーを組み込むホストは、SAPIOM_HARNESS_VERSION を使って独自のバージョンを通知できます。この値は clientMeta.harnessVersion として送信され、トリアージ時に「このユーザーが使っているビルドはどれか」を確認できるようになります。変数が設定されていない場合、このフィールドは省略され、プレースホルダーが設定されることもありません。@sapiom/harness はこの値を自動的に設定します。

使用状況の分析

このサーバーは、匿名の使用状況分析データ（ツール呼び出しごとに 1 件の tool.call イベント：ツール名、引数、所要時間、成功／エラーの分類）を、デフォルトで @sapiom/analytics-core 経由でホスト型の Sapiom コレクターに送信します。SAPIOM_TELEMETRY_DISABLED=1 または DO_NOT_TRACK=1 を設定すれば、いつでもオプトアウトできます。どちらを設定しても送信機能は完全に無効になり、何も送信されず、ディスクへの書き込みも行われません。SAPIOM_ANALYTICS_ENDPOINT で送信先を上書きできます。テレメトリーはメモリー内で同期的にキューに追加されます。例外を発生させたり、ツール呼び出しをブロックしたりすることはなく、ツールの結果に影響することもありません。

ライセンス

MIT