Hybrid Recursive Ladder MCP

Aggregate long time-series ranges with a handful of source requests instead of one per bucket.

An MCP server (stdio) for the Hybrid Recursive Ladder query planner. It splits a time range into complete calendar units — month, day, hour, minute — and reads each level once, so a ten-month range costs about five to seven source requests instead of 423,049 per-minute buckets.

Works with no configuration: the server exposes deterministic demo data, so every tool answers immediately. Point it at ThingsBoard or PostgreSQL when you have real data.

Install

uvx hybrid-recursive-ladder-mcp

or, with pip:

pip install hybrid-recursive-ladder-mcp
hybrid-recursive-ladder-mcp

Client configuration

{
  "mcpServers": {
    "hybrid-recursive-ladder": {
      "command": "uvx",
      "args": ["hybrid-recursive-ladder-mcp"]
    }
  }
}

Tools

All four are annotated: ladder_meta and ladder_decompose are local and side-effect free, ladder_sum can write through materialize=True, and ladder_verify reaches the source.

Configuration

Set these as environment variables in the client config. All are optional.

When not to use it

The tool computes sums only in this version. It does not do averages (needs weighted sum plus count), meter deltas, or non-additive metrics, and it needs a source that supports interval aggregation.

Links

• Repository and full docs: https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm
• Algorithm specification: https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm/blob/main/docs/algorithm.md
• Benchmarks: https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm/blob/main/docs/benchmarks.md
• Project site: https://magicsquarekey.github.io/hybrid_recursive_ladder_algorithm/
• License: MIT