Precisioncalc MCP

PrecisionCalc MCP

A deterministic Model Context Protocol (MCP) server that gives LLM agents reliable, high-precision business, finance, and operational calculations.

LLMs routinely lose precision or hallucinate on multi-step financial formulas, currency conversions, business-day logic, and growth math. PrecisionCalc offloads that work to exact, transparent tools. Every monetary/financial value is computed with Python's decimal module (never floats), and every result is returned in a consistent, agent-parseable JSON envelope that includes the exact value, a human-readable value, the formula applied, the inputs used, the unit, and any assumptions/warnings.

v2 highlights: live + historical FX (ECB), 14 SaaS metrics, NPV/IRR,

loan amortization, depreciation, a batch_calculate tool, per-country holidays,

API-key auth + rate limiting + usage metering on the HTTP transport, structured

JSON logging, optional OpenTelemetry tracing, and property-based tests.

🌐 Live hosted server (free, no install)

A public remote MCP server runs on Cloudflare's edge — point any Streamable-HTTP MCP client at it:

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

Install via npm (stdio, no hosting)

Run the server locally over stdio with a single command — nothing to deploy:

npx -y precisioncalc-mcp

Claude Desktop / any stdio MCP client (claude_desktop_config.json):

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

This is the same deterministic engine as the hosted server, running on your machine.

{ "mcpServers": { "precisioncalc": {

"type": "http", "url": "https://precisioncalc-mcp.pages.dev/mcp" } } }

The edge build (worker-src/) is a Cloudflare Pages Function that mirrors the Python engine using decimal.js — verified 17/17 exact output parity. Landing page + docs: https://precisioncalc-mcp.pages.dev.

Plans (hosted endpoint)

Checkout is Stripe (subscription). On success you get an API key instantly; send it as X-API-Key: (or Authorization: Bearer ). Manage/cancel at /portal. When a limit is hit, tools return a structured status:"error" envelope with type, usage, and an upgrade block containing checkout URLs — so an agent can surface the paywall to the user and act on it. Self-host (below) for unlimited calls with your own keys.

Billing internals live in worker-src/billing.mjs (Stripe REST + Cloudflare KV for keys and daily counters). Server env: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, PRICE_STARTER, PRICE_PRO, FREE_DAILY, STARTER_DAILY, PRO_DAILY, and a PRECISIONCALC_KV namespace binding (see wrangler.toml).

Rebuild/redeploy the edge server:

npm install          # decimal.js + esbuild

npm run deploy # bundles worker-src -> site/_worker.js and deploys to Pages

---

What it does

11 tools, all returning a uniform structured response:

Consistent response envelope

Success:

{

"status": "success", "value": "1600", // exact, full-precision (string for money/rates) "formatted_value": "$1,600.00", // human-readable "formula": "LTV = (ARPU * gross_margin) / churn_rate", "inputs_used": { "arpu": "100", "gross_margin": "0.8", "churn_rate": "0.05" }, "unit": "USD", "notes": ["LTV = (ARPU x gross_margin) / churn_rate.", "..."] }

Error (never raised across the tool boundary):

{

"status": "error", "error": { "type": "missing_parameter", "message": "Missing required parameter 'churn_rate'.", "hint": "Include 'churn_rate' in params. See list_metrics for the full schema." } }

---

Project structure

precisioncalc-mcp/

├── server.py # MCP server: tool definitions + transports ├── security.py # API-key auth + token-bucket rate limit + metering (ASGI) ├── observability.py # Structured JSON logging + optional OpenTelemetry ├── requirements.txt / pyproject.toml ├── Dockerfile / .dockerignore ├── fly.toml / render.yaml # One-click hosting configs ├── .env.example ├── calculations/ │ ├── _util.py # Decimal coercion, validation, formatting │ ├── metrics.py # 14 business/SaaS metrics + catalog │ ├── currency.py # FX: static + Frankfurter (live/historical) providers │ ├── business_days.py # Region-aware holidays (built-in + holidays lib) │ ├── growth.py # FV / PV / CAGR │ └── finance.py # NPV / IRR / loan amortization / depreciation ├── schemas/responses.py # Response envelope helpers ├── examples/agent_example.py # End-to-end MCP client demo ├── site/ # Static landing/docs page (Cloudflare Pages) └── tests/ # 49 unit tests + Hypothesis property tests

---

Requirements

• Python 3.11+ (developed/tested on 3.12)
• Core: mcp, python-dateutil
• Recommended: uvicorn + starlette (HTTP transport), holidays (per-country calendars)
• Optional: opentelemetry-sdk (tracing), pytest + hypothesis (tests)

The server auto-detects the SDK layout and works with mcp >= 2.0 (MCPServer), mcp 1.x (FastMCP), or the standalone fastmcp package.

---

Run it locally

cd precisioncalc-mcp

python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt # or: pip install -e ".[all]"

stdio transport (default; how MCP clients launch it)

python server.py # or: precisioncalc-mcp (console entrypoint)

Streamable HTTP transport (endpoint: /mcp)

python server.py http PRECISIONCALC_API_KEYS=key1,key2 PRECISIONCALC_FX_PROVIDER=frankfurter python server.py http

Demo + tests:

python examples/agent_example.py         # live end-to-end over stdio

python tests/test_calculations.py # 28 core tests (no pytest needed) python tests/test_v2.py # 17 v2 tests python tests/test_properties.py # Hypothesis property tests

or simply: pytest -q

Register with an MCP client (stdio)

{ "mcpServers": { "precisioncalc": {

"command": "python", "args": ["/absolute/path/to/precisioncalc-mcp/server.py"] } } }

---

Deploy

Docker

docker build -t precisioncalc-mcp .

docker run --rm -p 8000:8000 -e PRECISIONCALC_API_KEYS=your-key precisioncalc-mcp docker run --rm -i precisioncalc-mcp python server.py stdio

Fly.io

fly launch --no-deploy

fly secrets set PRECISIONCALC_API_KEYS=key1,key2 fly deploy

Render.com

Push to GitHub, then New + → Blueprint and point at the repo (render.yaml). Set PRECISIONCALC_API_KEYS as a secret in the dashboard.

---

Configuration (env vars)

---

Tools & parameters

calculate_metric(metric, params, currency="USD")

Rates/margins are decimals (0.05 = 5%).

currency_convert(amount, from_currency, to_currency, date=None, live=None)

USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR. date (YYYY-MM-DD) or live=true uses live/historical ECB rates (frankfurter.app), with automatic static fallback on any network failure. Returns rate, provider, is_live, and timestamps.

business_days(operation, start_date, days=None, end_date=None, region="US", custom_holidays=None)

operation: add_business_days | count_business_days (inclusive) | next_business_day | previous_business_day. region: US | UK | EU | NONE, or any ISO country code when the holidays package is installed (DE, FR, CA, AU, JP, IN, ...).

compound_growth(operation, rate, years, present_value, future_value, begin_value, end_value, compounding="annually", currency="USD")

operation: future_value | present_value | cagr. compounding: daily | weekly | monthly | quarterly | semiannually | annually | continuous.

net_present_value(rate, cashflows, currency="USD")

NPV = Σ CFₜ/(1+rate)ᵗ. cashflows[0] = period 0 (usually the negative outlay).

internal_rate_of_return(cashflows, guess=0.1)

Per-period rate where NPV = 0. Requires a sign change in the cashflows.

loan_amortization(principal, annual_rate, term_months, extra_payment=0, currency="USD", include_schedule=false)

Returns monthly payment, months-to-payoff, total interest, total paid, and (optionally) the full month-by-month schedule.

depreciation(method, cost, salvage_value, useful_life_years, currency="USD")

method: straight_line | declining_balance | sum_of_years_digits. Returns the full yearly schedule; book value converges to salvage_value.

batch_calculate(calls)

calls: list of {"tool": , "arguments": {...}} (max 100). One item failing never aborts the batch.

list_metrics() / health_check()

Discovery + status. No parameters.

---

Example MCP tool-call payloads

{ "name": "calculate_metric",

"arguments": { "me