precisioncalc-mcp

PrecisionCalc MCP

LLM エージェントに、信頼性の高い高精度なビジネス、財務、業務計算を提供する、決定論的な Model Context Protocol（MCP） サーバーです。

LLM は、複数段階の財務計算式、通貨換算、営業日ロジック、成長計算で、精度を失ったり、もっともらしい誤情報を生成したりすることがよくあります。PrecisionCalc は、正確で透明性の高いツールにこれらの処理を委ねます。すべての金額・財務値は Python の decimal モジュールで計算され（浮動小数点数は使用しません）、すべての結果は、正確な値、人が読める形式の値、適用した計算式、使用した入力値、単位、前提条件・警告を含む、一貫性のある、エージェントが解析可能な JSON エンベロープで返されます。

v2 の主な機能： ライブおよび過去の為替レート（ECB）、14 種類の SaaS 指標、NPV／IRR、ローン返済計算、減価償却、batch_calculate ツール、国ごとの祝日、HTTP トランスポートでの API キー認証＋レート制限＋使用量計測、構造化 JSON ログ、オプションの OpenTelemetry トレース、プロパティベーステスト。

🌐 ライブホストサーバー（無料、インストール不要）

Cloudflare のエッジ上でパブリックなリモート MCP サーバーが稼働しています。任意の Streamable-HTTP MCP クライアントから接続してください：

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

npm でインストール（stdio、ホスティング不要）

コマンドを 1 つ実行するだけで、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" } } }

エッジビルド（worker-src/）は、Python エンジンを decimal.js で再現した Cloudflare Pages Function です。17/17 の出力が完全一致することを検証済みです。ランディングページ＋ドキュメント：https://precisioncalc-mcp.pages.dev。

プラン（ホストエンドポイント）

プラン	価格	1 日あたりの呼び出し数	ライブ／過去の為替レート	batch_calculate
Free（キー不要）	$0	15 / 日（IP ごと）	❌ 静的レートのみ	❌
Starter	$12/mo	5,000 / 日	✅	✅
Pro	$39/mo	50,000 / 日	✅	✅

決済には Stripe（サブスクリプション）を使用します。決済が完了すると、API キーがすぐに発行されます。X-API-Key: <key>（または Authorization: Bearer <key>）として送信してください。/portal で管理・キャンセルできます。上限に達すると、ツールは type、usage、購入ページの URL を含む upgrade ブロックを備えた、構造化された status:"error" エンベロープを返します。これにより、エージェントはユーザーにペイウォールを提示し、その手続きを進められます。自分のキーで無制限に呼び出すには、以下の手順でセルフホストしてください。

課金処理の内部実装は 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 を参照）。

エッジサーバーを再ビルド／再デプロイするには：

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、Rule of 40、マジックナンバー、損益分岐点など）
currency_convert	主要通貨 9 種類を換算。静的レート（オフライン）またはライブ／過去の ECB 為替レートを使用
business_days	営業日の加算・カウント、次／前の営業日を取得。米国／英国／EU＋任意の ISO 国＋カスタム祝日
compound_growth	将来価値、現在価値、CAGR を計算。連続複利を含む 7 種類の複利頻度に対応
net_present_value	キャッシュフロー系列の NPV／割引キャッシュフロー
internal_rate_of_return	IRR（ニュートン法＋二分法によるフォールバック）
loan_amortization	元利均等返済ローン：返済額、合計額、全返済スケジュール、繰上返済による完済計算
depreciation	定額法／定率法／年数合計法による減価償却スケジュール
batch_calculate	1 回のリクエストで複数の計算を実行
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	(空)	カンマ区切りのキー。空の場合はオープンモード（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	1 にすると、SDK が存在する場合に 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、または holidays パッケージがインストールされている場合は任意の ISO 国コード （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件）。1件の失敗でバッチ全体が中止されることはありません。

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を使用します。JSONでの浮動小数点数の精度損失を防ぐため、valueは文字列としてシリアライズし、見やすく整形したformatted_valueも別途用意します。精度は有効数字50桁です。
• 利率／マージンは小数（0.05 = 5%）で指定します。すべてのツールで説明されています。
• FX：オフライン時のデフォルトでは、USDベースのstaticテーブル（as_of 2024-06-01）を使用します。frankfurterプロバイダーは、メモリ内TTLキャッシュと静的データへのフォールバック機能を備え、最新および過去のECB為替レートを提供します。
• 営業日：祝日は年ごとに算出します（米国は移動祝日、英国／EUはイースター基準）。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で公開するメモリ内カウンターです。キーごとの課金に対応するための接続点です。
• FXプロバイダー — calculations/currency.py::RateProviderは、ライセンス取得済みデータフィードを組み込むための差し替え可能な接続点です。

---

ロードマップ（v2以降）

1. Redisを使ったレート制限と、課金対応の使用状況計測。
2. 過去のFXデータの永続化とプロバイダーの追加。メトリクスへの複数通貨の引き継ぎ。
3. 債券の価格設定／利回り、WACC、オプション（Black-Scholes）、税／VAT、単位変換。
4. OTelトレースと併せて、PrometheusエクスポーターとGrafanaダッシュボードを追加。
5. PyPIパッケージの公開と、GHCRでのDockerイメージ公開。マルチテナント対応のホステッドSaaS。