Time Ledger MCP
You can load structured ledgers and inspect them as interactive, locally served timelines.
Load ledgers (
show): Accepts a ledger object, JSON file path, or JSON text, replaces the in-memory cache, and returns a local page URL. Data is never written to disk.Open the timeline (
open): Opens the local ledger page in your system browser. The page polls for the latestshowresult.Get format guidance (
help): Returns the authoritative ledger JSON format, axis rules, and display behavior in English or Chinese.Explore timeline details: Move the cursor to inspect values active at each point, using numeric/sequence axes or date-labeled numeric axes.
Compose reusable content: Uses globally unique IDs and track-based composition with override, merge, array replacement, intersection, and cycle rejection rules.
Customize the page UI: Switch between English/Chinese and Auto/Light/Dark appearance; preferences are saved in browser localStorage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Time Ledger MCP show examples/example.json and open it in the browser"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Time Ledger MCP
Time Ledger MCP turns structured ledgers into interactive timelines. Load a ledger with show, then move the cursor to inspect the details active at each point.
The server keeps only the most recently loaded ledger in memory. It does not write ledger data to disk, and the cache is cleared when the server exits.
Screenshots
Sequence-number axis

Date-labeled numeric axis

Nested ID composition

Related MCP server: @sflens/mcp
Requirements
Node.js 18 or newer
An MCP-compatible client
Install
Install the dependencies from the repository directory:
npm installTo use the server globally in VS Code, add it to the user-level mcp.json. Replace the example path with the absolute path to this repository:
{
"servers": {
"time-ledger": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/time-ledger-mcp/src/server.js"]
}
}
}VS Code starts the stdio server when needed and manages its lifetime with the client.
Tools
Tool | What it does |
| Loads a ledger, replaces the in-memory cache, and returns the local page URL. The input can be a ledger object, a JSON file path, or JSON text. |
| Opens the local page in the system browser. |
| Explains the ledger format and display behavior. English is the default; pass |
First use
Call
help(orhelpwith{"language":"zh"}) before creating or changing ledger JSON. It is the authoritative format reference.Choose a sample such as
examples/sequence-ledger.json,examples/date-ledger.json, orexamples/example.json.Call
showwith the file path. Use an absolute path if the MCP server's working directory is unknown.Call
opento display the page, then click or drag the timeline. Use the left/right arrow keys to fine-tune the cursor.
The page defaults to English and Auto appearance. Use the header selectors to switch to Chinese or force Light/Dark. Both choices are saved in browser localStorage for that page origin. Auto follows the operating system's color-scheme changes. This translates interface text only; ledger content remains unchanged.
Sequence and date axes
The axis is always numeric. For sequence-based data, use meaningful numbers such as steps or frames and set axis.label accordingly. For dates, convert dates to numeric UTC epoch days or seconds and provide human-readable date labels in axis.ticks; dates in start and end are not parsed automatically. See examples/date-ledger.json for an epoch-day example. Its cursor and detail ranges intentionally remain numeric.
Global ID composition
The distinctive feature is reusable content composed through globally unique IDs:
A track represents an item. Its base block uses the same ID as the track.
A block on another track can use that ID to reference the item during its interval.
Different block IDs on a source track form ordered sub-tracks. Higher sub-tracks override conflicting fields; nested objects merge and arrays replace as a whole.
The source track is composed locally before references are resolved recursively. A referenced composition applies only to the time intersection, and cycles are rejected.
The first reference to an ID without a track initializes that track from the reference block. Later references do not copy new blocks; add further source blocks explicitly. Open examples/example.json and move the cursor into the lighting interval to see the composed values and per-field source labels.
Example prompt:
Call the
time-ledgerMCPhelptool to learn the current format. Then createledgers/daily-ledger.jsonin this workspace using those rules, and load it withtime-ledger.show.
When show receives a file path, relative paths are resolved from the server process's working directory. Use an absolute path when that directory is unknown.
Local development
npm test
npm run serve
npm run serve -- examples/example.json
npm run serve -- examples/sequence-ledger.json
npm run serve -- examples/date-ledger.jsonnpm test checks the MCP tools, both help languages, ID-based composition, initialization, cycle and overlap validation, file and object loading, the page, and the ledger API. npm run serve previews the example ledger without an MCP client; press Ctrl+C to stop it.
The page server listens on 127.0.0.1. It starts at port 7317 and tries up to 20 consecutive ports. Set LEDGER_PORT to choose another starting port.
License
This project is licensed under the Apache License, Version 2.0. See LICENSE.
Available Tools
3 toolshelpFormat referenceB
Return the complete ledger JSON format, axis rules, and display behavior. Pass language: zh for the Chinese version.
Inputs: language.
openOpen pageA
Open the local ledger page in the system browser. The page polls for the latest show result.
Inputs: no named parameters.
showLoad ledgerA
Load a ledger and replace the in-memory cache. Data is never written to disk. ledger may be an object, a JSON file path, or JSON text; relative paths use the server process working directory.
Inputs: ledger (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have distinguishable purposes: show loads ledger data into memory, open launches a browser view, and help returns format documentation. show and open are adjacent (both surface ledger content) and could momentarily be confused, but the descriptions make the boundary clear enough.
All three names are single lowercase verbs (show, open, help) following a consistent pattern with no camelCase/snake_case mixing. They deviate from a verb_noun convention and are generic verbs that only make sense in context, but they are internally consistent.
Three tools is small but each earns its place for what is essentially a ledger viewer: load, render, and document. It sits at the low end of the comfortable range without obviously missing a sibling tool within its stated display-only scope.
The surface covers only reading and rendering a ledger; there is no way to add, update, delete, or query time entries, nor to compute totals or filter by date range. For a 'Time Ledger' domain this leaves the core authoring and querying lifecycle entirely to external editing, which will cause agent dead ends.
Related MCP Connectors
Read your Golem fleet's ledger from any MCP client: agents' sessions, live activity, signed record.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Create, validate, edit, export (markdown/svg/png/mermaid), and search JSON Canvas files.
Host any HTTP API as MCP tools with a tamper-evident cross-agent settlement ledger.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides a local, read-oriented MCP server for the MASA protocol, enabling offline validation, inspection, lineage tracing, public-export audit, and processing-request planning for sound-matter records.MIT
- AlicenseNot gradedqualityBmaintenanceProvides local, read-only Salesforce debug log analysis via MCP, including listing, searching, summarizing, analyzing, comparing logs, generating reproduction checklists, and exporting incident bundles.MIT
- AlicenseNot gradedqualityCmaintenanceEnables provenance capture and replay verification for scientific MCP tool calls, using a signed hash-chained ledger and data-source release resolution.MIT
- AlicenseBqualityCmaintenanceEnables users to explore a local repository’s commit history through read-only MCP tools, including branch lanes, merge edges, branch selection, search highlighting, commit metadata, file statistics, and bounded patches.2MIT