shikamaru

shikamaru

日数計算、休日カレンダー、営業日、支払スケジュールの計算を、証明可能な正確さで実行します。依存関係を抑えた小規模な TypeScript ライブラリ兼 MCP サーバーです。AI エージェントが推測せずに、正確な日付や数値を取得できます。

その理由

LLM は日付や金額の計算が不正確です。誤った日数計算規則を選んだり、市場の休日を忘れたり、経過利息の計算を誤ったりします。shikamaru は決定論的に計算し、公表された参照値との照合によって正しさを証明します。利息計算や決済日をモデルに推測させないでください。

できること

• 7 種類の市場慣行に基づく 2 つの日付間の日数計算比率：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）を返します。これにより、エージェントのクライアントはテキストを解析せずに数値を利用できます。

カレンダーの保守方針

カレンダーは公表済みのルールと、現行バージョン時点で確定した過去の臨時休業日の短い一覧を組み合わせたものです。ルールによって、どれだけ先の日付でも正しい日付を生成します。追悼日や臨時祝日などの臨時休業日は、発表され次第追加し、パッチリリースで提供します。スケジュールされた 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

任意の MCP クライアント（Claude Desktop、IDE など）から、stdio 経由でこのコマンドを指定してください。

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 Definitionsに準拠し、カレンダーは公表元（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。Copyright (c) 2026 Jay Ofemi.