precisioncalc-mcp

PrecisionCalc MCP

一个确定性的 Model Context Protocol (MCP) 服务，为 LLM Agent 提供可靠的高精度商业、金融和运营计算。

LLM 经常在多步骤金融公式、货币换算、工作日逻辑和增长计算中丢失精度或产生幻觉。PrecisionCalc 将这些工作交给精确、透明的工具处理。所有货币／金融数值均使用 Python 的 decimal 模块计算（绝不使用浮点数），每个结果都会以一致且便于 Agent 解析的 JSON 封装返回，其中包含精确值、人类可读的值、所用公式、使用的输入、单位以及任何假设／警告。

**v2 亮点：**实时 + 历史外汇汇率（ECB）、14 项 SaaS 指标、NPV/IRR、贷款摊销、折旧、batch_calculate 工具、按国家划分的节假日、HTTP 传输上的 API 密钥身份验证 + 速率限制 + 用量计量、结构化 JSON 日志、可选的 OpenTelemetry 跟踪，以及基于属性的测试。

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

Cloudflare Edge 上运行着一个公开的远程 MCP 服务——将任意 Streamable-HTTP MCP 客户端指向它：

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

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

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

npx -y precisioncalc-mcp

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

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

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

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

Edge 构建版本（worker-src/）是一个 Cloudflare Pages Function，使用 decimal.js 实现了与 Python 引擎相同的功能——已验证 17/17 项输出完全一致。落地页 + 文档：https://precisioncalc-mcp.pages.dev。

套餐（托管端点）

套餐	价格	每日调用次数	实时／历史外汇汇率	batch_calculate
免费版（无需密钥）	$0	每天 15 次（按 IP 计算）	❌ 仅静态汇率	❌
入门版	$12/mo	每天 5,000 次	✅	✅
专业版	$39/mo	每天 50,000 次	✅	✅

通过 Stripe 结账（订阅）。成功后，你会立即获得一个 API 密钥；将其作为 X-API-Key: <key>（或 Authorization: Bearer <key>）发送。在 /portal 管理／取消订阅。 达到限额时，工具会返回结构化的 status:"error" 封装，其中包含 type、 usage，以及带有结账 URL 的 upgrade 区块——这样Agent 就能向用户展示付费墙并据此操作。如需不限次数地调用并使用自己的密钥，请自行托管（见下文）。

计费逻辑位于 worker-src/billing.mjs（Stripe REST + Cloudflare KV，用于存储密钥和每日计数器）。服务环境变量：STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、 PRICE_STARTER、PRICE_PRO、FREE_DAILY、STARTER_DAILY、PRO_DAILY，以及 PRECISIONCALC_KV 命名空间绑定（参见 wrangler.toml）。

重新构建／重新部署 Edge 服务：

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

---

功能

11 个工具，全部返回统一的结构化响应：

工具	用途
calculate_metric	14 项 SaaS／业务指标（LTV、CAC、流失率、MRR 增长、NRR、GRR、40 法则、魔力数字、盈亏平衡等）
currency_convert	换算 9 种主要货币；支持静态（离线）或 ECB 实时／历史汇率
business_days	增加／计算工作日、查询下一个／上一个工作日；支持美国／英国／欧盟 + 任意 ISO 国家 + 自定义节假日
compound_growth	未来值、现值、CAGR；支持 7 种复利频率，包括连续复利
net_present_value	现金流序列的 NPV／折现现金流
internal_rate_of_return	IRR（Newton 法 + 二分法回退）
loan_amortization	等额还款贷款：还款额、总额、完整还款计划、提前还款结清计算
depreciation	直线法／余额递减法／年数总和法折旧计划
batch_calculate	在一次请求中运行多项计算
list_metrics	发现：列出所有指标及其说明和必需参数
health_check	服务状态、版本、功能能力

一致的响应封装

成功：

{
  "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.", "..."]
}

错误（不会跨工具边界抛出）：

{
  "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."
  }
}

---

项目结构

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

---

要求

• Python 3.11+（在 3.12 上开发/测试）
• 核心依赖：mcp、python-dateutil
• 推荐：uvicorn + starlette（HTTP 传输）、holidays（按国家/地区划分的日历）
• 可选：opentelemetry-sdk（追踪）、pytest + hypothesis（测试）

服务会自动检测 SDK 布局，并兼容 mcp >= 2.0 （MCPServer）、mcp 1.x（FastMCP）或独立的 fastmcp 包。

---

在本地运行

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

演示 + 测试：

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

注册到 MCP 客户端（stdio）

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

---

部署

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

推送到 GitHub，然后选择 New + → Blueprint 并指定仓库（render.yaml）。 在控制面板中将 PRECISIONCALC_API_KEYS 设置为密钥。

---

配置（环境变量）

变量	默认值	用途
PRECISIONCALC_HOST / PRECISIONCALC_PORT	127.0.0.1 / 8000	HTTP 绑定
PRECISIONCALC_API_KEYS	(empty)	逗号分隔的密钥。为空 = 开放模式（仍按 IP 计量/限流）
PRECISIONCALC_RATE_LIMIT_PER_MIN / _BURST	120 / 40	令牌桶限额
PRECISIONCALC_METRICS_PATH	/metrics	使用情况指标端点
PRECISIONCALC_FX_PROVIDER	static	static 或 frankfurter（实时/历史 ECB）
PRECISIONCALC_FX_TTL / _TIMEOUT	3600 / 4	外汇缓存 TTL / HTTP 超时时间（秒）
PRECISIONCALC_LOG_LEVEL / _LOG_JSON	INFO / 1	日志记录
PRECISIONCALC_OTEL	0	若存在 SDK，设为 1 可启用 OpenTelemetry 追踪

---

工具与参数

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

费率/利润率使用小数表示（0.05 = 5%）。

指标	参数	单位
ltv	arpu、churn_rate、gross_margin(=1)	货币
cac	total_spend、new_customers	货币
ltv_cac_ratio	ltv、cac	比率
payback_period_months	cac、monthly_revenue_per_customer、gross_margin(=1)	月
contribution_margin	revenue、variable_costs	货币
gross_margin	revenue、cogs	百分比
churn_rate	customers_lost、customers_at_start	百分比
mrr_growth_rate	beginning_mrr、ending_mrr	百分比
arr	mrr	货币
break_even_units	fixed_costs、price_per_unit、variable_cost_per_unit	单位数
nrr	starting_mrr、expansion_mrr、contraction_mrr、churned_mrr	百分比
grr	starting_mrr、contraction_mrr、churned_mrr	百分比
rule_of_40	growth_rate、profit_margin	百分比
magic_number	current_quarter_revenue、prior_quarter_revenue、prior_quarter_sm_spend	比率

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

支持 USD、EUR、GBP、JPY、CAD、AUD、CHF、CNY、INR。date（YYYY-MM-DD）或 live=true 会使用实时/历史 ECB 汇率（frankfurter.app）；任何网络故障都会自动回退到静态数据。 返回汇率、提供方、is_live 和时间戳。

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

operation：add_business_days | count_business_days（含首尾）| next_business_day | previous_business_day。region：US | UK | EU | NONE，或者任意 ISO 国家/地区代码 （需安装 holidays 包；如 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] = 第 0 期现金流（通常为负支出）。

internal_rate_of_return(cashflows, guess=0.1)

使 NPV = 0 的每期利率。现金流必须至少发生一次符号变化。

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

返回月供、还清所需月数、总利息、总还款额，以及（可选）完整的逐月还款计划。

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

method：straight_line | declining_balance | sum_of_years_digits。返回完整的逐年计划；账面价值会逐渐趋近于 salvage_value。

batch_calculate(calls)

calls：{"tool": <name>, "arguments": {...}} 列表（最多 100 项）。单项失败不会中止整个批次。

list_metrics() / health_check()

发现 + 状态。无参数。

---

MCP 工具调用载荷示例

{ "name": "calculate_metric",
  "arguments": { "metric": "rule_of_40", "params": { "growth_rate": 0.30, "profit_margin": 0.15 } } }

{ "name": "currency_convert",
  "arguments": { "amount": 5000, "from_currency": "EUR", "to_currency": "GBP", "date": "2024-01-15" } }

{ "name": "net_present_value",
  "arguments": { "rate": 0.10, "cashflows": [-10000, 3000, 4200, 6800] } }

{ "name": "loan_amortization",
  "arguments": { "principal": 250000, "annual_rate": 0.065, "term_months": 360, "include_schedule": false } }

{ "name": "batch_calculate",
  "arguments": { "calls": [
    { "tool": "internal_rate_of_return", "arguments": { "cashflows": [-10000, 3000, 4200, 6800] } },
    { "tool": "depreciation", "arguments": { "method": "declining_balance", "cost": 50000, "salvage_value": 5000, "useful_life_years": 5 } }
  ] } }

---

设计决策与假设

• 所有涉及金额／利率的计算均使用 Decimal；value 序列化为字符串，以防 JSON 中浮点数精度丢失，并另提供便于阅读的 formatted_value。精度 = 50 位有效数字。
• 利率／利润率均为小数（0.05 = 5%），每个工具的文档中均有说明。
• 外汇：离线默认使用基于 USD 的 static 汇率表（as_of 2024-06-01）；frankfurter 提供方可提供实时及历史 ECB 汇率，并使用内存 TTL 缓存，必要时可平稳回退到静态汇率。
• 工作日：按年计算节假日（美国的浮动节假日、英国／欧盟的复活节相关节假日）；count 包含起止日期；add 接受负数；自定义节假日会合并；通过 holidays 库支持任意 ISO 国家。
• IRR 使用牛顿法，并在失败时回退到带区间的二分法；现金流必须至少发生一次符号变化。
• 错误不会以异常形式越过工具边界——始终返回 status:"error"，并附带机器可读的 type 和可执行的 hint。
• HTTP 加固可通过环境变量选择启用：API 密钥、令牌桶速率限制、/metrics 用量。
• SDK 兼容性垫片可在 mcp>=2.0、mcp 1.x 或独立 fastmcp 环境下运行，无需修改。

---

商业化接口

• 身份验证——PRECISIONCALC_API_KEYS；请求需提供 X-API-Key 或 Authorization: Bearer。
• 速率限制——按密钥使用令牌桶（开放模式下按 IP）；扩展时可替换为 Redis。
• 用量计量——内存计数器通过 /metrics 暴露；可据此按密钥计费。
• 外汇提供方——calculations/currency.py::RateProvider 是接入许可汇率源的扩展点。

---

路线图（v2 之后）

1. 基于 Redis 的速率限制 + 计费级用量计量。
2. 持久化历史外汇数据 + 更多提供方；在指标中贯通多币种。
3. 债券定价／收益率、WACC、期权（Black-Scholes）、税费／VAT、单位换算。
4. 与 OTel traces 配套的 Prometheus exporter + Grafana dashboard。
5. 发布 PyPI 软件包 + GHCR 上的 Docker 镜像；托管式多租户 SaaS。