导语:Rokuyo MCP 离线部署的核心价值在于将传统历法计算从云端 API 中解放出来,以确定性内核加 stdio 协议适配的方式嵌入 AI 智能体工作流。本文基于 Astromei 开源项目,完整拆解从源码构建、协议接入到生产排错的工业级落地路径。
一、为什么 Rokuyo MCP 离线部署值得认真对待
在 AI 智能体(Agent)工程实践中,工具调用的可靠性往往比模型本身更决定系统上限。Rokuyo(六曜)是日本传统历法中的六标签体系,大安、友引等标签广泛出现在婚期选择与日历场景中。Astromei 团队将其历法计算抽取为开源核心库,并叠加一层 Model Context Protocol 适配器,形成了可离线运行的 MCP 服务。
从架构师视角看,这个项目最值得借鉴的不是历法公式本身,而是它的分层决策:计算与解释分离、协议与内核解耦、边界显式声明。这三点恰好是生产级 AI 工具链最容易踩坑的地方。Rokuyo MCP 离线部署的意义,在于它提供了一个可审计、可复现、无运行时网络依赖的参考实现。
企业级架构规范
flowchart TD
subgraph 接入层 ["表现层与接入网关 (Client & Gateway Tier)"]
A["MCP 客户端 (桌面 Agent / IDE)"] --> B["stdio 传输通道 (JSON-RPC)"]
end
subgraph 协议层 ["协议适配与工具编排层 (Protocol & Tool Tier)"]
B --> C["rokuyo-mcp 适配器 (stdio.js)"]
C --> D["工具路由: get_rokuyo / get_rokuyo_month / find_rokuyo_dates"]
end
subgraph 内核层 ["确定性历法计算内核 (Deterministic Core Tier)"]
D --> E["astromei-core 历法引擎"]
E --> F["农历转换 (korean-lunar-calendar)"]
F --> G["六曜标签计算 (模 6 运算)"]
end
subgraph 边界层 ["契约与安全边界 (Contract & Safety Tier)"]
G --> H["日期窗口校验 (2025-01-01 ~ 2027-12-31)"]
H --> I["只读结果返回 (无副作用)"]
end
二、生产环境安装配置实战:从源码到可运行服务
2.1 环境前置与依赖锁定
截至 2026 年 11 月 20 日,npm 正式包尚未发布,因此生产部署必须走源码检出路径。你需要 Node.js 20 或更高版本、npm 与 Git。安装阶段需要网络访问,因为 MCP 适配器依赖一个以 HTTPS Git commit 形式锁定的 astromei-core 版本,安装过程会自动构建该依赖。一旦构建完成,后续所有历法查询均在本地执行,无需 API Key,也无运行时网络请求。
git clone https://github.com/astromei/rokuyo-mcp.git cd rokuyo-mcp npm ci npm run build
使用 npm ci 而非 npm install,是为了严格遵循 lockfile 锁定依赖树。在离线部署场景中,依赖的可复现性直接决定构建产物的可信度,这一点在 CI/CD 流水线中尤为关键。
2.2 本地 JavaScript 查询验证
构建完成后,建议先用一个最小脚本验证内核行为,再接入 MCP 客户端。将以下内容保存为 example.mjs 并执行 node example.mjs:
import { getRokuyo, getRokuyoMonth, findRokuyoDates } from './dist/index.js';
const day = getRokuyo('2026-10-11');
console.log(day.rokuyo);
console.log(day.lunarDate);
const month = getRokuyoMonth(2026, 11);
console.log(month.length);
const taianDates = findRokuyoDates('2026-11-01', '2026-11-30', '大安');
console.log(taianDates.map(({ date }) => date));
当前实现的输出为:先負、{ year: 2026, month: 9, day: 1, leap: false }、30,以及大安日期数组 ['2026-11-06', '2026-11-10', '2026-11-16', '2026-11-22', '2026-11-28']。每日结果还包含日文读音、罗马字、文化描述与惯用时段说明——这些是传统解释,不是预测。
2.3 MCP 客户端 stdio 配置清单
适配器暴露三个只读工具:get_rokuyo(单日查询)、get_rokuyo_month(整月生成)、find_rokuyo_dates(区间匹配)。对于支持本地 stdio MCP 服务的客户端,配置如下:
{
"mcpServers": {
"astromei-rokuyo": {
"command": "node",
"args": ["/absolute/path/to/rokuyo-mcp/dist/stdio.js"]
}
}
}
请务必将路径替换为实际检出目录的绝对路径。若桌面客户端未继承 shell 的 Node 安装环境,command 字段需填写 Node 可执行文件的完整路径,否则会出现 stdio 握手失败。
配置生效后,你可以直接向客户端提问:“列出 2026 年 11 月的大安日期。”客户端会调用 find_rokuyo_dates 并返回结构化结果,而不是让模型在散文里凭空编造日期。这正是 MCP 工具调用的核心价值:把确定性计算交给确定性代码。
三、历法内核的确定性边界与排错指南
3.1 公式很小,农历转换才是难点
六曜标签的计算本身只有一行:labels[(lunarMonth + lunarDay - 2) % 6]。真正困难的是判断输入公历日期对应哪个农历月日。新月边界上的一天之差就会改变标签。例如当前引擎返回:2026-10-10 对应农历 8/30、标签先勝;2026-10-11 对应农历 9/1、标签先負。
该库使用 MIT 许可的 korean-lunar-calendar,基于 KASI 的 UTC+9 历法,遵循 Astromei 日历的约定。它并非日本官方日历,也不应假设韩国与日本历法约定在所有历史或未来年份完全一致。若替换为 UTC+8 的农历库,新月午夜附近的结果可能改变。这就是库显式声明转换来源并限制支持窗口的原因。
初始支持窗口为 2025-01-01 至 2027-12-31,这是 API 契约的一部分,不是外推邀请。非法日期或窗口外日期会抛出 RangeError;区间搜索包含两端点且最多 366 天。生产集成必须像声明时区一样显式声明历法约定。
3.2 常见故障与排错路径
| 故障现象 | 根因定位 | 处置方案 | 验证方式 |
|---|---|---|---|
| stdio 握手超时 | 客户端未继承 Node 环境 | 配置 Node 绝对路径 | npm test 通过 |
| RangeError 抛出 | 日期越界或格式错误 | 校验 YYYY-MM-DD 与窗口 | 边界用例测试 |
| 标签与预期不符 | 农历库时区约定差异 | 锁定 korean-lunar-calendar | 新月边界回归 |
| 安装构建失败 | Git 依赖拉取受限 | 预置依赖缓存或镜像 | npm ci 复现 |
点击展开:测试套件执行与备用验证命令
# 运行完整测试:日期校验、有界搜索、新月边界、MCP stdio 握手与工具调用 npm test # 单独验证 stdio 适配器可启动 node dist/stdio.js --help
四、架构升华:计算与解释分离的工程哲学
该项目将代码分为两层:astromei-core 负责历法计算,不依赖 MCP 或 AI;rokuyo-mcp 负责协议工具与兼容的 JavaScript 导出。仓库包含日期校验、有界搜索、新月午夜边界,以及真实 MCP stdio 握手与工具调用的测试。
模型可以帮助解释返回的标签,但日期计算必须留在确定性层。文化解释同理:描述一种传统,不应把它变成对事件结果的保证。这一原则对任何 Rokuyo MCP 离线部署的生产集成都是硬约束——把可审计的计算与不可控的生成严格隔离,才是智能体工具链长期可维护的根基。源码采用 MIT 许可,若想在集成前检查日期行为,浏览器日历是另一个入口。
本文核心技术背景源自海外一线技术研究:
Building an offline Rokuyo calendar MCP server in Node.js (Astromei / DEV Community)
