Time Ledger MCP
# Time Ledger MCP
Time Ledger is a Model Context Protocol (MCP) server that displays a ledger as a numeric timeline with tracks and overlapping blocks. Move the cursor across the timeline to inspect matching block details.
The server keeps only the latest ledger in memory. It does not write ledger data to disk, and the cache is cleared when the server exits.
[Chinese](./README.zh-CN.md)
## Requirements
- Node.js 18 or newer
- An MCP-compatible client
## Install
```powershell
npm install
```
Add the server to an MCP client. For a global VS Code installation, add it to the user-level `mcp.json`; use an absolute path to this repository:
```json
{
"servers": {
"time-ledger": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/time-ledger-mcp/src/server.js"]
}
}
}
```
VS Code manages the stdio process. It starts the server when needed and stops it when the client closes.
## Tools
| Tool | Purpose |
| --- | --- |
| `show` | Load a ledger, replace the in-memory cache, and return the local page URL. Accepts an object, a JSON file path, or JSON text. |
| `open` | Open the local page in the system browser. |
| `help` | Return the authoritative data format and display rules. English is the default; pass `{"language":"zh"}` for Chinese. |
Use the `help` tool before creating or transforming ledger JSON. It is the canonical format reference.
Example prompt:
> Use the `time-ledger` MCP `help` tool to learn the current ledger format. Then create `ledgers/daily-ledger.json` in this workspace, following the returned rules, and load it with `time-ledger.show`.
When `show` receives a file path, relative paths are resolved from the server process working directory. Use an absolute path if the client starts the server from an unknown directory.
## Local development
```powershell
npm test
npm run serve
npm run serve -- examples/example.json
```
`npm test` checks the MCP tools, both help languages, file and object loading, validation errors, 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`, 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](./LICENSE).
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.