cron-mcp
Cron toolkit: validate 5/6-field expressions (L/#nth), next fire times in any IANA timezone
التثبيت
أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: .cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).
@nopilot/cron-mcpclaude mcp add cron-mcp -- npx -y @nopilot/cron-mcp@1.0.1
{
"mcpServers": {
"cron-mcp": {
"command": "npx",
"args": [
"-y",
"@nopilot/cron-mcp@1.0.1"
]
}
}
}
التوثيق
مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.
المحتويات
temporal-tools
Deterministic temporal tool family — cron and timezone/timezone-DST utilities as npm engines and local-first MCP servers. Same input, same output, every time: zero LLM calls, zero network requests, zero external data sources. All timezone math runs against the IANA tzdata bundled with your Node.js runtime.
为什么做这个 / Why: LLMs are famously unreliable at cron math and timezone math. These tools give agents (and humans) a deterministic oracle instead of a guess.
中文说明见 § 中文说明。
Packages
| Package | What it is | npm |
|---|---|---|
@nopilot/cron-engine | Validate cron (5 & 6-field), compute next-N fire times in any IANA timezone, render human-readable explanations (English/中文) | publishable engine |
@nopilot/tz-engine | Instant & wall-clock conversion with DST gap/overlap classification, per-year DST transition lists, cross-timezone meeting-window search | publishable engine |
@nopilot/cron-mcp | MCP server exposing the cron engine as tools (cron_validate, cron_next_runs, cron_describe) | publishable server |
@nopilot/tz-mcp | MCP server exposing the tz engine as tools (tz_validate_zone, tz_convert_instant, tz_convert_local_time, tz_dst_transitions, tz_meeting_windows) | publishable server |
@nopilot/mcp-server-common | Shared stdio + Streamable HTTP runner (internal, not published) | — |
MCP servers
Both servers speak the Model Context Protocol via the official TypeScript SDK and offer two transports:
- stdio — for local clients (Claude Code, Claude Desktop, Cursor, …): the client spawns the process.
- Streamable HTTP — for when you prefer a local HTTP endpoint: stateless JSON-RPC POST on
/mcp.
Tool catalog
cron-mcp
| Tool | Description |
|---|---|
cron_validate | Validate a 5- or 6-field expression; returns normalized parts, error text, and whether dom/dow are both restricted. Supports L, ?, #nth. (W/LW are not supported — rejected deterministically.) |
cron_next_runs | Next N fire times (ISO-8601 UTC) anchored to any IANA timezone, searched from an explicit instant. DST gaps roll forward; ambiguous times take the later offset. |
cron_describe | Plain-English or 简体中文 sentence explaining the expression. Template-based, deterministic. |
tz-mcp
| Tool | Description |
|---|---|
tz_validate_zone | Is this a valid IANA zone name? Fail fast on typos. |
tz_convert_instant | One absolute instant → local wall clock in up to 25 zones, with offsets, offset names, DST-active flag. |
tz_convert_local_time | Wall-clock time in one zone → all target zones, with DST edge classification (normal / ambiguous = fall-back overlap (earlier occurrence used) / gap = spring-forward (resolves forward)) and optional meeting end time. |
tz_dst_transitions | All UTC-offset transitions of a zone in a year — e.g. US Eastern 2026: forward at 2026-03-08T07:00Z (−05:00→−04:00), backward at 2026-11-01T06:00Z. Handles 30-min (Lord Howe) and 45-min (Chatham) zones. |
tz_meeting_windows | Slots on a date that fall inside business hours for every participant zone (2–10 zones, 15/30/60-min steps, configurable 09:00–18:00 default). |
Quick start (stdio)
// Claude Code / Claude Desktop config
{
"mcpServers": {
"cron": { "command": "npx", "args": ["-y", "@nopilot/cron-mcp"] },
"tz": { "command": "npx", "args": ["-y", "@nopilot/tz-mcp"] }
}
}
From this repo (no npm install of published packages needed):
npm install && npm run build
node packages/cron-mcp/dist/main.js # stdio mode
node packages/tz-mcp/dist/main.js --transport http --port 9411
# -> [mcp] listening on http://127.0.0.1:9411/mcp
HTTP mode is stateless Streamable HTTP: every POST is a self-contained JSON-RPC
request (initialize not required before tools/list or tools/call). The server binds
127.0.0.1 by default and never phones home.
curl -s http://127.0.0.1:9411/mcp \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"cron_next_runs","arguments":{"expression":"*/15 9-17 * * 1-5","count":3}}}'
Why local-first (vs hosted-gateway alternatives)
| temporal-tools | hosted-gateway cron/tz servers (e.g. the factory-style listings) | |
|---|---|---|
| Runs where | Your machine (stdio child process or localhost HTTP) | Vendor's gateway |
| Network calls at runtime | None — impossible by construction | Every tool call round-trips to the gateway |
| Works offline / air-gapped | Yes | No |
| Data leaves your machine | Never (expressions/timezones are still data) | Query text transits vendor infra |
| Determinism | Same input → byte-equal output (audited by scripts/determinism-check.mjs) | Depends on gateway version |
| Timezone data | IANA tzdata bundled with your Node.js runtime | Server-side, unknown version |
Engines (library use)
import { nextRuns, describeCron, validateCron } from '@nopilot/cron-engine';
validateCron('0 30 9 * * *'); // { valid: true, fieldCount: 6, ... }
nextRuns('30 2 * * *', { // DST edge: 2026-03-08 02:30 America/New_York
count: 2,
from: '2026-03-08T00:00:00Z',
timezone: 'America/New_York',
}); // runs: ['2026-03-08T07:30:00.000Z', '2026-03-09T06:30:00.000Z']
describeCron('0 9 * * 1-5', { locale: 'zh' }); // 「在上午 09:00, 星期一至星期五」
import { convertInstant, dstTransitions, meetingWindows } from '@nopilot/tz-engine';
convertInstant('2026-06-15T12:00:00Z', ['Asia/Kathmandu']); // offset +05:45
dstTransitions('America/New_York', 2026); // spring 03-08, fall 11-01
meetingWindows({ participants: ['Asia/Shanghai', 'Europe/London'], date: '2026-06-15' });
Development
npm install
npm test # build + typecheck + 57 vitest cases + determinism audit
npm run determinism # just the byte-equal audit (22 cases, 2 fresh processes)
npm run publish:dry # npm pack --dry-run for all publishable packages
Test coverage highlights: month-end rollover, leap-year Feb 29 (2028 vs 2026/27),
L last-day/last-weekday, #nth, 2026 US spring-forward gap (03-08) and fall-back
overlap (11-01), fractional offsets (+05:45 Kathmandu), sub-hour DST (Lord Howe
+30min), 45-minute zones (Chatham +12:45/+13:45), and MCP protocol round trips over
both transports.
Dependencies & licenses
Runtime dependencies (all permissive, no GPL/AGPL anywhere in the tree — verified against each package's npm metadata):
| Package | License | Why |
|---|---|---|
cron-parser | MIT | cron field parsing + next-fire iteration + timezone anchoring |
cronstrue | MIT | human-readable cron rendering (en + zh_CN locales) |
luxon | MIT | IANA zone math, DST gap/overlap resolution, offset names |
@modelcontextprotocol/sdk | MIT | MCP protocol layer (server + transports) |
zod | MIT | tool input schema validation |
express | MIT | Streamable HTTP transport host |
Engines wrap these libraries behind a stable, documented API; they are declared in
each package's package.json and listed here per the repo's license-compliance norm.
License
MIT — see LICENSE.
中文说明
temporal-tools 是一个「确定性时间工具族」:cron 解析/下次触发计算/中英文人话解释, 加上跨时区换算/DST 切换日查询/跨时区排会,以 npm 引擎包 + 本地 MCP server 双形态提供。
三判据(产品定位,不可违背):
- 确定性动作工具,非 AI 包装 — 同输入必同输出(
npm run determinism做逐字节审计),零 LLM 调用; - 纯本地计算 — 零外部数据源、零网络请求,时区数据用 Node.js 运行时内置的 IANA tzdata;
- 本地运行 — stdio 子进程或本机 HTTP(默认只绑 127.0.0.1),不走任何托管网关。
与托管网关类竞品的差异:竞品每次工具调用都要回厂商网关(隐私/离线双弱点);本项目所有计算 在你机器上完成,断网可用,表达式内容不离开本机。
已知边界:W/LW(最近工作日)修饰符不受底层 cron-parser 支持,会被确定性拒绝并返回
明确错误(不瞎猜);DST 重叠时刻(秋季回拨)取较早一次出现;DST 空洞时刻(春季跳变)向前解析。
发布步骤(面向零背景读者)见 PUBLISH.md。
الأسئلة الشائعة
ما هو cron-mcp؟
Cron toolkit: validate 5/6-field expressions (L/#nth), next fire times in any IANA timezone
كيف أثبّت cron-mcp؟
يعمل على جهازك. في Claude Code: claude mcp add cron-mcp -- npx -y @nopilot/cron-mcp@1.0.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.
هل يحتاج cron-mcp إلى مفتاح API؟
لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.
هل cron-mcp مفتوح المصدر؟
نعم. شيفرته متاحة على GitHub بترخيص MIT.
من يصون cron-mcp؟
ينشره latbert. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.
من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.