Date Math

日期计算

为 AI Agent 提供精确的日期和时间计算，按调用付费。 大模型在处理工作日、夏令时、循环日程和节假日日历时并不可靠。Date Math 可通过 HTTP 或 MCP 提供确定的结果。

• **价格：**通过 x402 使用 Base 上的 USDC，每次调用 $0.001
• **免费试用：**每天可免费调用 MCP 工具 25 次，可在任何 MCP 应用中使用（Claude Desktop、Cursor，……）
• **访问方式：**无需注册，无需 API 密钥
• 基础 URL：https://date-math.datemath.workers.dev
• MCP 端点：https://date-math.datemath.workers.dev/mcp（Streamable HTTP）
• Agent 文档：/llms.txt · /openapi.json

工具

HTTP（POST，JSON 请求体）	MCP 工具	功能
/v1/diff	date_diff	计算两个日期之间的天数、周数、月数和工作日数。传入 country 可跳过该国家的公共假日；传入 workdays 可指定非周一至周五的工作周。
/v1/add	date_add	计算某日期之前或之后 N 天、周、月或工作日对应的日期
/v1/convert	timezone_convert	在 IANA 时区之间转换时间（考虑夏令时）
/v1/info	date_info	星期、ISO 周数、季度、一年中的第几天、闰年
/v1/holidays	public_holidays	207 个国家/地区在 2000–2050 年的公共假日
/v1/overlap	working_hours_overlap	查找跨时区的工作时间重叠时段（会议时段）
/v1/cron	cron_schedule	解析 cron 表达式，并列出任意时区中的下次运行时间
/v1/parse	parse_date_text	将“下周五下午 3 点”转换为精确的 ISO 日期时间
/v1/city	city_time	城市名称 → 时区和当地时间（7,000 多个城市）
/v1/recurrence	recurring_dates	将 iCal RRULE（“每月第 2 个星期二”）展开为日期
/v1/business_hours	business_hours_deadline	计算从现在起 N 个工作小时后的 SLA 截止时间，或已过去的工作时间
/v1/business_day	business_day	判断某日期是否为工作日；若不是，说明原因（周末或具体假日）；查找下一个/上一个工作日；查询当月的工作日
/v1/pay_dates	pay_dates	计算工资发放和账单日期（每月、每月 15 日和月末、每两周、每周），并避开周末和假日

在你的应用中使用

以下所有应用每天都可免费调用工具 25 次。无需注册，无需 API 密钥。

Claude Code

claude mcp add --transport http date-math https://date-math.datemath.workers.dev/mcp

**Claude Desktop / claude.ai：**进入 Settings → Connectors → Add custom connector，并粘贴 https://date-math.datemath.workers.dev/mcp。或者在 claude_desktop_config.json 中使用本地软件包：

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

Cursor（~/.cursor/mcp.json）

{ "mcpServers": { "date-math": { "url": "https://date-math.datemath.workers.dev/mcp" } } }

VS Code（.vscode/mcp.json）

{ "servers": { "date-math": { "type": "http", "url": "https://date-math.datemath.workers.dev/mcp" } } }

Windsurf（~/.codeium/windsurf/mcp_config.json）

{ "mcpServers": { "date-math": { "serverUrl": "https://date-math.datemath.workers.dev/mcp" } } }

Cline（MCP Servers → Configure）

{ "mcpServers": { "date-math": { "type": "streamableHttp", "url": "https://date-math.datemath.workers.dev/mcp" } } }

任何只能运行本地命令的应用：npx -y date-math-mcp（npm package）。将 DATE_MATH_PRIVATE_KEY 设置为持有 Base 上 USDC 的钱包密钥，即可自动支付超过免费额度的调用费用。

Vercel AI SDK

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({ transport: { type: "http", url: "https://date-math.datemath.workers.dev/mcp" } });
const tools = await mcp.tools(); // pass to generateText / streamText

LangChain / LangGraph（Python）

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({"date-math": {"transport": "streamable_http", "url": "https://date-math.datemath.workers.dev/mcp"}})
tools = await client.get_tools()

工作日工具接受 workdays（星期几的编号，0 = 星期日），用于指定其他工作周，例如 Sun–Thu 为 [0,1,2,3,4]，Mon–Sat 为 [1,2,3,4,5,6]。

每个响应都是一个 JSON 对象。错误格式为 {"error":{"code","message","example"}}，其中 example 是该工具的有效请求体。完整的架构和示例见 /openapi.json。

示例

# Unpaid call → HTTP 402 with payment terms in the PAYMENT-REQUIRED header
curl -i -X POST https://date-math.datemath.workers.dev/v1/business_hours \
  -H "Content-Type: application/json" \
  -d '{"start":"2026-11-06T16:00","hours":2,"timezone":"Asia/Manila","country":"PH"}'

请求正文	结果
/v1/business_hours {"start":"2026-11-06T16:00","hours":2,"timezone":"Asia/Manila"}	"deadline":"2026-11-09T10:00:00+08:00"（星期一）
/v1/add {"date":"2026-12-22","business_days":5,"country":"PH"}	"result":"2026-12-31"（跳过圣诞节和黎刹日）
/v1/overlap {"timezones":["Asia/Manila","Europe/London"],"date":"2026-11-10","work_end":"18:00"}	一个时间窗口：09:00–10:00Z
/v1/recurrence {"rrule":"FREQ=MONTHLY;BYDAY=2TU","start":"2026-01-01T10:00","timezone":"Asia/Manila","count":3}	1 月 13 日、2 月 10 日、3 月 10 日，均为 10:00 +08:00
/v1/business_day {"date":"2026-12-25","country":"PH"}	非工作日："holiday":"Christmas Day"，下一个工作日是 2026-12-28
/v1/pay_dates {"schedule":"semi_monthly","from":"2027-01-01","count":2}	1 月 15 日，然后 1 月 31 日（星期日）顺延至 1 月 29 日星期五

通过代码付款

任何 x402 客户端都会自动付款。使用官方 TypeScript 客户端：

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(privateKeyToAccount(process.env.KEY as `0x${string}`)) }],
});

const res = await pay("https://date-math.datemath.workers.dev/v1/city", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ cities: ["Cebu", "London"] }),
});
console.log(await res.json());

钱包需要在 Base 上持有 USDC。无需 ETH，因为支付中继会支付 Gas 费。

通过 MCP 使用

• 端点： https://date-math.datemath.workers.dev/mcp（Streamable HTTP，无状态）
• 列出工具（tools/list）免费。
• 每天前 25 次工具调用免费（按 IP 计算，每天 00:00 UTC 重置）。每个免费结果都会包含 _meta["date-math/free_calls_remaining"]。
• 之后，每次工具调用通过 x402 MCP 收费 $0.001。付款信息会随工具调用一起放在 _meta 中，支持 x402 的客户端会自动处理：

import { createx402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = createx402MCPClient({
  name: "my-agent", version: "1.0.0",
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
  autoPayment: true,
});
await client.connect(new StreamableHTTPClientTransport(new URL("https://date-math.datemath.workers.dev/mcp")));
const r = await client.callTool("public_holidays", { country: "US", year: 2026 });

不支持 x402 的 MCP 客户端可以使用每日免费调用次数；用完后，调用会返回“Payment required”。附带付款的客户端不会消耗免费调用次数。

免费额度仅适用于 MCP。普通 HTTP 调用始终需要付款（未付款的调用会返回 402），因为 x402 发现服务会检查这一点。

运行自己的副本

该服务是一个独立的 Cloudflare Worker，符合免费计划的限制：每次工具调用的 CPU 用时为 0–6 ms。

cd worker
npm install
npm test                 # 189 tests, including end-to-end payments with the real x402 clients
npx wrangler login
npx wrangler deploy

在 worker/wrangler.toml 中设置自己的钱包和价格：

设置	含义
PAY_TO	你的钱包地址。留空则所有端点都免费。
PRICE	每次调用的价格，例如 $0.001
X402_NETWORK	eip155:8453（Base）或 eip155:84532（Base Sepolia，用于测试）
FACILITATOR_URL	默认为 PayAI：无需密钥，且由其支付 Gas 费
FREE_CALLS_PER_DAY	每个 IP 每天可免费调用 MCP 工具的次数（默认值为 25，设为 0 可关闭）。计数器存储在 FREE_QUOTA Durable Object 中。

可选密钥（使用 npx wrangler secret put 设置）：

• CDP_API_KEY_ID、CDP_API_KEY_SECRET： 优先通过 Coinbase 的支付中继结算。
• POCKET_PREFIX： 供受信任的中继使用的私有免付费路径。

要根据 x402scan 的发现规则检查部署，请运行 node tools/x402scan-audit.mjs https://your-worker.workers.dev。 要检查是否能够实际收款（通过 HTTP 和 MCP，模拟 Agent 付款的方式），请运行 API_URL=https://your-worker.workers.dev EXPECTED_PAY_TO=0xYourWallet node worker/scripts/payment-monitor.mjs。

构建方式

• **技术栈：**在 Cloudflare Workers 上使用 Hono，以及 @x402/hono 和 @x402/mcp。
• **发现：**通过带有 x-payment-info 的 OpenAPI、/.well-known/x402、每个 402 响应中的 x402 Bazaar 元数据、llms.txt，以及在 /.well-known/ai-catalog.json 中列出的 /mcp/server-card 处的 MCP 服务器卡片。
• **预计算数据：**节假日表和城市表在构建时生成（worker/scripts/build-*.mjs），因此每次请求的查询复杂度为 O(1)。
• **时区：**UTC 偏移量来自缓存的 Intl 格式化器和按周分段的缓存。针对棘手时区（摩洛哥、Lord Howe、Chatham）进行了与直接查询结果的比对测试。
• **Cron：**内置引擎（worker/src/cron.ts），并使用 400 个随机表达式与 cron-parser 进行比对。
• **Workers 专用垫片：**x402 的 Bazaar 路由验证器使用 Ajv 代码生成（new Function），而 Workers 会拦截它。wrangler.toml 将其别名指向一个无操作垫片（worker/src/shims/bazaar.ts）。

数据和许可证

• **代码：**MIT，详见 LICENSE。第三方数据声明见 NOTICE。
• **节假日数据：**源自 date-holidays（CC BY 3.0）。农历日期或政府宣布的日期为基于规则的估算值。
• **城市数据：**源自 city-timezones（MIT），基于 Natural Earth（公共领域）。

联系方式：请参阅 /openapi.json 中的 info.contact。