tslab-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

uv sync --all-groups                      # set up (installs ~291 packages, ~2.3 GB)
uv run pytest                             # fast suite (~1.5s); excludes `slow` via addopts
uv run pytest -m slow                     # exercises TimeCopilot (~3.5 min, no weight downloads)
uv run pytest -m ''                       # everything
uv run pytest tests/test_features.py::test_acf1_within_bounds   # single test
uv run ruff check src tests
uv run mypy                               # strict on src/; first cold run takes ~10 min
uv build

Verify the wire protocol, not just the functions — a tool can pass its unit test and still fail a client handshake:

npx @modelcontextprotocol/inspector uv run tslab-mcp

What this is

An MCP server exposing deterministic time-series forecasting. The session driving the tools is the reasoning engine; this package computes numbers and never calls an LLM.

Two backends, chosen automatically in backends.select():

• statsforecast (core, always installed) runs the eleven statistical models. ~340 MB, no torch.
• TimeCopilot (optional foundation extra) runs the pretrained models and Prophet. ~2 GB, and only reached when a request names one of its models.

A request whose models are all statistical never touches TimeCopilot. A mixed request goes entirely to TimeCopilot, which carries the statistical models too — letting it merge the frames avoids reimplementing an upstream join.

Architecture

Four invariants drive nearly every design decision. Breaking one looks locally harmless and is not.

Handles, not dataframes. Panels live in registry.py's module-level _STORE, keyed by a short handle. Tools take the handle and return summaries, aggregates, and file paths. A CV frame is n_series × h × n_windows × n_models rows — serialising one into a tool result exhausts the session's context on the first call. Every bulk return path is capped by a schema-enforced maximum and reports truncated plus the omitted count.