Skip to main content
Glama
HushHarbor

Time Ledger MCP

by HushHarbor
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

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

Requirements

  • Node.js 18 or newer

  • An MCP-compatible client

Related MCP server: @sflens/mcp

Install

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:

{
  "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

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.

Available Tools

3 tools
helpFormat referenceB

Return the complete ledger JSON format, axis rules, and display behavior. Pass language: zh for the Chinese version.

NameRequiredDescriptionDefault
languageNoHelp language; defaults to English.

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral-disclosure burden. It implies a read-only reference return and lists the content categories, but it does not explicitly confirm that the operation has no side effects or describe the response structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted language. The primary purpose is front-loaded, and the language option follows as a secondary usage detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple help/reference tool with one optional parameter and no output schema, the description gives enough context to invoke it correctly. The main remaining gap is the absence of an explicit read-only/no-side-effect statement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, and the single parameter is already fully documented with an enum. The description reinforces that language: zh selects Chinese, but it adds little beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: it returns the complete ledger JSON format, axis rules, and display behavior. That is more specific than the tool title or name alone. However, it does not explicitly differentiate this reference tool from the sibling tools show and open.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to request Chinese output but gives no guidance on when to use this tool instead of show or open. There are no stated exclusions, prerequisites, or alternative-selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openOpen pageA

Open the local ledger page in the system browser. The page polls for the latest show result.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does disclose useful behavior beyond the name — a real browser is launched and the page self-updates by polling the latest show result — but it omits whether the call blocks, what it returns (URL? handle?), and what happens if no browser is available.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, action stated first, with the polling detail front-loaded as the one behavior an agent needs to know. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema utility the description is close to sufficient, but with no annotations it should still note whether the call is side-effecting only (launching a browser) and whether it returns anything an agent can act on.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly says nothing about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (open) plus resource (the local ledger page) and where it opens (the system browser). It is distinguishable from `show`/`help` only indirectly, via the mention that the page polls for the latest *show* result, so sibling differentiation is implied rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: reach for this when you want the live-updating view in a browser rather than terminal output. However, it never explicitly says when to prefer this over the sibling `show` tool, nor any precondition such as a running local ledger server.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

NameRequiredDescriptionDefault
ledgerYesA ledger object, JSON file path, or JSON text.

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With zero annotations the description carries the whole burden, and it discloses the key traits: it replaces the in-memory cache (state-destroying), never writes to disk, and resolves relative paths against the server process working directory. It stops short of stating what happens to the existing cache on a failed load, or what the call returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the action and its side effect, then the accepted input forms. Every clause contributes information and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no annotations and no output schema, the description covers the operation, its state impact, its persistence profile, and input resolution. The notable remaining gap is error behavior when the ledger is invalid, since a failure mode matters when the cache is being replaced.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the accepted forms at 100% coverage, so the description's restatement of 'object, JSON file path, or JSON text' is redundant. It still earns above baseline by adding genuinely new semantics: relative paths resolve against the server process working directory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Load a ledger') plus the side effect ('replace the in-memory cache'), which is far clearer than the ambiguous name 'show'. It never mentions the sibling 'open', so an agent cannot tell from the text alone which of the two to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this versus 'open' or 'help', and no exclusion conditions. The only implied usage cue is the note that it replaces the cache, which hints at a heavier operation but never states a decision rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedhelp
    • First observedopen
    • First observedshow
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness2/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MASA

    prismatic7
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides 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

  • @sflens/mcp

    jcd1991
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides local, read-only Salesforce debug log analysis via MCP, including listing, searching, summarizing, analyzing, comparing logs, generating reproduction checklists, and exporting incident bundles.
    MIT

  • provmcp

    AbhiAdhikari
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables provenance capture and replay verification for scientific MCP tool calls, using a signed hash-chained ledger and data-source release resolution.
    MIT

  • git-graph

    anthonyfong100
    A
    license
    B
    quality
    C
    maintenance
    Enables 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.
    2
    MIT