SMB Sandbox

sandbox-mcp

sandbox-mcp 是一组开源的模拟小型企业 MCP 服务，涵盖 CRM、收件箱、日历、开票和电话，并以一家逼真的虚构公司为背景，让你无需接触真实客户账号即可端到端测试 AI Agent。

将 Claude、Cursor、VS Code 或任何 Model Context Protocol 客户端连接到它，你的 Agent 就能运营一家仿真的企业：等待回复的潜在客户、无人跟进的报价、重复联系人、逾期发票、尚未匹配的支票。每项变更都会像真实系统一样经过验证、记录在审计日志中，并且只在进程内部生效。“发送”电子邮件或 SMS 只会写入发件箱。

快速开始

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

这会通过 stdio 启动 MCP 服务，并生成一家家居服务公司（种子为 42，因此每次生成的公司都相同）。其他行业：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>		在 http://127.0.0.1:<port>/mcp 提供 Streamable HTTP 服务，而非使用 stdio

日志只会写入 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 时可访问，因此答案不会泄露给受测 Agent）。

强制执行的业务规则

• 外键必须存在；金额以整数分为单位；日期格式为 YYYY-MM-DD。
• 交易阶段遵循销售流程（new → qualified → quote-sent → negotiation → won/lost）；won 是最终状态，lost 需要提供原因，且可以重新开启。
• 已作废、草稿或已全额支付的发票不能收款，也不能超额收款。已有付款记录的发票不能作废。
• 未匹配的付款只能匹配同一客户的发票。
• 不能为技术人员安排时间重叠的工作（除非设置 allowOverlap），重新安排时间会更新工作的时间。
• 发送电子邮件和短信需要有效的地址或号码，因此缺少联系信息时会产生真实错误。
• 向潜在客户的联系人发送消息或致电，会在该潜在客户记录中记下首次响应。
• 模拟时钟从数据集“今天”的公司时间 09:00 开始，每次变更前进一分钟，因此时间戳具有确定性。

为 Agent 评分

使用 --state-out 运行你的 Agent，然后根据最终状态而非交互记录评分：

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

run.json 包含：

• dataset：每条记录的最终状态（架构与 @teamshift/fake-business 相同），包括新增的 events。
• audit：按顺序记录每次变更尝试：{ seq, at, tool, input, result: "ok" | "error", error?, changedIds }。
• outbox：Agent“发送”的所有电子邮件和短信。

将 dataset 与原始数据集中的真实 anomalies 进行比较（例如：是否合并了重复联系人、是否处理了未匹配的付款、是否为每笔过期交易设置了 nextAction？），并使用 audit 对错误、破坏性操作或违反政策的行为进行扣分。不要启用 admin 工具集，以免 Agent 重置自己的运行状态。

在代码中直接使用存储

同一引擎也以类型化库的形式导出，参考解决方案和验证器会以这种方式运行：

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 服务。

常见问题

如何安全地测试 MCP Agent？

为它提供一个沙盒，而不是生产环境凭据。sandbox-mcp 提供与真实 CRM、收件箱、日历、开票和电话系统同类的工具，模拟一家虚构公司，不访问网络，也不使用真实账户。运行 Agent，使用 --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 传入自己的数据集。

Agent 能看到答案吗？

默认情况下看不到。只有使用 --expose-answers 时，才会将真实答案 anomalies 作为资源公开；但它们始终会包含在提供给评分人员的 --state-out 文件中。

是否支持 Streamable HTTP？

支持：--http 8787 会在 http://127.0.0.1:8787/mcp 提供无状态 Streamable HTTP 服务。所有请求共用同一个沙盒状态。

许可证

Apache-2.0

---

由 TeamShift 构建 — 面向小型企业运营的 AI 工作人员。