scenariosim-mcp

ScenarioSim MCP

一个透明的、100% 确定性的模型上下文协议（MCP）服务，为大模型 Agent 提供可靠的假设情景／情景模拟引擎。

Agent 擅长描述计划，却不擅长推算结果：它们在多期计算中容易出错，无法妥善处理复利，也无法展示推算过程。ScenarioSim 将模拟工作交给精确、可解释的引擎处理。你提供假设（增长率、客户流失率、定价、成本、起始指标、时间范围）；它会返回随时间变化的预测结果、关键指标、实际采用的假设，以及敏感性分析和盈亏平衡计算，并为每项结果提供通俗易懂的说明。

所有数字都通过 decimal.js 以 40 位精度计算（绝不使用浮点数），因此相同输入始终会生成字节级完全一致的输出。该服务是无状态的——没有数据库、会话、时钟，结果也不受随机因素影响。

这是本套件中的第三款产品，与 PrecisionCalc MCP（确定性的高精度金融／商业计算）和 DecisionMatrix MCP（透明的多准则决策分析）采用相同的工程标准：项目结构、输出理念和 Cloudflare Pages 部署方式均一致。

🌐 在线托管服务（免费，无需安装）

Cloudflare 边缘网络上运行着一个公开的远程 MCP 服务——将任意支持 Streamable-HTTP 的 MCP 客户端指向此服务：

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

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

免费套餐采用开放模式运行（无需密钥，每个 IP 每天可调用 20 次）。可通过 Stripe Checkout 购买付费套餐（Starter：每月 $12 · 每天 5,000 次；Pro：每月 $39 · 每天 50,000 次）——购买套餐后会立即获得 API 密钥，将其作为 X-API-Key 发送即可。自托管可享无限调用次数，无需密钥。落地页及定价：https://scenariosim-mcp.pages.dev。

---

功能

六种工具，均返回格式统一、便于 Agent 解析的数据结构：

工具	用途
run_scenario	主要工具。 通过预建模板或自由格式模型预测一段时间内的结果 → 各期 projections、概要 key_results、实际采用的 assumptions_used、methodology、notes 和通俗易懂的 explanation。
sensitivity_analysis	一次调整一个或多个输入，并报告其对目标指标的影响——包含弹性估算、输出范围，以及影响最大的输入项排名。
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+（用于构建、测试和本地开发）。开发/运行时依赖仅有两个： 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，无需托管）

只需一条命令即可通过 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 排名。也可以提供显式的 values: [...] 或 min/max 网格，而非 variation。

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，分别与第一个场景（基线）进行比较。传入 compare_metric + goal（默认为 max，也可为 min）以进行排名并选出 winner。可在顶层设置共享 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
} }

要在一年后留住 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 使用相同的模式——一个构建步骤会将 worker-src/ 打包到 site/_worker.js（Pages“高级模式” 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. KV 命名空间，用于存储 API 密钥和每日用量计数器，并在 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 → 在 https://<your-domain>/webhook 创建 Stripe webhook 端点， 监听 customer.subscription.updated 和 customer.subscription.deleted。

已接入的路由：/checkout?plan=starter|pro → Stripe Checkout，/success 配置并显示 API 密钥（幂等），/portal 打开 Stripe 账单门户， /webhook 处理订阅生命周期（撤销/恢复），/metrics 报告用量。

---

身份验证与速率限制

托管服务在 worker-src/billing.mjs 中强制执行分级配额：

• 身份识别 — 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 信封（Agent 可以读取并据此操作）。
• 用量计量 — /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 模型），误用时会对此作出说明。
• 错误是数据，而非异常——每个工具都会返回 status:"error"，并附带机器可读的 type 和可执行的 hint。验证涵盖未知模板/输入/指标、非数值、无效预测期/周期标签、无法达到的目标等情况。
• 无状态且无副作用——易于缓存、可水平扩展，可安全地在任何环境中运行（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. Monte-Carlo 模式：为输入设置分布 → 为结果生成置信区间（使用种子，仍具确定性）。
3. 除逐项分析外，增加多变量（网格）敏感性分析和龙卷风图。
4. 支持对自由格式的 custom 模型以及多个同时变化的输入进行盈亏平衡分析。
5. 按密钥提供用量仪表板 + Durable-Object 配额，以增强一致性。

许可证

MIT — 详见 LICENSE。