Shikamaru MCP server

shikamaru

Provably correct day-count, holiday-calendar, business-day, and payment-schedule calculations. A small, dependency-light TypeScript library and an MCP server, so an AI agent can get the exact date or number instead of guessing.

Why

LLMs are unreliable at date and money math: they pick the wrong day-count convention, forget market holidays, and miscompute accrued interest. shikamaru does it deterministically and proves it against published reference values. Do not let a model guess your interest accrual or your settlement date.

What it does

• Day-count fraction between two dates under seven market conventions: 30/360, 30E/360, 30E/360 ISDA, ACT/360, ACT/365F, ACT/ACT ISDA, ACT/ACT ICMA (with reference periods and stub decomposition).
• Simple accrued interest: notional x rate x day-count fraction.
• Holiday calendars as rules in code, no data feed: us-federal, nyse, sifma-us, target, uk.
• Business-day math: is-business-day, next/previous, ISDA adjustment conventions (following, modified-following, preceding, modified-preceding), T+N settlement.
• Payment schedules: monthly to annual, backward or forward roll, short or long stubs, end-of-month rule, per-period unadjusted and adjusted dates.
• All of it exposed as a library and as an MCP server.
• Every MCP tool is annotated read-only and returns structured output (typed JSON under an output schema) alongside the plain-text result, so an agent client can consume the numbers without parsing text.

Calendar maintenance contract

Calendars are published rules plus a short pinned table of historical one-off closures, current as of this version. Rules generate correct dates arbitrarily far forward; one-off closures (a mourning day, a proclaimed extra holiday) are added when announced and ship in a patch release. A scheduled CI run re-checks every calendar against the latest QuantLib weekly, so drift is detected, not discovered.

Install

npm install @jayofemi/shikamaru

Library usage

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

Dates are strict ISO YYYY-MM-DD. Rate is an annual decimal (0.05 = 5%).

MCP server

From source (local dev):

npm install
npm run build
node dist/cli.js

Or launch the published package directly:

npx @jayofemi/shikamaru

Point any MCP client (Claude Desktop, an IDE, etc.) at that command over stdio.

Claude Code users can also install it as a plugin, which registers the MCP server automatically:

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

Verify the MCP server

The test suite exercises the server end to end in memory, covering tool listing, read-only annotations, structured output against each output schema, and a call to every tool. For an interactive check, use the official MCP Inspector:

Shortened. The full README is on GitHub.