agentstack-mcp

AgentStack MCP

面向 AI Agent 的确定性推理栈——通过单个 Model Context Protocol（MCP）端点和一个 API 密钥提供服务：

模拟（ScenarioSim）→ 决策（DecisionMatrix）→ 计算（PrecisionCalc）

此外还有可串联这三个引擎的跨领域复合工具。所有数值都通过 decimal.js以 40 位精度计算 （绝不使用浮点数），因此相同的输入始终会产生逐字节相同的输出。 此服务无状态——没有数据库，也没有会话。

AgentStack 将三个独立的 MCP 服务整合在一起，让 Agent 只需安装一个 服务、使用一个密钥，即可执行涵盖这三个领域的推理。它直接导入相同的引擎 （不通过 HTTP 代理）——不会增加延迟，也不会发生级联故障。

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

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

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

免费套餐：无需密钥，每个 IP 每天可调用 20 次。付费套餐（Starter $19/月 · 8,000 次/天、 Pro $59/月 · 80,000 次/天）会提供一个通过 X-API-Key 发送的 API 密钥。一个密钥即可 使用全部三个产品和复合工具——费用约为分别订阅它们的一半。落地页：https://agentstack-mcp.pages.dev。

---

三个命名空间（24 个工具）

命名空间	引擎	工具
sim_*	ScenarioSim — 假设分析／情景模拟	sim_run、sim_sensitivity、sim_break_even、sim_compare、sim_list_templates
decide_*	DecisionMatrix — 多准则决策分析	decide、decide_score、decide_sensitivity、decide_compare_two、decide_list_methods
calc_*	PrecisionCalc — 精确的金融／商业计算	calc_metric、calc_list_metrics、calc_currency_convert、calc_business_days、calc_compound_growth、calc_npv、calc_irr、calc_loan_amortization、calc_depreciation
meta	—	list_capabilities、health_check

关于两个特意使用不同命名空间的同名工具： sim_sensitivity 变动 情景输入；decide_sensitivity 变动准则权重。它们是 不同的操作——前缀可帮助 Agent 区分二者。

复合工具——使用此推理栈的理由

端到端确定性执行；每个工具都会串联单个服务无法同时提供的引擎：

工具	流程	功能
plan_to_valuation	模拟 → 计算	预测一个情景，获取每期现金流序列（cashflow_metric），并评估其价值：以折现 rate 计算净现值（NPV）、**内部收益率（IRR）**和未折现总额。initial_investment 会作为第 0 期的流出额（计算 IRR 所需）。
evaluate_options_with_scenarios	模拟 → 决策	将每个选项分别预测为一个情景，然后根据从情景结果（key_results）中提取的加权准则对选项进行排序。
stress_test_decision	模拟 × 决策	对每个选项的同一情景假设进行压力测试，并报告基线胜出选项保持胜出的频率（稳健性）以及胜出选项发生变化的情况。

复合工具响应会报告其执行的 pipeline，并包含各阶段的结构化输出，让 Agent 可以深入查看任一步骤。

配置档案——减少工具选择干扰

在端点后附加 ?profile=，即可只加载一部分工具：

配置档案	工具
all (默认)	所有工具（24 个）
finance	calc_* + plan_to_valuation + meta
decision	decide_* + evaluate_options_with_scenarios + stress_test_decision + meta
simulation	sim_* + 所有复合工具 + meta

{ "mcpServers": { "agentstack": {
    "url": "https://agentstack-mcp.pages.dev/mcp?profile=finance" } } }

---

响应封装

命名空间工具会返回其底层产品的原样封装。复合工具会添加 composite、pipeline、 各阶段内容块、methodology、notes 和通俗易懂的 explanation。错误始终以结构化数据返回：

{ "status": "error", "error": { "type": "unknown_metric", "message": "...", "hint": "..." } }

示例 — plan_to_valuation（删节版）：

{
  "status": "success",
  "composite": "plan_to_valuation",
  "pipeline": ["scenariosim.run_scenario", "precisioncalc.net_present_value", "precisioncalc.internal_rate_of_return"],
  "scenario": { "template": "saas_growth", "horizon": 12, "key_results": { "ending_mrr": 26982.1 } },
  "cashflow_metric": "mrr",
  "cashflows": [-150000, 14040, 15600, "..."],
  "valuation": { "discount_rate": 0.01, "npv": 11157.386023, "irr": 0.02504, "value_creating": true },
  "explanation": "Projecting 'saas_growth' over 12 month(s) and valuing the 'mrr' stream at 1%/period gives an NPV of ..."
}

---

项目结构

agentstack-mcp/
├── worker-src/
│   ├── index.mjs           # Cloudflare Pages Function: MCP transport, namespacing, profiles, billing
│   ├── composites.mjs      # the 3 cross-domain tools (simulate -> decide -> compute)
│   ├── billing.mjs         # Stripe + KV: one key / one quota for the whole stack
│   └── engines/            # vendored, unmodified product engines (100% deterministic)
│       ├── scenariosim.mjs
│       ├── decisionmatrix.mjs
│       └── precisioncalc.mjs
├── server.mjs              # local stdio MCP server (same engines + composites; AGENTSTACK_PROFILE env)
├── site/                   # landing page + mcp.json + llms.txt + _worker.js (built)
├── tests/composites.test.mjs
├── examples/agent_example.mjs
├── scripts/sync-engines.sh # re-vendor engines from the sibling repos
├── package.json · wrangler.toml · server.json · smithery.yaml · Dockerfile · LICENSE
└── README.md

为什么要内置这些引擎？ 这样本仓库即可自包含且可复现。这些引擎与三个独立服务所使用的是同一套确定性模块；上游有变更时，运行 npm run sync-engines 即可从同级仓库重新复制它们。

---

在本地运行

git clone <your-fork> agentstack-mcp && cd agentstack-mcp
npm install
npm test                      # composite-logic tests (no network)
npm run dev                   # -> http://127.0.0.1:8788/mcp
node examples/agent_example.mjs            # hosted demo
node examples/agent_example.mjs http://127.0.0.1:8788
node server.mjs               # dependency-light stdio server (AGENTSTACK_PROFILE=finance to subset)

快速手动调用：

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_capabilities","arguments":{}}}'

---

通过 npm 安装（stdio，无需托管）

只需一条命令，即可通过 stdio 在本地运行服务——无需部署：

npx -y agentstack-mcp

Claude Desktop / 任意 stdio MCP 客户端（claude_desktop_config.json）：

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

这与托管服务使用的是同一套确定性引擎，只是在你的机器上运行。

客户端配置

Cursor — ~/.cursor/mcp.json

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

Claude Desktop — claude_desktop_config.json（通过 mcp-remote）

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

VS Code — .vscode/mcp.json

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

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

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

获取密钥后，添加 "headers": { "X-API-Key": "ssak_live_..." }。

---

复合载荷示例

根据预期结果为增长策略排序：

{ "name": "evaluate_options_with_scenarios", "arguments": {
  "template": "saas_growth", "horizon": 12,
  "options": [
    { "name": "Aggressive", "inputs": { "new_customers_per_period": 60, "churn_rate": 0.05 } },
    { "name": "Lean",       "inputs": { "new_customers_per_period": 20, "churn_rate": 0.02 } }
  ],
  "criteria": [
    { "metric": "ending_mrr", "weight": 3, "direction": "benefit" },
    { "metric": "total_churned_customers", "weight": 1, "direction": "cost" }
  ]
} }

评估计划的 MRR 收入流：

{ "name": "plan_to_valuation", "arguments": {
  "template": "saas_growth", "horizon": 12,
  "inputs": { "new_customers_per_period": 60, "churn_rate": 0.05, "arpu": 60 },
  "cashflow_metric": "mrr", "rate": 0.01, "initial_investment": 150000
} }

对决策进行压力测试：

{ "name": "stress_test_decision", "arguments": {
  "template": "saas_growth", "horizon": 12,
  "options": [ { "name": "Aggressive", "inputs": { "churn_rate": 0.05 } },
               { "name": "Lean", "inputs": { "churn_rate": 0.02 } } ],
  "criteria": [ { "metric": "ending_mrr", "weight": 3 } ],
  "stress": { "variable": "churn_rate", "variation": 0.5, "steps": 5 }
} }

---

部署到 Cloudflare Pages

npm install
npx wrangler login
npm run deploy      # esbuild -> site/_worker.js, then wrangler pages deploy

无需绑定或密钥即可完全免费 / 私密运行（免费层会默认放行）。如需计费：绑定 KV 命名空间 AGENTSTACK_KV，在 [vars] 中设置 PRICE_STARTER / PRICE_PRO，并添加 Stripe 密钥：

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

路由：/mcp（Streamable HTTP）、/checkout、/success、/portal、/webhook、/metrics。

身份验证与速率限制

在 worker-src/billing.mjs 中强制执行：identify() 读取 X-API-Key / Authorization: Bearer，并在未提供时回退到按 IP 分配的免费层；consumeQuota() 使用 KV 每日计数器（唯一的限流点）。一个密钥 / 一个配额适用于整个技术栈。标记为 NOTE (auth) / NOTE (rate limiting) 的接入点展示了如何替换为 JWT/mTLS 或令牌桶。这些机制都不会影响确定性数学计算。

与独立服务的关系

AgentStack 是补充方案，而非替代品。这三个产品仍可独立运行，适用于单一领域：

• ScenarioSim — https://scenariosim-mcp.pages.dev/mcp
• DecisionMatrix — https://decisionmatrix-mcp.pages.dev/mcp
• PrecisionCalc — https://precisioncalc-mcp.pages.dev/mcp

许可证

MIT — 参见 LICENSE。