scenariosim-mcp

ScenarioSim MCP

LLM エージェントに信頼性の高い what-if／シナリオシミュレーションエンジンを提供する、透明性の高い 100％決定論的な Model Context Protocol (MCP) サーバーです。

エージェントは計画を説明するのは得意ですが、その結果を 予測 するのは苦手です。複数期間にわたる計算でずれが生じ、複利を適切に扱えず、計算過程を示せません。ScenarioSim は、シミュレーションを厳密で説明可能なエンジンに委ねます。前提条件（成長率、解約率、価格設定、コスト、開始時の指標、期間）を指定すると、期間ごとの予測結果、主要指標、実際に使用した前提条件に加え、感度分析と損益分岐点の計算を返します。それぞれに平易な説明が付属します。

すべての数値は decimal.js による40桁の精度で処理されます（浮動小数点数は使用しません）。そのため、同一の入力からは常にバイト単位で同一の出力が得られます。このサーバーはステートレスで、データベースもセッションもなく、結果に時計や乱数は使用しません。

これは、PrecisionCalc MCP（決定論的な高精度の財務・ビジネス計算）および DecisionMatrix MCP（透明性の高い多基準意思決定分析）と同じエンジニアリング標準に基づいて構築された製品群の3番目の製品です。プロジェクト構成、出力方針、Cloudflare Pages へのデプロイ方式は同一です。

🌐 ホスティング済みのライブサーバー（無料、インストール不要）

Cloudflare のエッジでパブリックなリモート MCP サーバーが稼働しています。Streamable-HTTP MCP クライアントから接続できます。

https://scenariosim-mcp.pages.dev/mcp

{ "mcpServers": { "scenariosim": {
    "type": "http", "url": "https://scenariosim-mcp.pages.dev/mcp" } } }

無料プランではオープンモードで稼働します（キー不要、1 IP あたり1日20回）。有料プラン（Starter 月額$12・1日5,000回、Pro 月額$39・1日50,000回）は Stripe Checkout から利用できます。プランを購入すると API キーがすぐに発行され、X-API-Key として送信できます。キー不要で無制限に利用するには、セルフホストしてください。ランディングページと料金プラン：https://scenariosim-mcp.pages.dev。

---

機能

6つのツールが、すべて統一されたエージェント向け解析可能な形式で応答します。

ツール	用途
run_scenario	メインツール。 あらかじめ用意されたテンプレート、または自由形式のモデルを期間に沿って予測します。→ 期間ごとの projections、概要となる key_results、assumptions_used、methodology、notes、平易な説明の explanation を返します。
sensitivity_analysis	1つ以上の入力を1つずつ変化させ、対象指標への影響を報告します。弾力性の推定値、出力範囲、影響の大きい入力のランキングも含まれます。
break_even	対象指標を目標値にするために必要な入力値を計算します（決定論的な二分法）。
compare_scenarios	2～3個のシナリオを並べて実行し、ベースラインとの差分と、任意で最良のシナリオを返します。
list_templates	テンプレートを一覧表示します。各テンプレートの入力（デフォルト値と単位）および利用可能な出力を確認できます。
health_check	バージョン、ステータス、機能。

シナリオテンプレート

id	models	primary output
saas_growth	獲得（独自の成長率を含む）と解約に基づく購読者数 + MRR/ARR	ending_mrr
pricing_change	価格弾力性による価格変更の売上／利益への影響	cumulative_profit_after
churn_impact	解約がない場合のベースラインと比較した、継続率の低下 + 売上損失	cumulative_revenue_lost
cost_reduction	コスト削減による利益 + 利益率への影響	cumulative_savings
hiring_plan	従業員数、諸経費込みの人件費、売上能力	cumulative_payroll
cash_runway	将来の現金残高 + 残り資金で事業を継続できる期間（月数）	runway_periods
unit_economics	LTV、LTV:CAC、CAC回収期間、顧客あたりの利益率曲線	ltv_cac_ratio
marketing_funnel	訪問者 → リード → 顧客 → 売上	total_revenue
compound_growth	単一指標の一般的な複利／線形予測	ending_value
custom	自由形式：独立して成長する任意の数の指標	(最初の指標)

すべてのテンプレートは horizon（期間数、1～1200）と period_label （day／week／month／quarter／year。年率換算にも使用）を受け取ります。指定のない入力には ドキュメントに記載されたデフォルト値が使用されます。不明な入力は無視され、notes で報告されます。 入力／出力の全カタログを確認するには、list_templates を呼び出してください。

一貫したレスポンス形式

成功したレスポンスには、status、scenario、period_label、horizon、 key_results（単位と完全精度の value_exact を含む key_results_detail も）、 projections、assumptions_used、methodology、notes、自然言語による explanation が含まれます。

{
  "status": "success",
  "scenario": "saas_growth",
  "period_label": "month",
  "horizon": 12,
  "key_results": {
    "ending_customers": 449.7, "ending_mrr": 26982.1, "ending_arr": 323785.2,
    "total_churned_customers": 82.4, "cumulative_revenue": 232104.6
  },
  "projections": [
    { "period": 0, "customers": 200, "mrr": 12000, "new_customers": 0, "churned_customers": 0 },
    { "period": 1, "customers": 234, "mrr": 14040, "new_customers": 40, "churned_customers": 6 }
  ],
  "assumptions_used": {
    "template": "saas_growth", "starting_customers": "200", "new_customers_per_period": "40",
    "acquisition_growth_rate": "0", "churn_rate": "0.03", "arpu": "60",
    "horizon": 12, "period_label": "month"
  },
  "methodology": {
    "model": "SaaS Growth",
    "primary_output": "ending_mrr",
    "precision": "decimal.js (40 significant digits)",
    "deterministic": true,
    "period_convention": "Period 0 is the starting state; periods 1..12 are projected. 12 month(s) per year."
  },
  "notes": ["Churn is applied to the prior period's base before new customers are added."],
  "explanation": "Starting from 200 customers and adding 40 per month (churn 3%), after 12 months you reach ..."
}

エラーがツール境界を例外として越えることはありません。代わりに、構造化された実行可能な形式で返されます。

{
  "status": "error",
  "error": {
    "type": "unknown_template",
    "message": "Unknown scenario template 'saaas'.",
    "hint": "Available templates: saas_growth, pricing_change, churn_impact, cost_reduction, hiring_plan, cash_runway, unit_economics, marketing_funnel, compound_growth. Call list_templates for details ..."
  }
}

設計メモ — 正確な数値： key_results の主要数値は、扱いやすいように決定論的に丸められます（小数点以下6桁）。key_results_detail[].value_exact と assumptions_used には、JSON で精度が失われないよう、完全精度の文字列が格納されます。 内部の計算はすべて、40桁精度の十進数で行われます。

---

プロジェクト構成

scenariosim-mcp/
├── worker-src/
│   ├── index.mjs        # Cloudflare Pages Function (_worker.js): MCP over Streamable HTTP + billing routes
│   ├── engine.mjs       # The deterministic simulation engine: 9 templates + 6 tools + solver + validation
│   └── billing.mjs      # Stripe Checkout + KV-backed API keys, quota metering, webhook
├── server.mjs           # Local stdio MCP server (same engine, no network/state)
├── site/
│   ├── index.html       # Static landing / pricing / docs page
│   ├── mcp.json         # Machine-readable connection manifest
│   ├── llms.txt         # LLM-friendly summary
│   └── _worker.js       # Built bundle (esbuild output; git-ignored)
├── tests/
│   └── engine.test.mjs  # 29 core simulation-logic tests (node --test)
├── examples/
│   └── agent_example.mjs # End-to-end MCP client demo over HTTP
├── package.json         # build / deploy / dev / test scripts
├── wrangler.toml        # Cloudflare Pages config
├── .env.example         # Optional auth/rate-limit env reference
├── LICENSE              # MIT
└── README.md

関心の分離： engine.mjs は純粋で、トランスポートに依存しません（テストや Node／Deno／エッジランタイムから直接インポートできます）。index.mjs は MCP の JSON-RPC 接続、HTTP、CORS、認証／使用量計測との接続部分のみを処理します。server.mjs は同じエンジンを stdio 経由で 再利用します。

---

要件

• Node 18+（ビルド、テスト、ローカル開発に必要）。開発時／実行時の依存関係は2つだけです： decimal.js（計算）と esbuild（バンドラー）。
• ホスト版のデプロイには Cloudflare アカウントが必要です（無料プランで問題ありません）。

---

ローカルで実行

git clone <your-fork> scenariosim-mcp && cd scenariosim-mcp
npm install

# Run the test suite (no server needed)
npm test

# Serve the MCP endpoint locally via Wrangler (builds + runs Pages dev)
npm run dev          # -> http://127.0.0.1:8788/mcp

# Try the end-to-end client demo (hosted by default, or pass a local URL)
node examples/agent_example.mjs
node examples/agent_example.mjs http://127.0.0.1:8788

# Or run the dependency-light stdio server directly
node server.mjs

簡単な手動呼び出し：

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"list_templates","arguments":{}}}'

---

npm でインストール（stdio、ホスティング不要）

コマンドを1つ実行するだけで、サーバーをローカルの stdio 経由で起動できます。デプロイは不要です：

npx -y scenariosim-mcp

Claude Desktop／任意の stdio MCP クライアント（claude_desktop_config.json）：

{ "mcpServers": { "scenariosim": { "command": "npx", "args": ["-y", "scenariosim-mcp"] } } }

これは、ホスト版サーバーと同じ決定論的なエンジンを、お使いのマシンで実行します。

クライアントの設定

Cursor — ~/.cursor/mcp.json

{ "mcpServers": { "scenariosim": {
    "url": "https://scenariosim-mcp.pages.dev/mcp" } } }

Claude Desktop — claude_desktop_config.json

Claude Desktop は stdio サーバーを起動するため、mcp-remote を使って HTTP エンドポイントに接続します：

{ "mcpServers": { "scenariosim": {
    "command": "npx", "args": ["-y", "mcp-remote", "https://scenariosim-mcp.pages.dev/mcp"] } } }

VS Code — .vscode/mcp.json

{ "servers": { "scenariosim": {
    "type": "http", "url": "https://scenariosim-mcp.pages.dev/mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json

{ "mcpServers": { "scenariosim": {
    "serverUrl": "https://scenariosim-mcp.pages.dev/mcp" } } }

Streamable HTTP 対応の MCP クライアント

https://scenariosim-mcp.pages.dev/mcp（またはセルフホスト URL）を指定してください。認証を有効にする場合は、クライアントの headers に X-API-Key（または Authorization: Bearer <key>）を追加してください。

---

ツールとパラメーター

run_scenario(template?, inputs?, metrics?, horizon?, period_label?)

• template — 上記のテンプレート ID のいずれかです（saas、pricing、runway、 ltv、funnel などのエイリアスも解決されます）。省略するか、"custom" を渡すと、自由形式のモデルを実行します。
• inputs — テンプレートの前提条件を指定するオブジェクトです。例： { "churn_rate": 0.03, "arpu": 60 }。assumptions として指定するか、トップレベルに展開して指定することもできます。 指定されていないキーには、ドキュメントに記載されたデフォルト値が使われます。
• metrics — (カスタムモード) { name, start, growth_rate?, mode? } の配列です。 mode は "compound"（デフォルト、x·(1+r)ⁿ）または "linear"（x·(1+r·n)）です。
• horizon — 予測する期間数（1～1200）です。デフォルト値はテンプレートごとに異なります（通常は 12）。
• period_label — day／week／month／quarter／year（デフォルトは month）です。

sensitivity_analysis(template, variable|variables, target_metric?, variation?, steps?, values?, min?, max?, inputs?, horizon?)

リストされた各入力値を範囲内で変化させ（デフォルトではベースラインを中心に ±variation=0.2、steps=5）、他の入力値はすべてベースラインに固定したまま、各点で target_metric（デフォルトはテンプレートの主要出力）を再計算します。変数ごとの sweep 行、elasticity_estimate、output_range、most_influential のランキングを返します。variation の代わりに、明示的な values: [...] または min／max のグリッドを指定することもできます。

break_even(template, solve_for, target_metric?, target_value, bounds?, inputs?, horizon?)

決定論的な二分法と自動的なブラケットの拡張によって、target_metric が target_value になる solve_for（入力名）の値を求めます。required_input、change_from_baseline、achieved_metric、residual を返します。探索範囲内で、解を求める入力に対して指標が単調であることを前提とします。ターゲットをブラケットできない場合は、達成可能な範囲を示す明確な no_solution エラーを返します。探索範囲を制限（または固定）するには、明示的に bounds: [lo, hi] を渡します。

compare_scenarios(scenarios, compare_metric?, goal?, horizon?, include_projections?)

2～3 個の scenarios（{ name?, template, inputs }、またはカスタムの場合は { name?, metrics }）を実行し、key_results を揃えて、それぞれを最初のシナリオ（ベースライン）との差分として示します。ランキングを作成して winner を選ぶには、compare_metric と goal（デフォルトは max、または min）を渡します。共通の horizon はトップレベル、またはシナリオごとに設定できます。

list_templates() / health_check()

テンプレートの検出とステータス確認です。パラメーターはありません。

---

ツール呼び出しペイロードの例

SaaS の成長を 12 か月間予測します：

{ "name": "run_scenario", "arguments": {
  "template": "saas_growth",
  "inputs": { "starting_customers": 200, "new_customers_per_period": 40,
              "acquisition_growth_rate": 0.05, "churn_rate": 0.03, "arpu": 60 },
  "horizon": 12, "period_label": "month"
} }

期末 MRR を最も大きく動かす要因は何ですか？

{ "name": "sensitivity_analysis", "arguments": {
  "template": "saas_growth",
  "inputs": { "starting_customers": 200, "new_customers_per_period": 40, "churn_rate": 0.03, "arpu": 60 },
  "variables": [ { "name": "churn_rate", "variation": 0.5 },
                 { "name": "arpu", "variation": 0.3 },
                 { "name": "new_customers_per_period", "variation": 0.5 } ],
  "target_metric": "ending_mrr", "horizon": 12
} }

1 年後に顧客の 90% が残る解約率はいくつですか？

{ "name": "break_even", "arguments": {
  "template": "churn_impact",
  "inputs": { "starting_customers": 1000, "arpu": 60, "new_customers_per_period": 0 },
  "solve_for": "churn_rate", "target_metric": "retention_pct",
  "target_value": 0.9, "horizon": 12
} }

→ required_input ≈ 0.008742（月あたり約 0.87%）。

成長戦略を比較します：

{ "name": "compare_scenarios", "arguments": {
  "scenarios": [
    { "name": "Base",           "template": "saas_growth", "inputs": { "churn_rate": 0.04, "new_customers_per_period": 30 } },
    { "name": "Aggressive",     "template": "saas_growth", "inputs": { "churn_rate": 0.04, "new_customers_per_period": 60 } },
    { "name": "RetentionFocus", "template": "saas_growth", "inputs": { "churn_rate": 0.015, "new_customers_per_period": 30 } }
  ],
  "compare_metric": "ending_mrr", "goal": "max", "horizon": 12
} }

自由形式（カスタム）モデル：

{ "name": "run_scenario", "arguments": {
  "metrics": [
    { "name": "revenue", "start": 10000, "growth_rate": 0.08, "mode": "compound" },
    { "name": "headcount", "start": 12, "growth_rate": 0.05, "mode": "linear" }
  ],
  "horizon": 12
} }

---

Cloudflare Pages へのデプロイ

PrecisionCalc／DecisionMatrix と同じパターンです。1 つのビルドステップで worker-src/ を site/_worker.js（Pages の「advanced mode」Function）にバンドルし、その後 Wrangler で site/ ディレクトリをデプロイします。

npm install
npx wrangler login          # once

# Build + deploy in one shot
npm run deploy              # esbuild -> site/_worker.js, then wrangler pages deploy

または、Git に接続します。Pages プロジェクトを作成し、ビルドコマンドに npm run build を、出力ディレクトリに site を設定します。プッシュするたびに自動でデプロイされます。 compatibility_date とプロジェクト名は wrangler.toml に記載されています。

完全無料かつプライベートで実行するために、バインディング、シークレット、環境変数は必要ありません。シミュレーションエンジンはステートレスで、サーバーはフェイルオープンで動作します（無料枠、クォータ無効）。

課金を有効にする（任意）

有料デプロイでは、以下を複製してください。

1. API キーと日次使用量カウンター用の KV 名前空間。wrangler.toml で SCENARIOSIM_KV としてバインドします （wrangler kv namespace create SCENARIOSIM_KV）。
2. Stripe の商品／価格（サブスクリプション）— 価格 ID を [vars] に設定します （PRICE_STARTER、PRICE_PRO）。あわせて日次制限（FREE_DAILY、STARTER_DAILY、 PRO_DAILY）も設定します。
3. Stripe シークレット（リポジトリには絶対に含めないでください）：

   wrangler pages secret put STRIPE_SECRET_KEY     --project-name scenariosim-mcp
   wrangler pages secret put STRIPE_WEBHOOK_SECRET  --project-name scenariosim-mcp
   

4. Webhook → customer.subscription.updated と customer.subscription.deleted 用の Stripe webhook エンドポイントを https://<your-domain>/webhook に作成します。

接続済みのルート：/checkout?plan=starter|pro → Stripe Checkout、/success は API キーを発行して表示します（冪等）。/portal は Stripe の課金ポータルを開き、/webhook はサブスクリプションのライフサイクル（取り消し／復元）を処理し、/metrics は使用状況を報告します。

---

認証とレート制限

ホスト型サーバーは worker-src/billing.mjs で段階別のクォータを適用します。

• ID の識別 — identify() は X-API-Key／Authorization: Bearer を読み取り、KV でキーを検索し、該当するキーがなければ IP ごとの無料枠にフォールバックします。(JWT／mTLS／組織ごとのキーを追加する場合は、extractKey と identify だけを変更します。エンジンとトランスポートには手を加えません。)
• クォータ — consumeQuota() は KV の日次カウンターです（00:00 UTC にリセット）。handleRpc 内で method === "tools/call" の場合に実行される唯一の制限判定ポイントです。(分単位の制限を設けるには、Durable Object または Redis でスライディングウィンドウ／トークンバケットに置き換えてください。NOTE (rate limiting) コメントを参照してください。)
• ペイウォールの応答 — クォータ超過／無効／取り消し済みのキーには、料金とチェックアウト URL を含む構造化された upsell エンベロープを返します（エージェントはこれを読み取り、対応できます）。
• 使用量の計測 — /metrics にインメモリカウンターを設けています。

ScenarioSim に有料プラン限定のツールはありません。すべてのツールはどのプランでも利用でき、有料プランでは日次クォータだけが増えます。特定のツールを有料プラン限定にするには、index.mjs の PAID_ONLY_TOOLS にその名前を追加します。エンジンは純粋かつステートレスであるため、これらの変更がシミュレーションロジックに影響することはありません。

---

設計上の決定と前提

• 構造上、決定論的です。 40 桁の十進演算、すべての計算での ROUND_HALF_UP、期間ごとの反復（float**n は使いません）を採用し、結果に時計や乱数は使いません。
• 期間 0 は開始時点の状態で、期間 1..horizon が予測期間です。period_label は年換算係数を設定します（month → 年 12 回など）。この係数は ARR／給与計算に使われます。
• 前提条件はすべて返されます（assumptions_used）。デフォルト値も補完されるため、呼び出し側は何がシミュレーションされたのかを常に正確に把握できます。
• 精度を保つため、件数は小数のままです（例：顧客数 233.6 人）。必要に応じて、表示レイヤーで整数に丸めてください。この点は notes に記載されています。
• 弾力性／成長モデルは、意図的にシンプルで透明性の高いものです（一定の弾力性、期間ごとの一定の増加率）。計量経済学的な予測ではなく、誠実な一次推定値です。方法論のブロックにもその旨が記載されています。
• break_even は二分法を使います。ブラケットを自動的に拡張し、反復回数を固定することで決定論的に動作します。解を求める入力の範囲内で、指標が単調であることを前提とします。非単調な指標や、極を持つ比率指標では、誤った解を返すのではなく、明確な no_solution を返します。sensitivity_analysis／break_even は名前付きテンプレートに対して動作し、自由形式の custom モデルには対応していません。誤った使い方をした場合は、その旨を通知します。
• エラーは例外ではなくデータです。 すべてのツールは、機械処理可能な type と、実行可能な対処方法を示す hint を含む status:"error" を返します。検証では、未知のテンプレート／入力／指標、数値以外の値、不正な予測期間／期間ラベル、到達不可能な目標などを確認します。
• ステートレスで副作用がありません。 簡単にキャッシュでき、水平スケーリングが可能で、どこでも安全に実行できます（Cloudflare、Node、Deno、Bun）。

---

テスト

npm test          # node --test tests/*.test.mjs  (29 tests, no network)

テストスイートでは、手作業で検証できる算術計算（複利成長率、LTV/CAC、弾力性、資金繰り余力）を固定し、決定性、複数の前提入力形式、期間ラベルの年率換算、自由形式のカスタムモデル、感度分析のスイープと影響度ランキング、損益分岐点ソルバー（到達不能な目標への対応を含む）、goal=min を使ったシナリオ比較、およびすべてのエラーパスを確認します。

---

ロードマップ（MVP 後）

1. テンプレートの追加：LBO/DCF、在庫とキャッシュ・コンバージョン・サイクル、広告費用対効果（ROAS）、コホート継続率。
2. モンテカルロモード：入力値の分布から結果の信頼帯を算出します（シードを指定し、引き続き決定的です）。
3. 一変数ずつの感度分析に加えて、多変数（グリッド）感度分析とトルネードチャートを追加します。
4. 自由形式の custom モデルと、複数の同時入力に対する損益分岐点分析。
5. キーごとの使用状況ダッシュボードと、より強い一貫性を実現する Durable Object のクォータ。

ライセンス

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