DTC MCP

dtc-mcp

Klaviyo と Shopify の分析用コード実行 MCP サーバーです。

3 つのツール。型付き 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 拡張機能を入手できます。

---

3 つのツール

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)	自動集計（件数、合計、最小／最大／平均、任意で上位 N 件）
globalThis.*	同じ MCP セッション内の execute_code 呼び出し間で代入内容が保持されます

公開されないもの： fetch、process、require、import、setTimeout、ファイルシステム、環境変数。サンドボックスの外部へアクセスする唯一の経路は型付き SDK メソッドで、ホスト側のレートリミッターとキャッシュを経由します。

デフォルト：呼び出しごとの実時間は 30 秒、ヒープは 128 MB（サイドカー）、セッション全体では 256 MB です。コードの先頭に // @timeout 2m を指定すると、実時間の上限を最大 5 分まで延長できます。

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

---

アーキテクチャ

サンドボックスは、起動時に自動選択される 2 つのモードのいずれかで実行されます。

優先：isolated-vm を使用したサイドカー

┌─ 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     │
│                                                               │
└───────────────────────────────────────────────────────────────┘

サイドカーを使う理由： 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 が見つからない場合、またはサイドカーの起動に失敗した場合、サーバーはメインプロセス内の node:vm ランナーにフォールバックします。サンドボックスの仕様は同一ですが（globalThis、ヘルパー、状態の動作は同じ）、分離の強度は弱くなります。node:vm はミスを防ぐための境界であり、セキュリティ境界ではないため、プロトタイプチェーンを悪用する手法で回避できます。脅威モデルは「攻撃者が脱出を試みる」ではなく、「ユーザー自身の LLM がバグのあるコードを書く」ことなので、許容できます。

すべての execute_code の結果には "sandbox": "sidecar" または "sandbox": "vm" が含まれるため、どちらのモードで実行されたかを確認できます（あなたも LLM も確認できます）。

ステートフルなセッション

1つのサンドボックスコンテキストは、MCP 接続が継続している間保持されます。ある execute_code 呼び出しで設定した globalThis.x = ... は、その後のすべての呼び出しから参照できます。スクリプトの先頭で宣言した const／let は、その呼び出し内でのみ有効です。後続の呼び出しにも保持したい値には globalThis を使用してください。

接続が閉じられたとき、30 分間アイドル状態が続いたとき、Isolate のメモリ不足が発生したとき、または長い間隔を空けた後の最初の呼び出し時に、コンテキストは再作成されます。その場合、次の結果に "sessionReset": true が含まれ、以前の状態が失われたことを LLM に知らせます。

出力の適切な管理

Klaviyo と Shopify のエンドポイントは、冗長な JSON を返します。ホストは execute_code の戻り値を 100 KB（DTC_MCP_MAX_RESPONSE_KB で設定可能）までに制限します。上限を超えた戻り値は { truncated: true, preview, instructions } に置き換えられます。サンドボックス側には pick／topN／summarize ヘルパーが用意されているため、LLM は設計上この上限を超えずに済みます。例については 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 にキャッシュ）。これにより、MCP の新しいリリースがなくても新しい API エンドポイントが追加されます。完全なオフライン利用には DTC_MCP_DOCS_REFRESH=0 を設定してください。

---

インストール

オプション A — Claude Desktop のワンクリックインストール

1. 最新の GitHub リリースから dtc-mcp.mcpb をダウンロードします。
2. ファイルをダブルクリックします。Claude Desktop にインストールダイアログが表示されます。
3. Klaviyo API キー（必須）と Shopify の認証情報（任意）を貼り付けます。
4. Claude Desktop を再起動します。ハンマーメニューに 3 つのツール（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

認証方式は 2 種類あります。アプリの種類に合った方式を使用してください。

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 Admin → 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	いいえ	サイドカーで使用する 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 のサブエージェントが評価）と、v1.0.5 から v1.0.6 への進化につながった内部調査結果が含まれています。

独自の MCP を構築する場合は、ぜひご覧ください。

• bench/notes/findings.md — LLM が MCP をどのように使用するかについて、具体的なベンチマーク結果に基づく 7 つの知見をまとめています。v1.0.5 でのリグレッションと、v1.0.6 での LLM に適した説明文への修正による回復についても記載しています。
• bench/notes/description-ablation.md — ツールの説明文候補について、Sonnet のサブエージェントによる 3 ラウンドの調査（約 63 回の試行）をまとめています。実際の API を使用した標準的な例を 1 つ示すだけで、学習効果の約 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 のサブエージェントを使った調査パターン（bench/runner/probe-descriptions.ts + probe-round3.ts）なら、ツールの説明文の変更による影響を約 5 分、約 0 ドルで評価できます。エージェントの動作に影響する変更を確定する前に実行することをおすすめします。

---

ライセンス

MIT。LICENSE を参照してください。