Shikamaru: Day-Count and Accrued Interest Engine

shikamaru

提供可验证正确的计日、节假日日历、工作日和付款计划计算。这是一个小巧、依赖精简的 TypeScript 库和 MCP 服务，让 AI Agent 能准确获取日期或数字，而不是靠猜测。

为什么需要它

大模型在日期和金额计算上并不可靠：它们可能选错计日惯例、漏掉市场假日，也可能算错应计利息。shikamaru 以确定性方式完成计算，并通过公开的参考值验证结果。不要让模型猜测你的利息应计或结算日期。

功能

• 根据七种市场惯例计算两个日期之间的计日分数：30/360、30E/360、30E/360 ISDA、ACT/360、ACT/365F、ACT/ACT ISDA、ACT/ACT ICMA（含参考期间和首尾不完整期间分解）。
• 计算简单应计利息：名义金额 x 利率 x 计日分数。
• 将节假日日历定义为代码规则，无需数据源：us-federal、nyse、sifma-us、target、uk。
• 工作日计算：是否为工作日、下一个／上一个工作日、ISDA 调整惯例（顺延、经调整的顺延、提前、经调整的提前）、T+N 结算。
• 付款计划：月度至年度频率，向前或向后滚动，短周期或长周期首尾不完整期间，月末规则，以及每期未调整和调整后的日期。
• 所有功能均可通过库和 MCP 服务使用。
• 每个 MCP 工具都标注为只读，并在纯文本结果之外返回结构化输出（符合输出架构的类型化 JSON），因此 Agent 客户端无需解析文本即可获取数值。

日历维护约定

日历由已发布的规则和一份简短的历史临时关闭日期表组成，内容截至当前版本。规则可生成任意未来日期的正确结果；临时关闭日期（如哀悼日或宣布增加的假日）会在公布后添加，并随补丁版本发布。定时 CI 任务每周都会将所有日历与最新的 QuantLib 进行重新核对，以便及时发现偏差，而非事后才察觉。

安装

npm install @jayofemi/shikamaru

库的用法

import {
	accruedInterest, addBusinessDays, adjustDate, dayCountFraction,
	generateSchedule, isBusinessDay,
} from "@jayofemi/shikamaru";

dayCountFraction("2003-11-01", "2004-05-01", "ACT/ACT ISDA"); // 0.4977...
accruedInterest({
	notional: 1_000_000,
	rate: 0.05,
	start: "2024-01-01",
	end: "2024-04-01",
	convention: "ACT/365F",
});

isBusinessDay("2024-06-19", "nyse"); // false (Juneteenth)
adjustDate("2024-03-29", "modified-following", "target"); // "2024-03-28" (Good Friday, stays in March)
addBusinessDays("2024-07-02", 2, "us-federal"); // "2024-07-05" (T+2 over July 4th)

generateSchedule({
	effective: "2024-01-15",
	termination: "2026-01-15",
	frequency: "semiannual",
	calendar: "target",
}); // four periods with unadjusted and adjusted dates

日期必须采用严格的 ISO 格式 YYYY-MM-DD。利率为年化小数（0.05 = 5%）。

MCP 服务

从源码启动（本地开发）：

npm install
npm run build
node dist/cli.js

也可以直接启动已发布的软件包：

npx @jayofemi/shikamaru

通过 stdio 将任意 MCP 客户端（Claude Desktop、IDE 等）连接到该命令。

Claude Code 用户也可以将其安装为插件，自动注册 MCP 服务：

/plugin marketplace add JayOfemi/shikamaru
/plugin install shikamaru@shikamaru

验证 MCP 服务

测试套件会在内存中端到端测试该服务，涵盖工具列表、只读标注、针对每种输出架构的结构化输出，以及对每个工具的调用。如需交互式检查，请使用官方 MCP Inspector：

npm run build
npx @modelcontextprotocol/inspector node dist/cli.js

它会打开本地 UI，通过 stdio 连接，列出工具并允许你调用它们。快速验证：使用开始日期 2003-11-01、结束日期 2004-05-01 和惯例 ACT/ACT ISDA 调用 day_count_fraction，返回值约为 0.4977。

正确性

约定遵循 ISDA 2006 定义；日历遵循其发布来源（OPM、NYSE 规则、SIFMA 建议、ECB TARGET 规则、gov.uk 公告）。测试套件会检查已发布的参考向量（ISDA 示例、官方假日列表、OpenGamma 约定指南）、属性检查，以及与事实标准 QuantLib 的差异测试：计日分数、跨数十年的各日历完整假日列表、营业日调整和递进、逐日对比的计划表，以及包含短首尾期的 ACT/ACT ICMA 分数。

要（重新）生成 QuantLib 测试集（需要 Python + pip）：

pip install QuantLib
npm run vectors

这会写入 test/vectors/quantlib.json 和 test/vectors/quantlib-calendar.json（两者都要提交）。随后，npm test 会将 shikamaru 与每个 QuantLib 值进行检查。CI 会在每次推送时以及每周定期任务（漂移监控）中，使用最新的 QuantLib 重新生成测试集，因此即使仓库没有变动，现实中的日历变更也会触发失败运行。这就是产品的证明。

开发

npm install
npm run build
npm test

许可证

MIT。版权所有 (c) 2026 Jay Ofemi。