Shikamaru: Day-Count and Accrued Interest Engine

by JayOfemi

261 downloads

Not rated

GitHub

About

Provably correct day-count and accrued-interest calculations. A small, dependency-light TypeScript library and an MCP server, so an AI agent can get the exact number instead of guessing.

Details

Author: JayOfemi
Downloads: 261
Categories: Other, Finance

- Day-count fraction under seven market conventions (30/360, ACT/360, etc.)
- Simple accrued interest: notional × rate × day-count fraction
- Holiday calendars: us-federal, nyse, sifma-us, target, uk
- Business-day math: is-business-day, next/previous, ISDA adjustments, T+N settlement
- Payment schedules: monthly to annual, backward or forward roll, short/long stubs
- Continuous correctness verification against QuantLib via CI

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Shikamaru: Day-Count and Accrued Interest Engine

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

From the repository

Install the npm package (npm install @jayofemi/shikamaru), then build and run the MCP server from source (npm run build && node dist/server.js) or launch it directly via npx @jayofemi/shikamaru. Any MCP client (Claude Desktop, IDE, etc.) can connect over stdio.

`day_count_fraction`

Exact day-count fraction between two dates under a market convention. Dates are ISO YYYY-MM-DD. For ACT/ACT ICMA also pass frequency (coupons per year) and, for stub periods, the reference period boundaries. Deterministic; do not estimate this with a model.

`accrued_interest`

Exact simple accrued interest (notional * rate * day-count fraction) between two dates. Dates are ISO YYYY-MM-DD; rate is the annual rate as a decimal (0.05 = 5%). Deterministic.

`list_conventions`

List the supported day-count conventions.

`is_business_day`

Whether a date is a business day under a holiday calendar, with the reason when it is not (weekend or holiday). Calendars are rules in code (no stale data feed). Deterministic; do not let a model guess market holidays.

`adjust_date`

Adjust a date to a business day under an ISDA convention and holiday calendar. Business days pass through unchanged. modified-following falls back to preceding rather than leave the month (the bond-market default). Deterministic.

`add_business_days`

Move a signed number of business days under a holiday calendar (settlement math: T+2 is count 2). Zero returns the date unchanged. Deterministic.

`generate_schedule`

Generate coupon/payment accrual periods between an effective and a termination date: monthly to annual frequency, backward or forward roll, short or long stub, optional end-of-month rule, business-day adjustment per calendar. Returns each period's unadjusted and adjusted start and end. This is where hand-rolled date code goes wrong; do not approximate it.

`list_calendars`

List the supported holiday calendars with a one-line description of each.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "shikamaru: day-count and accrued interest engine": {
            "shikamaru": {
                "command": "npx",
                "args": [
                    "-y",
                    "--package=@jayofemi/shikamaru",
                    "shikamaru-mcp"
                ]
            }
        }
    }
}

McpServers

{
    "shikamaru": {
        "command": "npx",
        "args": [
            "-y",
            "--package=@jayofemi/shikamaru",
            "shikamaru-mcp"
        ]
    }
}

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.

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

ts
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/server.js



Once published, an MCP client can launch it directly:


npx @jayofemi/shikamaru



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

Verify the MCP server


The standard way to test shikamaru's server is the official MCP Inspector. The unit tests cover the library; the Inspector covers the server layer they do not touch.


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



It opens a local UI, connects over stdio, lists the tools, and lets you call them. Sanity check:

day_count_fraction with start 2003-11-01, end 2004-05-01, convention ACT/ACT ISDA

 returns about 0.4977.

Correctness


Conventions follow the ISDA 2006 definitions; calendars follow their published sources (OPM, NYSE rules, SIFMA recommendations, ECB TARGET rules, gov.uk proclamations). The test suite checks published reference vectors (ISDA worked examples, official holiday lists, the OpenGamma conventions guide), property checks, and differential batteries against QuantLib, the de-facto reference: day-count fractions, full per-calendar holiday lists across decades, business-day adjustment and advancing, schedules compared date by date, and ACT/ACT ICMA fractions including stubs.

To (re)generate the QuantLib batteries (needs Python + pip):


pip install QuantLib
npm run vectors



This writes

test/vectors/quantlib.json and test/vectors/quantlib-calendar.json (commit both). npm test

 then checks shikamaru against every QuantLib value. CI regenerates the batteries from the latest QuantLib on every push AND on a weekly schedule (the drift watchdog), so a real-world calendar change surfaces as a red run even when the repo is quiet. The proof is the product.

Develop


npm install
npm run build
npm test

License

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

day_count_fraction

accrued_interest

list_conventions

is_business_day

adjust_date

add_business_days

generate_schedule

list_calendars

Claude Desktop / Cursor

McpServers

Shikamaru

Why

What it does

Calendar maintenance contract

Install

Library usage

MCP server

Verify the MCP server

Correctness

Develop

License

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀

`day_count_fraction`

`accrued_interest`

`list_conventions`

`is_business_day`

`adjust_date`

`add_business_days`

`generate_schedule`

`list_calendars`