DTC MCP

dtc-mcp

用于 Klaviyo + Shopify 分析的代码执行 MCP 服务。

三种工具。类型化 SDK。V8 沙箱可在多次调用间保留状态，因此迭代分析时无需重复获取数据。可在 Claude Desktop、Cursor 或任何 MCP 客户端中使用。

LLM asks → execute_code → V8 sandbox ─→ host bridge ─→ Klaviyo / Shopify
                              ↑                             ↓
                         globalThis state            rate limit + cache
                         persists across calls

npm install -g dtc-mcp

或者获取一键安装的 Claude Desktop 扩展。

---

三种工具

execute_code(code)

在受限的 V8 沙箱中运行 JavaScript（接受 TypeScript 语法——执行前会剥除类型注解）。沙箱提供类型化的 Klaviyo 和 Shopify 客户端；主机在后台处理身份验证、速率限制和缓存。

沙箱内可用的全局对象：

klaviyo	get、post、paginate，以及类型化命名空间：campaigns、flows、lists、segments、profiles、events、metrics 和 reporting.{campaignValues,flowValues}
shopify	gql、ql（ShopifyQL）、timezone
console	log / error / warn / info——会被捕获并作为 stdout 返回
pick(v, schema)	对对象 / 数组进行深层投影
topN(arr, n, by)	按数值键降序取前 N 项
summarize(arr, opts)	自动聚合（计数、总计、最小值 / 最大值 / 平均值，可选 topN）
globalThis.*	在同一 MCP 会话中，赋值会在多次 execute_code 调用间保留

未公开： fetch、process、require、import、setTimeout、文件系统或任何环境变量。离开沙箱的唯一途径是类型化 SDK 方法，它们会经由主机的速率限制器和缓存。

默认值：每次调用最长运行 30s，堆内存为 128 MB（sidecar），每个会话总计 256 MB。在代码开头选择性添加 // @timeout 2m，可将最长运行时间延长至 5 min。

search_docs(query, platform?, limit?)

对捆绑的 SDK 参考文档进行全文 BM25 搜索。返回带有签名和可运行示例的排名 Markdown 片段。按意图查找方法时使用此工具（例如，“如何列出带有其操作的流程？”）。

read_doc(path?, platform?)

按确切路径直接获取片段；不带参数调用时则返回完整列表。LLM 确定所需内容后，使用此工具比 search_docs 更省资源。在会话开始时调用一次 read_doc({})，是一次性了解整个 SDK 接口面的推荐方式。

read_doc({})                                            // list all 332 paths
read_doc({ path: "klaviyo.reporting.campaignValues" })  // one chunk verbatim
read_doc({ platform: "shopify" })                       // Shopify only

---

架构

沙箱会在启动时自动选择以下两种模式之一。

首选：使用 isolated-vm 的 sidecar

┌─ Claude Desktop (Electron, hardened runtime) ────────────────┐
│                                                               │
│  MCP server (Electron's bundled Node)                         │
│   ├ execute_code      proxies to ↓                            │
│   ├ search_docs       MiniSearch BM25 over data/docs.json     │
│   ├ read_doc          direct fetch by chunk ID                │
│   ├ host SDK          Klaviyo + Shopify (rate limit / cache)  │
│   └ sidecar manager   spawn / lifecycle / NDJSON over stdio   │
│                                                               │
└─────────────────────────────│─────────────────────────────────┘
                              │ newline-delimited JSON-RPC
┌─ Sidecar process (system Node, outside Electron) ────────────┐
│                                                               │
│  isolated-vm loads here (no Library Validation restriction)   │
│                                                               │
│  One long-lived V8 isolate per MCP connection:                │
│   • 256 MB heap, 30 min idle TTL                              │
│   • klaviyo/shopify/pick/topN/summarize injected once         │
│   • globalThis state preserved across execute_code calls      │
│   • host-bridge calls round-trip back to the main process     │
│                                                               │
└───────────────────────────────────────────────────────────────┘

为什么使用 sidecar： Claude Desktop 是一款采用 macOS 强化运行时 + 库验证的 Electron 应用。加载到 Claude Desktop 进程中的原生模块必须与 Anthropic 共享 Team ID——而我们无法使用该 ID 签名。将用户的 /usr/local/bin/node 作为子进程启动即可绕过此限制；子进程有自己的强化运行时状态，因此 isolated-vm 可以正常加载。

Node 查找顺序：DTC_MCP_NODE_PATH 环境变量 → which node / where node → Homebrew（Intel + Apple Silicon）→ 标准系统路径 → nvm → Volta → fnm → asdf。需要 Node ≥ 20。

后备方案：进程内 node:vm

如果找不到系统 Node ≥ 20，或 sidecar 启动失败，服务会回退到主进程中的 node:vm 执行器。沙箱接口相同（相同的 globalThis、相同的辅助函数、相同的状态语义），但隔离性较弱——node:vm 只能防止误操作，并非安全边界，且可通过原型链技巧逃逸。这可以接受，因为威胁模型是“用户自己的 LLM 可能会编写有缺陷的代码”，而不是“攻击者试图逃逸”。

每个 execute_code 结果都包含 "sandbox": "sidecar" 或 "sandbox": "vm"，因此你（和 LLM）可以查看运行的是哪种模式。

有状态会话

单个沙盒上下文会在整个 MCP 连接期间持续存在。在一次 execute_code 调用中设置的 globalThis.x = ...，后续每次调用都可见。脚本顶层声明的 const/let 仅在该次调用中有效——需要跨调用保留的内容请使用 globalThis。

在以下情况下会重新创建上下文：连接关闭、空闲 30 min、隔离环境内存不足，或长时间间隔后的首次调用。发生这种情况时，下一个结果会包含 "sessionReset": true，让大模型知道先前的状态已丢失。

输出规范

Klaviyo 和 Shopify 端点会返回冗长的 JSON。主机将任何 execute_code 返回值限制在 100 KB 以内（可通过 DTC_MCP_MAX_RESPONSE_KB 配置）；超出限制的返回值会被替换为 { truncated: true, preview, instructions }。沙盒端提供了 pick / topN / summarize 辅助函数，方便大模型从设计上控制输出不超过上限——示例请参阅 guide.output-discipline 文档片段。

文档交付

search_docs 和 read_doc 会查询从 data/docs.json 构建的内存 MiniSearch 索引。随附版本包含约 330 个片段（手工编写的指南和配方，以及为每个 Klaviyo OpenAPI 端点自动生成的参考文档）。启动时，后台会从 https://cdn.jsdelivr.net/gh/rafaelsztutman/dtc-mcp-docs@latest/docs.json 拉取更新的版本（ETag 缓存于 ~/.cache/dtc-mcp/docs.json），因此新增 API 端点无需发布新的 MCP 版本即可使用。将 DTC_MCP_DOCS_REFRESH=0 设为完全离线使用。

---

安装

选项 A — Claude Desktop 一键安装

1. 从最新的 GitHub 发布版本下载 dtc-mcp.mcpb。
2. 双击该文件。Claude Desktop 会打开安装对话框。
3. 粘贴 Klaviyo API 密钥（必需）和 Shopify 凭据（可选）。
4. 重启 Claude Desktop。锤子菜单中会出现三个工具：execute_code、search_docs、read_doc。

选项 B — 手动配置（claude_desktop_config.json、Cursor 等）

{
  "mcpServers": {
    "dtc-mcp": {
      "command": "npx",
      "args": ["-y", "dtc-mcp"],
      "env": {
        "KLAVIYO_API_KEY": "pk_your_private_key_here",
        "SHOPIFY_STORE": "your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "shpss_your_secret"
      }
    }
  }
}

仅使用 Klaviyo 的模式：省略 SHOPIFY_* 变量。shopify.* 调用会抛出配置错误；klaviyo.* 调用正常工作。

选项 C — npm 全局安装

npm install -g dtc-mcp
dtc-mcp           # runs the MCP server on stdio

---

获取凭据

Klaviyo

1. 登录 Klaviyo。点击 Settings → Account → API Keys（左侧边栏）。
2. 点击 Create Private API Key。将名称设为 dtc-mcp。
3. 授予只读权限范围：campaigns:read、flows:read、lists:read、segments:read、profiles:read、metrics:read、events:read。
4. 复制 pk_... 密钥。

Shopify

有两种身份验证模式。请根据应用类型选择。

Dev Dashboard 应用（推荐；2026 年 1 月之后创建的应用必须使用）：

1. 在 Shopify Partners Dashboard 中打开你的应用。
2. 点击 Configuration → Client credentials。复制 Client ID 和 Client Secret。
3. 所需权限范围：read_orders、read_products、read_customers、read_inventory、read_reports。

环境变量：

SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_CLIENT_ID=your_client_id
SHOPIFY_CLIENT_SECRET=shpss_your_secret

旧版自定义应用（2026 年 1 月之前创建的应用）：

1. Shopify 管理后台 → Settings → Apps and sales channels → Develop apps，打开你的应用。
2. 点击 API credentials → 复制 Admin API 访问令牌（shpat_...）。

环境变量：

SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_your_token_here

请勿同时设置两种身份验证模式；如果两者都已设置，服务会记录一条警告，并使用 Client Credentials。

---

环境

变量	必填	说明
KLAVIYO_API_KEY	是	Klaviyo 私有 API 密钥（pk_...）
SHOPIFY_STORE	适用于 Shopify	*.myshopify.com 域名
SHOPIFY_CLIENT_ID	Dev Dashboard 身份验证	应用客户端 ID
SHOPIFY_CLIENT_SECRET	Dev Dashboard 身份验证	应用客户端密钥（shpss_...）
SHOPIFY_ACCESS_TOKEN	旧版自定义应用	Admin API 令牌（shpat_...）
SHOPIFY_API_VERSION	否	默认值为 2026-01
KLAVIYO_CONVERSION_METRIC_ID	否	覆盖自动发现的“Placed Order”指标 ID
DTC_MCP_SANDBOX	否	auto（默认值）| sidecar（要求使用 isolated-vm）| vm（强制使用 node:vm）
DTC_MCP_NODE_PATH	否	sidecar 使用的 Node 二进制文件绝对路径。跳过自动发现。
DTC_MCP_MAX_RESPONSE_KB	否	限制 execute_code 返回值的字节数（默认值为 100）。
DTC_MCP_DOCS_URL	否	覆盖文档源。默认值：jsDelivr → dtc-mcp-docs@latest。
DTC_MCP_DOCS_REFRESH	否	设为 0 可禁用后台文档刷新（离线模式）。
LOG_LEVEL	否	debug | info | warn | error（默认值为 info）

---

开发

npm install        # installs deps, builds isolated-vm via node-gyp
npm run build      # tsc → dist/
npm run dev        # tsc --watch
npm test           # vitest (63 tests)
npm run inspect    # MCP Inspector — connect any client to dist/index.js

构建 .mcpb 包

tools/build-mcpb.sh           # → dtc-mcp-v<version>.mcpb in repo root

暂存仅用于生产环境的依赖，为原生 .node 二进制文件临时签名（macOS 要求），并打包成可一键安装的 .mcpb。

重新生成打包的文档

npm run codegen:klaviyo   # download Klaviyo OpenAPI, emit chunk JSON
npm run codegen:shopify   # introspect Shopify GraphQL (needs SHOPIFY_* env), emit chunks
npm run codegen:docs      # merge guides + chunks into data/docs.json

在生产环境中，这项任务每天由 dtc-mcp-docs 上的 GitHub Action 运行；MCP 会在下次启动时获取最新版本。

---

基准测试与设计说明

bench/ 中包含与 Klaviyo 官方 MCP 服务的正面对比基准测试（9 项分析任务 × 两个 MCP × 2 次试验，由 Sonnet 子 Agent 评判），以及推动 v1.0.5 演进至 v1.0.6 的内部发现。

如果你正在构建自己的 MCP，值得一读：

• bench/notes/findings.md — 关于大模型如何使用 MCP 的七条经验，均以具体的基准测试单元为依据。包括 v1.0.5 的回归问题，以及 v1.0.6 如何通过面向大模型的描述修复解决该问题。
• bench/notes/description-ablation.md — 针对候选工具描述进行了三轮 Sonnet 子 Agent 探测（约 63 次试验）。结果表明，一个标准的真实 API 示例就能完成约 99% 的教学；除此之外，格式的作用微乎其微；规定性文字则是多余的负担。
• bench/notes/prior-art.md — 代码执行型 MCP 相关先例综述（Anthropic Code-Execution MCP、Cloudflare Code Mode、CodeAct、smolagents、BFCL v3、τ²-bench），以及它们与我们观察结果的对应关系。
• bench/notes/v1.1.0-plan.md — 按意图发现配方，这是下一个可发挥作用的切入点。

基准测试框架本身（bench/runner/）可重复使用。Sonnet 子 Agent 探测模式（bench/runner/probe-descriptions.ts + probe-round3.ts）约需 5 分钟，成本约为 $0，可用于消融测试任何工具描述变更——建议在提交会影响 Agent 行为的变更前运行。

---

许可证

MIT。请参阅 LICENSE。