decisionmatrix-mcp

Purpose

DecisionMatrix MCP addresses a common shortcoming of AI agents in the decision-making step: agents are good at collecting options, but unreliable when weighing trade-offs—they easily lose precision, apply weights inconsistently, and cannot show their reasoning process. This tool offloads the scoring work to a precise, explainable deterministic engine, so the agent only needs to provide the options, weighted criteria, and scoring matrix to obtain fully scored, ranked, and explained results.

Main Capabilities

• Three scoring methods: weighted sum (weighted_sum, default), weighted product (weighted_product), TOPSIS, with support for aliases such as saw, wpm, and ideal.
• Criterion direction awareness: each criterion can be set to benefit (higher is better, such as quality or speed) or cost (lower is better, such as price, latency, or risk).
• Exact computation: all numeric values are computed via decimal.js with 40-digit precision, using ROUND_HALF_UP, with no floating point, no randomness, and no clock involved in the results; the same input always produces byte-for-byte identical output.
• Unified response structure: every successful return includes status, method, winner, ranking (with per-criterion breakdown), methodology, weights_used, inputs_used, notes, and a natural-language explanation.
• Six tools:
  • create_decision(options, criteria, scores, method="weighted_sum")—complete scoring, ranking, and explanation;
  • score_options(options, criteria, scores, method)—returns the full scoring matrix (per-option, per-criterion normalized scores and total scores), without a winner narrative;
  • sensitivity_analysis(options, criteria, scores, method, variation=0.2, steps=10)—scans each criterion weight within the range of ±variation (e.g., 0.2 means ±20%) in increments of steps (2–100) and renormalizes the other weights, recalculates the winner, and returns robustness_score (the proportion of scenarios in which the baseline winner remains first), fragile_criteria, and the flip point for each criterion;
  • compare_two(option_a, option_b, criteria, scores, method)—a head-to-head comparison of two options, returning the winner, score difference, per-criterion win/loss counts, and a per-criterion breakdown;
  • list_methods() / health_check()—discovery and status query, with no parameters.
• Errors as data: errors are not thrown across the tool boundary as exceptions, but returned as a structured, actionable response envelope containing a machine type and a hint. Validation covers duplicate names, missing cells (listed precisely), non-numeric scores, invalid weights/directions, and unknown methods.
• Weight relativity: weights are internally normalized to sum to 1, so [3,2,1] and [30,20,10] produce the same result.
• Score relativity: scores measure the relative position of an option within the given alternative set, not an absolute rating, and this is stated in notes.

Usage

Hosted remote server (free, no installation required): the public remote MCP server runs at the Cloudflare edge, and any Streamable-HTTP MCP client can point to it. The free open mode requires no key and allows 15 calls per IP per day. Paid plans (Starter $12/month, 5,000 calls/day; Pro $39/month, 50,000 calls/day) are purchased through Stripe Checkout, and an API key is obtained immediately after purchase and sent in the X-API-Key header. Self-hosting has no call limits and requires no key.

npm installation (stdio, no hosting required): the server can be run locally via stdio with a single command, with no deployment required.

Client configuration locations:

• Cursor:~/.cursor/mcp.json
• Claude Desktop：claude_desktop_config.json(Claude Desktop launches the stdio server and needs to bridge to the HTTP endpoint with mcp-remote)
• VS Code:.vscode/mcp.json
• Any Streamable-HTTP MCP client: point it at the server address; if authentication is enabled, add X-API-Key (or Authorization: Bearer <key>) to the client headers.

Deployment: Can be deployed to Cloudflare Pages, in the same pattern as PrecisionCalc—a build step bundles worker-src/ into site/_worker.js (a Pages advanced mode Function), then Wrangler deploys the site/ directory; you can also connect it to Git, set the build command to npm run build, and set the output directory to site, for automatic deployment on every push. The compatibility date and project name are in wrangler.toml. Running completely free/privately requires no bindings, secrets, or environment variables.

Billing configuration (the hosted server is already live and can be replicated for a self-hosted paid deployment): requires a KV namespace (DECISIONMATRIX_KV) to store API keys and daily usage counts; the Stripe subscription product price IDs go in [vars] (PRICE_STARTER, PRICE_PRO) along with the daily limits (FREE_DAILY, STARTER_DAILY, PRO_DAILY); the Stripe secret is set via wrangler pages secret put ; the webhook endpoint handles customer.subscription.updated and customer.subscription.deleted; routes include /checkout, /success, /portal, /webhook, /metrics.

Authentication and rate limiting: identify() reads the X-API-Key or Bearer token and looks it up in KV, otherwise falls back to the IP-based free tier; consumeQuota() is a KV daily counter (reset at 00:00 UTC) and is the only gating point in handleRpc for method === "tools/call"; exceeding the quota or an invalid key returns a structured upgrade prompt envelope containing pricing and a checkout link.

Use cases

Suitable for any scenario that requires an AI agent to produce an explainable, reproducible ranking among multiple alternatives based on multiple weighted criteria—for example, vendor selection, technology stack comparison, procurement decisions, etc. Because the engine is stateless and side-effect-free, it is easy to cache, can scale horizontally, and runs safely in environments such as Cloudflare, Node, Deno, and Bun.

Limitations and notes

• The weighted sum uses min-max normalization (best→1, worst→0); if a criterion has the same value across all options, it is treated as neutral (normalized to 1) and noted.
• The weighted product uses ratio normalization and requires scores to be strictly positive, otherwise it returns an explicit error.
• TOPSIS uses vector normalization and ranks by closeness to the ideal/anti-ideal solution.
• Rankings are computed from exact values, with input order as a stable tie-breaker.
• Node 18+ is used for building, testing, and local development; there are only two development/runtime dependencies: decimal.js and esbuild.
• All tools are available at every tier; paid plans only increase the daily quota; if you want to make a tool paid-only, add its name to PAID_ONLY_TOOLS in index.mjs.

Project structure

engine.mjs is pure and transport-agnostic (it can be imported directly in tests or any Node/Deno/edge runtime); index.mjs only handles the MCP JSON-RPC connection, HTTP, CORS, and the authentication/metering seam.

Roadmap (after MVP)

More methods (AHP, ELECTRE, PROMETHEE, Borda count), group decision-making (aggregating weight/score sets from multiple stakeholders), Monte Carlo sensitivity analysis in parallel with one-by-one analysis, per-key usage dashboards and Redis/Durable-Object quotas, publishing an npm package and a hosted multi-tenant tier.

License: MIT.