decisionmatrix-mcp

DecisionMatrix MCP

一个透明、100% 确定性的 模型上下文协议（MCP） 服务，为大模型 Agent 提供可靠的**多准则决策分析（MCDA）**引擎。

Agent 擅长收集选项，但在权衡方面并不可靠：它们会失去精度、使用不一致的权重，也无法展示推理过程。DecisionMatrix 将评分工作交给精确且可解释的引擎。你提供选项和加权准则（以及评分矩阵）；它会返回经过完整评分、排名并附有解释的结果，包括各准则的细分结果、所用方法、应用的权重，以及通俗易懂的解释。

每个数字都通过 decimal.js 以 40 位精度进行计算（绝不使用浮点数），因此相同的输入始终会产生逐字节完全相同的输出。该服务无状态——没有数据库，也没有会话。

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

Cloudflare 边缘网络上运行着一个公开的远程 MCP 服务——将任何 Streamable-HTTP MCP 客户端指向它即可：

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

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

免费套餐以开放模式运行（无需密钥，每个 IP 每天可调用 15 次）。付费套餐 （Starter $12/mo · 5,000/day、Pro $39/mo · 50,000/day）已通过 Stripe Checkout 上线——购买套餐后即可立即获取 API 密钥，并将其作为 X-API-Key 发送。可自托管以实现无限次调用，无需密钥。落地页 + 定价：https://decisionmatrix-mcp.pages.dev。

---

功能

六种工具，均返回统一且可供 Agent 解析的封装结构：

工具	用途
create_decision	主要工具。 根据加权准则对选项进行排名 → 返回胜出选项、完整排名、各准则细分结果、方法、权重和通俗易懂的解释。
score_options	当分数单独提供时，返回完整的归一化评分矩阵。
sensitivity_analysis	将每个准则的权重上下调整 ±X%，并报告胜出选项的稳健程度（以及排名发生变化的范围）。
compare_two	对恰好两个选项进行正面对比，并统计各准则的胜出次数。
list_methods	发现可用的评分方法及其适用场景。
health_check	版本、状态和功能。

评分方法

method	model	normalization	notes
weighted_sum (默认)	简单加权法（SAW）	每个准则进行极差归一化	最透明；按加法计算贡献。支持负数。
weighted_product	加权乘积模型（WPM）	比率（x/max, min/x）	对任何单项较弱的准则惩罚更重；要求分数 > 0。
topsis	与理想解的接近程度	向量（欧几里得）	0–1 接近度系数；适用于准则较多的情况。

每个准则都有一个方向：benefit（越高越好——质量、速度）或 cost（越低越好——价格、延迟、风险）。权重是相对值；系统会在内部将其归一化，使总和为 1。

统一的响应封装结构

每个成功响应都包含：status、method、winner、ranking （包含各准则的 breakdown）、methodology、weights_used、inputs_used、 notes 和自然语言的 explanation。

{
  "status": "success",
  "method": "weighted_sum",
  "winner": { "option": "Gamma", "score": 0.666667, "score_exact": "0.666667", "rank": 1, "tie": false, "tied_with": [] },
  "ranking": [
    { "rank": 1, "option": "Gamma", "score": 0.666667, "score_exact": "0.666667",
      "breakdown": [
        { "criterion": "Price", "direction": "cost", "weight": 0.5, "weight_raw": "3",
          "raw_score": "900", "normalized_score": 1, "weighted_contribution": 0.5 }
      ] }
  ],
  "methodology": {
    "method": "weighted_sum",
    "name": "Weighted Sum Model (Simple Additive Weighting)",
    "normalization": "min-max per criterion (best value -> 1, worst -> 0)",
    "score_range": "0 to 1 (higher is better)",
    "weighting": "Criteria weights are normalized to sum to 1; only their relative sizes matter.",
    "deterministic": true
  },
  "weights_used": [ { "criterion": "Price", "direction": "cost", "weight_input": "3", "weight_normalized": 0.5 } ],
  "inputs_used": { "options": ["Alpha","Beta","Gamma"], "method": "weighted_sum", "option_count": 3, "criterion_count": 3 },
  "notes": [ "Scores are normalized within this option set; they express relative standing, not an absolute grade." ],
  "explanation": "Using the Weighted Sum Model, 'Gamma' ranks #1 with a score of 0.666667, ahead of 'Alpha' (0.527778) by 26.32% ..."
}

错误不会以异常形式越过工具边界——而是以结构化且可执行的封装结构返回：

{
  "status": "error",
  "error": {
    "type": "incomplete_scores",
    "message": "Missing 1 score(s) in the options x criteria matrix.",
    "hint": "Provide a score for every option and criterion. Missing: Beta / Weight."
  }
}

设计说明——精确数值：score 是经过确定性舍入的数字（保留 6 位小数），便于使用；score_exact / raw_score 是完整精度的字符串，因此 JSON 中不会丢失精度。排名基于精确值计算，输入顺序则作为稳定的平局判定依据。

---

项目结构

decisionmatrix-mcp/
├── worker-src/
│   ├── index.mjs        # Cloudflare Pages Function (_worker.js): MCP over Streamable HTTP + billing routes
│   ├── engine.mjs       # The deterministic MCDA engine: 3 methods + 6 tools + validation
│   └── billing.mjs      # Stripe Checkout + KV-backed API keys, quota metering, webhook
├── site/
│   ├── index.html       # Static landing / pricing / docs page
│   └── _worker.js        # Built bundle (esbuild output; git-ignored)
├── tests/
│   └── engine.test.mjs  # 21 core scoring-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 以及身份验证/计量接口。

---

要求

• Node 18+（用于构建、测试和本地开发）。只有两个开发/运行时依赖项： decimal.js（数学运算）和 esbuild（打包工具）。
• 一个 Cloudflare 账号（免费套餐即可），用于部署托管版本。

---

在本地运行

git clone <your-fork> decisionmatrix-mcp && cd decisionmatrix-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

快速手动调用：

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

---

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

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

npx -y decisionmatrix-mcp

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

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

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

客户端配置

Cursor — ~/.cursor/mcp.json

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

Claude Desktop — claude_desktop_config.json

Claude Desktop 会启动 stdio 服务，因此请使用 mcp-remote 桥接到 HTTP 端点：

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

VS Code — .vscode/mcp.json

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

任意 Streamable-HTTP MCP 客户端

将其指向 https://decisionmatrix-mcp.pages.dev/mcp（或你的可自托管 URL）。如果 启用了身份验证，请在客户端的 headers 中添加 X-API-Key（或 Authorization: Bearer <key>）。

---

工具和参数

create_decision(options, criteria, scores, method="weighted_sum")

• options — 名称数组（["Vendor A","Vendor B"]）或对象数组 （[{"name":"Vendor A","scores":{...}}]）。至少 2 个名称，且名称必须唯一。
• criteria — { "name", "weight" (>=0), "direction": "benefit"|"cost" } 数组。 至少有一个权重必须大于 0。
• scores — 选项×标准矩阵。接受以下形式：
  • 对象映射：{ "Vendor A": { "Price": 100, "Quality": 8 }, ... }
  • 数组：[ { "option": "Vendor A", "scores": { ... } }, ... ]
  • 内嵌于每个选项对象中。
• method — weighted_sum（默认）· weighted_product · topsis（也支持 saw、wpm、ideal 等别名）。

score_options(options, criteria, scores, method)

输入与 create_decision 相同；返回完整的评分矩阵（每个选项、每项标准的归一化分数及总分），不包含胜出者说明。

sensitivity_analysis(options, criteria, scores, method, variation=0.2, steps=10)

以 steps 个增量（2–100）将每项标准的权重从 -variation 扫描至 +variation（按比例计算，例如 0.2 = ±20%），同时对其他权重重新归一化，并在每次计算中重新确定胜出者。返回 robustness_score（基准胜出者保持第 1 名的情景占比）、fragile_criteria，以及每项标准对应的胜出者变更临界点。

compare_two(option_a, option_b, criteria, scores, method)

对比恰好两个选项（传入 option_a/option_b 名称，或包含两个元素的 options 数组）。返回胜出者、分数 margin、criteria_wins，以及 per_criterion 细分，显示每项标准更倾向于哪个选项。

list_methods() / health_check()

发现支持的方法并检查状态。无需参数。

---

工具调用载荷示例

选择一台笔记本电脑（价格和重量为成本标准）：

{ "name": "create_decision", "arguments": {
  "options": ["Alpha", "Beta", "Gamma"],
  "criteria": [
    { "name": "Price",   "weight": 3, "direction": "cost" },
    { "name": "Battery", "weight": 2, "direction": "benefit" },
    { "name": "Weight",  "weight": 1, "direction": "cost" }
  ],
  "scores": {
    "Alpha": { "Price": 1000, "Battery": 8,  "Weight": 1.5 },
    "Beta":  { "Price": 1200, "Battery": 12, "Weight": 1.8 },
    "Gamma": { "Price": 900,  "Battery": 6,  "Weight": 1.2 }
  }
} }

测试胜出者的稳健性：

{ "name": "sensitivity_analysis", "arguments": {
  "options": ["Alpha", "Beta", "Gamma"],
  "criteria": [
    { "name": "Price", "weight": 3, "direction": "cost" },
    { "name": "Battery", "weight": 2 }
  ],
  "scores": { "Alpha": {"Price":1000,"Battery":8}, "Beta": {"Price":1200,"Battery":12}, "Gamma": {"Price":900,"Battery":6} },
  "variation": 0.3, "steps": 8
} }

一对一对比：

{ "name": "compare_two", "arguments": {
  "option_a": "Alpha", "option_b": "Beta",
  "criteria": [ { "name": "Price", "weight": 3, "direction": "cost" }, { "name": "Battery", "weight": 2 } ],
  "scores": { "Alpha": {"Price":1000,"Battery":8}, "Beta": {"Price":1200,"Battery":12} }
} }

---

在 Cloudflare Pages 上部署

与 PrecisionCalc 使用相同的模式——通过一个构建步骤将 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 中绑定为 DECISIONMATRIX_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 decisionmatrix-mcp
   wrangler pages secret put STRIPE_WEBHOOK_SECRET  --project-name decisionmatrix-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 的免费层级。
• 配额 — consumeQuota() 是 KV 每日计数器（于 00:00 UTC 重置）；在 handleRpc 中，只有 method === "tools/call" 时才会经过此唯一的配额检查点。
• 付费墙响应 — 超出配额、密钥无效或已撤销时，会返回包含定价和结账 URL 的结构化 upsell 信封（Agent 可以读取并据此操作）。
• 用量计量 — 在内存中计数，并通过 /metrics 提供数据。

DecisionMatrix 没有仅限付费层级使用的工具——所有层级都能使用每个工具；付费方案只会提高每日配额。若要将某个工具设为仅限付费层级使用，请将其名称添加到 index.mjs 中的 PAID_ONLY_TOOLS。由于引擎是纯函数且无状态，这些改动都不会影响评分逻辑。

---

设计决策与假设

• 从设计上保证确定性。 使用 40 位十进制定点数运算，处处采用 ROUND_HALF_UP，并按输入顺序稳定地处理并列情况。结果不涉及浮点数、随机性或时钟。
• 按准则进行归一化，并考虑方向。 weighted_sum 使用最小-最大归一化（最佳→1，最差→0）；如果所有选项在某项准则上的值都相同，则将其视为中性（归一化为 1）并注明。weighted_product 使用比率归一化，并要求分数严格为正（否则会明确报错）。topsis 使用向量归一化，并根据与理想/反理想解的接近程度进行排名。
• 权重为相对值——归一化后总和为 1，因此 [3,2,1] 和 [30,20,10] 会得到相同结果。
• 分数相对于选项集——分数衡量的是给定备选方案内的相对表现，而非绝对等级。这一点会在 notes 中说明。
• 错误是数据，而非异常——每个工具都会返回带有机器可读 type 和可执行 hint 的 status:"error"。验证范围包括重复名称、缺失单元格（准确列出缺失项）、非数值分数、无效权重/方向以及未知方法。
• 无状态且无副作用——可轻松缓存、水平扩展，并可安全地在任何环境中运行（Cloudflare、Node、Deno、Bun）。

---

测试

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

测试套件会验证可手动核算的 weighted_sum 算术，并检查确定性、权重相对性、方向处理、并列情况、全部三种方法、compare_two、sensitivity_analysis、多种分数输入形式以及所有错误路径。

---

路线图（MVP 之后）

1. 增加更多方法：AHP（成对比较的权重确定）、ELECTRE、PROMETHEE、Borda 计数法。
2. 群体决策：汇总多个利益相关者的权重/分数组。
3. 在逐一扰动的基础上，增加蒙特卡洛敏感性分析（同时扰动所有权重）。
4. 按密钥提供用量仪表板，并使用 Redis/Durable-Object 配额以增强一致性。
5. 发布 npm 包，并推出托管式多租户层级。

许可证

MIT — 参见 LICENSE。