内容
# 忍者神龟
[](https://github.com/JayOfemi/shikamaru/actions/workflows/ci.yml)
可证明正确的天数计算、假日日历、工作日和付款计划计算。一个小型、依赖轻量的TypeScript库和MCP服务器，允许AI代理获取确切的日期或数字，而不是猜测。
## 为什么
大型语言模型在日期和货币数学方面不可靠：它们选择错误的天数计算约定，忘记市场假日，错误计算累积利息。忍者神龟确定性地执行这些计算，并根据已发布的参考值证明其正确性。不要让模型猜测您的利息累积或结算日期。
## 功能
- 七种市场惯例下的两个日期之间的天数分数：30/360、30E/360、30E/360 ISDA、ACT/360、ACT/365F、ACT/ACT ISDA、ACT/ACT ICMA（带有参考期和stub分解）。
- 简单的累积利息：本金 x 利率 x 天数分数。
- 代码中的假日日历规则，无需数据馈送：`us-federal`、`nyse`、`sifma-us`、`target`、`uk`。
- 工作日数学：是否为工作日、下一个/上一个、ISDA调整约定（后续、修正后续、前序、修正前序）、T+N结算。
- 付款计划：每月至每年、向后或向前滚动、短或长stub、月底规则、每期未调整和调整日期。
- 所有功能都作为库和MCP服务器公开。
### 日历维护合同
日历是已发布的规则加上历史一次性关闭的短固定表，当前版本即时生效。规则生成任意远的未来正确日期；一次性关闭（哀悼日、宣布的额外假日）会在宣布后添加，并在补丁版本中发布。计划的CI运行会针对最新的QuantLib每周检查每个日历，以检测漂移，而不是发现漂移。
## 安装
```bash
npm install @jayofemi/shikamaru
```
## 库使用
```typescript
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服务器 [](https://glama.ai/mcp/servers/JayOfemi/shikamaru)
[](https://glama.ai/mcp/servers/JayOfemi/shikamaru)
从源代码（本地开发）：
```bash
npm install
npm run build
node dist/server.js
```
一旦发布，MCP客户端可以直接启动：
```bash
npx @jayofemi/shikamaru
```
将任何MCP客户端（Claude Desktop、IDE等）指向该命令的标准输入/输出。
## 验证MCP服务器
测试忍者神龟服务器的标准方法是使用官方MCP检查器。单元测试涵盖库；检查器涵盖服务器层，它们不涉及的测试。
```bash
npm run build
npx @modelcontextprotocol/inspector node dist/server.js
```
它打开一个本地UI，通过标准输入/输出连接，列出工具，并允许您调用它们。健全检查：`day_count_fraction`，起始日期 `2003-11-01`，结束日期 `2004-05-01`，约定 `ACT/ACT ISDA` 返回约 0.4977。
## 正确性
约定遵循ISDA 2006定义；日历遵循其发布的来源（OPM、NYSE规则、SIFMA建议、ECB TARGET规则、gov.uk公告）。测试套件检查已发布的参考向量（ISDA示例、官方假日列表、OpenGamma约定指南）、属性检查和与QuantLib的微分电池，QuantLib是事实上的参考：天数分数、每个日历的完整假日列表、跨越数十年的业务日调整和推进、计划比较日期和ACT/ACT ICMA分数，包括stub。
要（重新）生成QuantLib电池（需要Python + pip）：
```bash
pip install QuantLib
npm run vectors
```
这会写入 `test/vectors/quantlib.json` 和 `test/vectors/quantlib-calendar.json`（提交两者）。然后 `npm test` 会检查忍者神龟与每个QuantLib值的匹配情况。CI从最新的QuantLib重新生成电池，并在每次推送和每周计划（漂移看门狗）时执行此操作，因此实际日历更改会以红色运行显示，即使存储库处于静止状态。证明是产品。
## 开发
```bash
npm install
npm run build
npm test
```
## 许可证
MIT。版权所有（c）2026 Jay Ofemi。
