API 文档

Calcton 对外提供两类程序化接口：面向 AI 助手的 MCP Server（Model Context Protocol）与面向开发者的 REST 端点。所有计算内核与网页版同源同口径，可直接集成到你的应用、脚本或智能体中。

MCP Server（AI 助手集成）

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，允许 AI 助手（Claude、ChatGPT、Gemini 等）以结构化方式调用外部工具。Calcton MCP Server 暴露 220 个纯计算工具（2026-06-06 起从 20 个扩容至 162，2026-06-06 再新增统计偏度/物理转动/化学溶液/金融资本成本等 58 项），AI 助手可直接获取精确结果。

POST/mcpJSON-RPC 2.0 端点

协议版本：2025-03-26。请求体遵循 JSON-RPC 2.0 格式，Content-Type 为 application/json。

支持的 RPC 方法：

initialize握手，返回服务端能力与协议版本

ping存活探测

tools/list列出全部可用工具及其参数定义

tools/call调用指定工具，返回计算结果

notifications/*通知类消息，返回 202 Accepted

暴露工具：

工具名	说明	关键参数
bmi	BMI 身体质量指数，WHO 七级分档	weightKg, heightCm
mortgage	房贷月供与总利息	principalWan, annualRatePct, years, method
percent	百分比三模式（of / what / change）	mode, a, b
unit_convert	单位换算（长度/重量/面积/体积/速度/数据量）	value, from, to, category
date_diff	两日期之间的天数、周数、月数	from, to（YYYY-MM-DD）
compound_interest	复利终值与利息	principal, rate, years
discount	折扣三模式（打折 / 满减 / 单价对比）	mode, price, zhe, amount…
tax	月薪个税（基础免征额 5000 元/月）	monthlyIncome
age	周岁、累计天数与下次生日	birthDate（YYYY-MM-DD）
temperature	摄氏 / 华氏 / 开尔文三向换算	value, from, to
speed	距离 / 速度 / 时间三量互算	known, speed, distance, time
gpa	四分制 GPA（支持 12 档等级）	courses（[{grade, credits}]）
currency	主流货币换算（静态参考汇率）	from, to, amount
loan	等额本息月供与总利息（单位：元）	amount, annualRatePct, months
slope	两点斜率、倾角与直线方程	x1, y1, x2, y2
z_score	标准分数 Z 与解读	value, mean, stdDev
density	密度 / 质量 / 体积三量互算	known, mass, volume, density
area	矩形 / 圆 / 三角形面积与周长	shape, length, width, radius, a, b, c
tip	小费金额与人均分摊	bill, tipPct, people
fuel_cost	行程油耗费用（距离 × 油耗 × 油价）	distance, consumption, fuelPrice

调用示例（以 BMI 为例）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bmi",
    "arguments": { "weightKg": 70, "heightCm": 175 }
  }
}

响应示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{...}" }],
    "structuredContent": {
      "bmi": 22.86,
      "whoCategory": "正常",
      "standard": "WHO 成人 BMI 分级（18.5 / 25 / 30 主切点）",
      "healthyRangeKg": [56.7, 76.3]
    },
    "isError": false
  }
}

完整参数定义以 tools/list 的实时返回为准（含每个字段的类型、枚举与描述），上表为速览。

接入配置：在 Claude Desktop 的 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "calcton": {
      "url": "https://www.calcton.com/mcp"
    }
  }
}

REST 计算端点（/api/v1）

面向应用与脚本的 REST 封装：一个端点即可调用 全部 220 个计算工具（统计、物理、金融、化学等，与 MCP Server 同源同口径自环转发），返回结构化 JSON。适合无法说 MCP 协议的 HTTP 客户端、Excel 脚本、微信/飞书机器人等场景。

POST/api/v1/calc{ tool, arguments } → 计算结果 JSON

POST/api/v1/keys创建 API key（默认日限 10000 次）

GET/api/v1/keys查询 key 用量（x-api-key 头）

GET/api/openapi.jsonOpenAPI 3.0 规范（可导入 Apifox / Postman）

全部公开接口的机器可读规范见 /api/openapi.json（OpenAPI 3.0，覆盖计算端点、Key 管理、投票、纠错反馈、AI 助手与运维接口），可直接导入 Apifox、Postman 或 Insomnia 生成调试环境。

鉴权与限额：携带 x-api-key 头走 key 额度（默认 10000 次/天）；不携带则享受 IP 免费额度 100 次/天。工具名与参数与 MCP 的 tools/call 完全一致（自环转发，覆盖全部 220 个工具），可用清单见上方 MCP Server 段或 POST /mcp tools/list。

# 1. 创建 key
curl -X POST https://www.calcton.com/api/v1/keys -H 'Content-Type: application/json' -d '{"name":"my-app"}'

# 2. 调用计算（示例：z_score 标准分数）
curl -X POST https://www.calcton.com/api/v1/calc \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-calc-xxxxxxxx' \
  -d '{"tool":"z_score","arguments":{"value":85,"mean":70,"stdDev":10}}'

# 3. 响应（含当日用量）
{
  "ok": true,
  "tool": "z_score",
  "data": {
    "tool": "z_score",
    "source": "https://www.calcton.com/z-score",
    "data": { "zScore": 1.5, "value": 85, "mean": 70, "stdDev": 10, "interpretation": "偏高" }
  },
  "usage": { "used_today": 1, "daily_limit": 10000 }
}

在线试调直接在浏览器调用，无 key 自动走 IP 免费额度

计算工具（… 个内核）API key（可选）

真实用户性能（RUM 看板）

全站页面通过 web-vitals 库匿名采集 Core Web Vitals（LCP / INP / CLS / FCP / TTFB），经 POST /api/web-vitals 落库（不采集任何身份信息），以下为近 24 小时真实用户 p75 聚合，评级口径与 Google Core Web Vitals 阈值一致。

加载性能数据中…

GET/api/web-vitals近 24h 各指标 count 与 p75 聚合（JSON）

POST/api/web-vitals上报单条指标：{ metric, value, rating?, path? }

GET 结果缓存 60s；POST 有指标白名单与数值范围校验，脏数据直接丢弃。

投票接口（REST）

用于工具详情页的「有用 / 没用」投票功能。基于 Supabase 存储，网页端按浏览器（localStorage）记录投票状态并支持改票与撤销；API 层为匿名计数，不关联用户身份，请勿高频刷票。

GET/api/vote?slug=bmi查询投票计数

POST/api/vote投一票（up 或 down）

DELETE/api/vote?id=xxx撤销投票

GET 响应：

{ "up": 42, "down": 3 }

POST 请求体：

{ "slug": "bmi", "vote": "up" }

POST 响应：

{ "id": "uuid", "up": 43, "down": 3 }

slug 必须为已注册的计算器标识（如 bmi、mortgage、discount），否则返回 404。投票为匿名计数，不关联用户身份。GET 结果不缓存（Cache-Control: no-store），POST 成功返回新插入记录的 id 与最新计数。

汇率接口（REST）

货币换算数据源：欧洲央行（ECB）参考汇率（经 frankfurter.dev），以人民币为基准，服务端缓存 12 小时；ECB 未覆盖的币种自动回落到静态参考表。

GET/api/exchange-rate最新汇率（CNY 为基准）

响应示例：

{
  "rates": { "USD": 6.7114, "EUR": 7.7441, "JPY": 0.0433 },
  "date": "2026-05-11",
  "source": "live",
  "base": "CNY"
}

rates 含义为 1 单位外币兑换的人民币（如 USD 6.7114 即 1 美元 ≈ 6.71 元）。source 取值 live（ECB 实时）或 static（兜底参考表）；响应头 Cache-Control: public, s-maxage=43200。涵盖 USD / EUR / GBP / JPY / HKD / KRW / AUD / CAD / SGD / CHF / TWD 等主流币种。

RSS 订阅

GET/rss.xmlRSS 2.0 订阅源

返回 application/rss+xml 格式的网站更新日志，取最近 20 条变更记录。响应头包含 Cache-Control: public, max-age=3600（1 小时缓存）。

在 RSS 阅读器中添加 https://www.calcton.com/rss.xml 即可订阅。

站点地图

GET/sitemap.xmlXML Sitemap

包含全站可索引页面的 URL、最后修改时间、变更频率与优先级。搜索引擎爬虫可自动发现，也可手动提交至 Google Search Console 或百度站长平台。

llms.txt（AI 爬虫指引）

GET/llms.txt面向 AI 爬虫的站点描述

遵循 llms.txt 开放标准，以纯文本格式描述站点结构、工具清单与 MCP 端点。AI 爬虫（如 ChatGPT Browse、Perplexity）可据此快速理解 Calcton 的能力边界。

robots.txt

GET/robots.txt爬虫访问规则

放行主流搜索引擎与 AI 爬虫（Googlebot、Bingbot、Baiduspider、GPTBot、ClaudeBot、PerplexityBot 等），禁止抓取 /api/ 前缀（内部接口）与 /_next/、/static/ 资源路径。嵌入页（/embed）通过 meta robots 的 noindex 声明而非 robots.txt 屏蔽——保持可抓取才能让搜索引擎读到 noindex 指令。

站内搜索

GET/search?q=房贷站内搜索落地页

返回 HTML 页面（非 JSON），基于标题、描述、关键词的中文/英文/拼音多相关度排序。支持直接链接分享，无客户端 JavaScript 依赖。

使用条款

以上接口均供个人与教育用途免费使用，无需注册。MCP、投票、汇率等接口直接调用即可；REST 计算端点可选创建免费 API key 以提升每日额度。请合理控制请求频率（建议不超过每分钟 30 次）。计算结果与网页版同源，但接口返回的是原始数值，格式化与展示由调用方自行处理。

如需批量集成或商业授权，请通过联系页沟通。