SMB Sandbox

sandbox-mcp

sandbox-mcp は、現実味のある架空の企業を基盤とする、CRM、受信トレイ、カレンダー、請求、電話のモック用小規模ビジネス MCP サーバーを集めたオープンソースプロジェクトです。実際の顧客アカウントに触れることなく、AI エージェントをエンドツーエンドでテストできます。

Claude、Cursor、VS Code、または任意の Model Context Protocol クライアントを接続すると、エージェントが操作できる、もっともらしいビジネス環境が用意されます。返信待ちの見込み客、フォローアップされていない見積もり、重複した連絡先、支払期限を過ぎた請求書、照合されていない小切手などが存在します。変更は実際のシステムと同じように検証され、監査ログに記録され、プロセス内にとどまります。メールや SMS を「送信」しても、送信トレイに書き込まれるだけです。

クイックスタート

npx @teamshift/sandbox-mcp --industry home-services

これにより、生成された住宅サービス企業のデータセット（シード 42。毎回同じ企業になります）を使い、stdio 経由で MCP サーバーが起動します。ほかの業種として、dental-clinic、marketing-agency があります。

npx @teamshift/sandbox-mcp --industry dental-clinic --seed 7 --toolsets crm,inbox --state-out run.json

MCP クライアントを接続する

Claude Code

claude mcp add sandbox -- npx -y @teamshift/sandbox-mcp

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "sandbox": {
      "command": "npx",
      "args": ["-y", "@teamshift/sandbox-mcp", "--industry", "home-services"]
    }
  }
}

Cursor

.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "sandbox": {
      "command": "npx",
      "args": ["-y", "@teamshift/sandbox-mcp", "--industry", "home-services"]
    }
  }
}

VS Code

.vscode/mcp.json に追加します：

{
  "servers": {
    "sandbox": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@teamshift/sandbox-mcp", "--industry", "home-services"]
    }
  }
}

次のようなプロンプトを試してみてください：「受信トレイと通話ログを確認し、緊急性の高いものに返信して、すべての進行中の案件に次のアクションが設定されていることを確認してください。」

CLI オプション

オプション	デフォルト	説明
--industry <id>	home-services	home-services、dental-clinic、または marketing-agency
--seed <n>	42	同じシードなら、バイト単位で同じ企業になります
--size <s>	medium	small、medium、または large
--messiness <x>	1	注入するデータの問題の倍率。0 にするとクリーンなデータになります
--data <file>		生成する代わりに、データセット JSON（例：@teamshift/fake-business のデータセット）を読み込みます
--toolsets <list>	all	crm,inbox,calendar,invoicing,phone,admin のカンマ区切りリスト
--expose-answers	off	正解データの異常を sandbox://anomalies リソースとして公開します
--state-out <file>		終了時および admin_save_state 実行時に、最終データセット、監査ログ、送信トレイを JSON として書き込みます
--http <port>		stdio の代わりに http://127.0.0.1:<port>/mcp で Streamable HTTP を提供します

ログは stderr にのみ出力されるため、stdout はクリーンな MCP チャネルのままです。

ツール

すべてのツールにはシステム名のプレフィックスが付き、zod で検証された入力を受け取り、コンパクトな JSON を返し、MCP ツールのアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint: false）を備えています。失敗はクラッシュではなく、実行可能なメッセージを含むツールエラーとして返されます（例：failed_precondition: Cannot move deal from "new" to "won". Allowed: qualified, quote-sent, lost.）。

ツールセット	ツール
crm	crm_search_contacts、crm_get_contact、crm_create_contact、crm_update_contact、crm_merge_contacts、crm_list_customers、crm_get_customer、crm_list_employees、crm_list_leads、crm_update_lead、crm_list_deals、crm_get_deal、crm_update_deal、crm_list_quotes、crm_send_quote、crm_follow_up_quote、crm_list_tasks、crm_create_task、crm_complete_task
inbox	inbox_list_threads、inbox_get_thread、inbox_send_email、inbox_send_sms、inbox_mark_thread_read
calendar	calendar_list_jobs、calendar_get_job、calendar_schedule_job、calendar_reschedule_job、calendar_cancel_job、calendar_complete_job
invoicing	invoicing_list_invoices、invoicing_get_invoice、invoicing_create_invoice、invoicing_send_reminder、invoicing_void_invoice、invoicing_record_payment、invoicing_list_payments、invoicing_match_payment
phone	phone_list_calls、phone_log_call
admin	admin_get_company_policies、admin_get_company、admin_get_audit_log、admin_reset、admin_save_state、admin_advance_clock

リソース： sandbox://company、sandbox://policies、sandbox://anomalies（--expose-answers を指定した場合のみ。テスト対象のエージェントに答えが漏れることはありません）。

適用されるビジネスルール

• 外部キーは実在する必要があります。金額は整数のセント単位で、日付は YYYY-MM-DD 形式です。
• 案件ステージはパイプラインに従います（new → qualified → quote-sent → negotiation → won/lost）。won は最終ステージです。lost には理由が必要で、再開できます。
• 無効、下書き、または全額支払い済みの請求書への支払い、および過払いはできません。支払いがある請求書は無効化できません。
• 未照合の支払いは、同じ顧客の請求書にのみ照合できます。
• allowOverlap を指定しない限り、ジョブで技術者のスケジュールを重複させることはできません。再スケジュールすると、ジョブの時刻が更新されます。
• メールと SMS には有効なアドレスまたは電話番号が必要です。そのため、連絡先情報がない場合は実際のエラーとして表面化します。
• リードの連絡先にメッセージを送信するか電話をかけると、そのリードに初回応答が記録されます。
• シミュレートされた時計は、データセットの「今日」の会社時刻 09:00 から始まり、変更のたびに 1 分進むため、タイムスタンプは決定的です。

エージェントの採点

--state-out を指定してサンドボックスに対してエージェントを実行し、トランスクリプトではなく最終状態を採点します。

npx @teamshift/sandbox-mcp --industry home-services --seed 42 --toolsets crm,inbox,calendar,invoicing,phone --state-out run.json

run.json には次の内容が含まれます。

• dataset：新しい events を含む、すべてのレコードの最終状態（@teamshift/fake-business と同じスキーマ）。
• audit：試行されたすべての変更を順番に記録したもの：{ seq, at, tool, input, result: "ok" | "error", error?, changedIds }。
• outbox：エージェントが「送信」したすべてのメールと SMS。

dataset を元のデータセットに含まれる正解の anomalies と照合し（たとえば、重複した連絡先が統合されたか、未照合の支払いが適用されたか、古い案件すべてに nextAction が設定されたか）、audit を使ってエラー、破壊的な操作、ポリシー違反を減点します。エージェントが自分の実行をリセットできないよう、admin ツールセットは除外してください。

コードからストアを直接使用する

同じエンジンが型付きライブラリとしてエクスポートされており、リファレンス実装と検証ツールはこの方法で実行します。

import { generate } from "@teamshift/fake-business";
import { SandboxStore } from "@teamshift/sandbox-mcp";

const store = new SandboxStore(generate({ industry: "home-services", seed: 42 }));
for (const quote of store.listQuotes({ notFollowedUp: true, limit: 100 }).items) {
  store.followUpQuote({ quoteId: quote.id, body: "Just checking in on your quote. Any questions?" });
}
console.log(store.audit().length, store.outbox().length);
const finalState = store.snapshot();

createSandboxServer(store, { toolsets, exposeAnswers }) と任意の SDK トランスポートを使って、独自のプロセスに MCP サーバーを組み込むこともできます。

FAQ

MCP エージェントを安全にテストするには？

本番環境の認証情報ではなく、サンドボックスを使います。sandbox-mcp は、架空の企業を対象に、実際の CRM、受信トレイ、カレンダー、請求システム、電話システムと同種のツールを提供します。ネットワークアクセスも実在するアカウントもありません。エージェントを実行し、--state-out で状態を保存して、変更内容を確認します。

実際にメールを送信しますか？

いいえ。プロセスの外に出るものはありません。inbox_send_email、inbox_send_sms、crm_follow_up_quote、invoicing_send_reminder は、送信メッセージをスレッドと送信トレイに追加します。すべてのアドレスには予約済みの .example ドメインを使い、電話番号には 555-01xx を使います。

サンドボックスをリセットするには？

admin_reset ツールを呼び出します（監査ログは保持され、リセットの記録が残るため、採点者が確認できます）。または、サーバーを再起動します。同じ --industry と --seed を指定すると、常に同一の企業が再生成されます。コードでは store.reset() を呼び出します。

データはどこから取得されますか？

現実的な架空の中小企業を生成する決定論的なジェネレーター @teamshift/fake-business から取得します。採点用に、ラベル付きの異常データも含まれています。--data を使って独自のデータセットを渡すこともできます。

エージェントは答えを見られますか？

デフォルトでは見られません。正解データの anomalies は、--expose-answers を指定した場合にのみリソースとして公開されます。採点者向けに、--state-out ファイルには常に含まれます。

Streamable HTTP に対応していますか？

はい。--http 8787 を指定すると、ステートレスな Streamable HTTP が http://127.0.0.1:8787/mcp で提供されます。すべてのリクエストでサンドボックスの状態が共有されます。

ライセンス

Apache-2.0

---

TeamShift が開発 — 中小企業の業務を支援する AI ワーカー。