tslab-mcp

Ein MCP-Server, der deterministische Zeitreihenprognosen als Werkzeuge bereitstellt, sodass Ihr Agent die Denkmaschine ist und jede Zahl aus gewöhnlichem, reproduzierbarem Python stammt.

In diesem Paket wird kein LLM aufgerufen. Es ist kein API-Schlüssel erforderlich (es sei denn, Sie fragen nach TimeGPT, das die Nixtla-API aufruft).

Warum

Einige Prognosebibliotheken liefern einen Agenten mit, der Merkmale liest, ein Modell auswählt und das Ergebnis mit einem LLM im Kreislauf erklärt. Wenn Sie einen solchen von Ihrem eigenen Agenten aus aufrufen, verschachteln Sie einen Agenten in einem anderen – zwei Prompts, zwei Rechnungen, zwei Quellen für Nichtdeterminismus und eine undurchsichtige Zwischenschicht, die die Begründung der Modellauswahl nicht überprüfbar macht.

Hier ist die Kontrolle also umgekehrt: Die Prognosebibliothek ist das Werkzeug, und Ihr Agent ist derjenige, der denkt. Er liest die Merkmale, argumentiert für eine Modellfamilie, validiert die Kandidaten kreuzweise und schreibt die Begründung in ein Manifest. Jede Zahl auf dem Weg wird durch einen Bibliotheksaufruf erzeugt, den Sie ohne LLM im Pfad erneut ausführen können.

Diese Trennung setzt sich in der Art und Weise fort, wie das Paket selbst aufgebaut ist. Die Basisinstallation führt elf statistische Modelle aus – AutoARIMA, AutoETS, Theta, CrostonClassic und weitere – über statsforecast: etwa 340 MB, kein PyTorch, und es startet in Sekunden. Ein optionales foundation-Extra fügt die vortrainierten Modelle von TimeCopilot hinzu – Chronos, Moirai, TimesFM, TiRex, Toto und andere – sowie Prophet, für den Fall, dass eine statistische Basislinie nicht ausreicht. Eine Anfrage, die nur statistische Modelle nennt, importiert niemals TimeCopilot oder torch; eine Anfrage, die auch nur ein Foundation-Modell nennt, läuft vollständig über TimeCopilot, das auch die statistischen Modelle mit sich führt. In beiden Fällen meldet tsf_list_models, was tatsächlich installiert ist, bevor Sie sich auf ein Modell festlegen.

Related MCP server: forecast-mcp

Installation

Erfordert Python 3.10+ (3.13 empfohlen, siehe Python-Version).

uvx tslab-mcp                     # run without installing
uv tool install tslab-mcp         # or install the CLI

Die Basisinstallation führt die elf statistischen Modelle über statsforecast aus: etwa 340 MB, kein PyTorch, und es startet sofort. Für die vortrainierten Foundation-Modelle – Chronos, Moirai, TimesFM, Toto, TiRex – und Prophet fügen Sie das Extra hinzu:

uvx --from 'tslab-mcp[foundation]' tslab-mcp

Das foundation-Extra zieht TimeCopilot nach sich, das torch, transformers und lightning mitbringt: etwa 2 GB bei der ersten Installation, und der erste Werkzeugaufruf, der darauf zugreift, benötigt etwa 30 Sekunden für den Import. Beides sind einmalige Vorgänge, und keiner ist kostenpflichtig, es sei denn, Sie fragen nach einem Modell, das sie benötigt.

Von GitHub

uv und uvx akzeptieren beide eine Git-URL anstelle eines Paketnamens, was den aktuellen main-Zweig installiert, ohne auf ein Release zu warten:

uvx --from git+https://github.com/pedrobtz/tslab-mcp tslab-mcp
uv tool install git+https://github.com/pedrobtz/tslab-mcp        # or install the CLI

# with the foundation extra
uvx --from 'tslab-mcp[foundation] @ git+https://github.com/pedrobtz/tslab-mcp' tslab-mcp

Fixieren Sie einen Ref für alles andere als beiläufige Tests – der Branch-Head kann sich sonst unter Ihnen bewegen. Ein Commit funktioniert heute; ein Versionstag wird ebenfalls funktionieren, sobald einer erstellt ist:

uv tool install "git+https://github.com/pedrobtz/tslab-mcp@136824c1cc2a"

Aus einem Checkout

git clone https://github.com/pedrobtz/tslab-mcp
cd tslab-mcp
uv sync                              # base
uv sync --extra foundation           # with the pretrained models
uv run tslab-mcp

Konfiguration

Fügen Sie den Server zur Konfiguration Ihres MCP-Clients hinzu. Die Datei unterscheidet sich pro Client – oft .mcp.json im Projektstammverzeichnis – aber der Eintrag selbst hat die gleiche Form:

{
  "mcpServers": {
    "tslab": {
      "command": "uvx",
      "args": ["tslab-mcp"],
      "env": {
        "TSLAB_MCP_HOME": "~/.tslab-mcp"
      }
    }
  }
}

TSLAB_MCP_HOME legt fest, wo Artefakte geschrieben werden; der Standardwert ist ~/.tslab-mcp, und Ausgaben von Läufen landen in <home>/runs.

Der Transport ist nur stdio, aus gutem Grund: Ihre Daten werden als sensibel betrachtet und verlassen niemals die Maschine. Der Server tätigt keine ausgehenden Anfragen, außer den Modellgewichts-Downloads, die TimeCopilot selbst für Foundation-Modelle durchführt, und den Nixtla-API-Aufrufen, die TimeGPT tätigt, wenn Sie explizit danach fragen.

GitHub Copilot

Copilot entdeckt MCP-Server aus einer mcp.json-Datei und stellt ihre Werkzeuge im Agentenmodus zur Verfügung – die Werkzeuge erscheinen nicht im Frage- oder Bearbeitungsmodus.

VS Code. Platzieren Sie den Server in .vscode/mcp.json, um ihn mit dem Repository zu teilen, oder führen Sie MCP: Open User Configuration aus der Befehlspalette aus, um ihn in Ihrem eigenen Profil über alle Arbeitsbereiche hinweg zu behalten. Beachten Sie, dass der Schlüssel servers ist, nicht mcpServers:

{
  "servers": {
    "tslab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tslab-mcp"],
      "env": {
        "TSLAB_MCP_HOME": "${userHome}/.tslab-mcp"
      }
    }
  }
}

Aus einem Checkout heraus verweisen Sie stattdessen auf den Arbeitsbaum:

{
  "servers": {
    "tslab": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "tslab-mcp"]
    }
  }
}

Dann: Öffnen Sie Chat, schalten Sie den Modus-Wähler auf Agent und verwenden Sie die Schaltfläche Tools, um zu bestätigen, dass die acht tsf_*-Werkzeuge aufgelistet und aktiviert sind. MCP: List Servers zeigt den Status des Servers und seine Protokolle an, wo ein fehlgeschlagener Start erklärt wird. Copilot begrenzt, wie viele Werkzeuge gleichzeitig aktiv sein können. Wenn Sie also mehrere MCP-Server betreiben, müssen Sie möglicherweise einige abwählen, um alle acht unterzubringen.

Visual Studio. Gleiche JSON-Form, in .mcp.json im Lösungsstammverzeichnis (oder %USERPROFILE%\.mcp.json für alle Lösungen), dann aktivieren Sie die Werkzeuge aus der Copilot Chat-Agentenmodus-Werkzeugauswahl.

JetBrains, Eclipse und Xcode. Öffnen Sie die Copilot Chat-Agentenmodus-Werkzeugauswahl, wählen Sie Edit MCP configuration und fügen Sie denselben servers-Eintrag zu der geöffneten mcp.json hinzu.

Copilot Coding Agent (der Cloud-Agent auf github.com) ist für diesen Server schlecht geeignet: Er führt Ihre MCP-Server in einer flüchtigen GitHub Actions-Umgebung aus, was bedeutet, dass die etwa 2 GB große TimeCopilot-Installation bei jedem Lauf bezahlt werden muss, und er hat keinen Zugriff auf lokale Datendateien. Verwenden Sie ihn stattdessen von Ihrem Editor aus.

Werkzeuge

Alles außer den beiden tsf_export_*-Werkzeugen ist als schreibgeschützt markiert; nichts hier löscht, daher ist das Bereinigen von ~/.tslab-mcp/runs Ihre Aufgabe, nicht die des Agenten.

Starten einer Sitzung

Die Werkzeuge erzwingen keine Reihenfolge, daher ist der Eröffnungsprompt das, was acht aufrufbare Funktionen in eine Analyse verwandelt. So etwas funktioniert gut:

Verwenden Sie die tslab-Werkzeuge, um die Serie in /Users/me/data/deposits.csv 12 Monate im Voraus zu prognostizieren.

Arbeiten Sie in dieser Reihenfolge und zeigen Sie Ihre Überlegungen bei jedem Schritt:

1. Laden Sie die Datei und sagen Sie mir, was Sie gefunden haben – wie viele Serien, welche Frequenz, etwaige Lücken oder fehlende Werte.

2. Beschreiben Sie die Merkmale und sagen Sie, für welche Modellfamilien sie sprechen und warum.

3. Überprüfen Sie, welche Modelle tatsächlich installiert sind, bevor Sie welche vorschlagen.

4. Validieren Sie Ihre Shortlist gegen eine SeasonalNaive-Baseline über 4 Fenster. Vorerst nur statistische Modelle.

5. Prognostizieren Sie mit dem Gewinner, mit 80%- und 95%-Intervallen.

6. Exportieren Sie ein Laufmanifest und einen HTML-Bericht und setzen Sie die Begründung der Modellauswahl in die Notiz: was Sie gewählt haben, was die Metriktabelle zeigte und was Sie verworfen haben.

Fassen Sie die Ergebnisse zusammen und geben Sie mir die Parquet-Pfade – fügen Sie keine ganzen DataFrames in den Chat ein.

Vier Dinge in diesem Prompt leisten echte Arbeit:

• Ein absoluter Pfad. Relative Pfade werden relativ zum Arbeitsverzeichnis des Servers aufgelöst, das Ihr MCP-Client wählt und das Sie im Allgemeinen nicht vorhersagen können.

• Ein Horizont, der zur Entscheidung passt. h treibt sowohl die Prognose als auch den Umfang der Historie, die jedes CV-Fenster verbraucht; 12 monatliche Schritte sind ein Jahr Planung, kein willkürlicher Standard.

• „Vorerst nur statistische Modelle.“ Ohne diese Einschränkung könnte ein Agent nach einem Foundation-Modell greifen und mehrere Minuten damit verbringen, Gewichte herunterzuladen, um eine Frage zu beantworten, die AutoETS in Sekunden erledigt hätte. Heben Sie die Einschränkung auf, sobald die billigen Modelle eine Untergrenze gesetzt haben.

• Die Begründung in der Manifest-Notiz anfordern. Das Chat-Transkript ist wegwerfbar; das Manifest ist der Teil, den jemand erneut ausführen und prüfen kann. Wenn die Begründung nur in der Konversation existiert, ist sie praktisch verloren.

Kürzere Eröffnungen, wenn Sie wissen, was Sie wollen:

Laden Sie /Users/me/data/sales.parquet und beschreiben Sie die Merkmale. Noch nicht prognostizieren – ich möchte zuerst sehen, womit wir es zu tun haben.

Vergleichen Sie SeasonalNaive, AutoETS und AutoARIMA auf dem geladenen deposits-Handle über 6 Fenster bei h=12 und sagen Sie mir dann, ob etwas die Baseline genug schlägt, um die zusätzliche Komplexität wert zu sein.

Rein statistische Aufrufe antworten in Sekunden. Der erste Aufruf, der ein Foundation-Modell nennt, benötigt etwa 30 Sekunden für den Import von TimeCopilot, bevor er etwas anderes tut – diese Pause ist erwartet, kein Hängen, und sie tritt nur auf, wenn das foundation-Extra installiert ist und eine Anfrage tatsächlich nach einem greift.

Eine durchgearbeitete Sitzung

Starten Sie von einer CSV im Nixtla-Langformat:

unique_id,ds,y
branch_01,2018-01-01,1043.2
branch_01,2018-02-01,1102.7
...

1. Laden Sie sie. Das Panel bleibt im Serverprozess; das Handle ist alles, was die Sitzung mit sich führt.

{"handle": "deposits", "n_series": 12, "n_obs": 864, "freq": "MS",
 "start": "2018-01-01T00:00:00", "end": "2023-12-01T00:00:00",
 "obs_per_series": {"min": 72, "median": 72, "max": 72},
 "n_missing_y": 0, "sha256": "9f2c…"}

2. Beschreiben Sie sie. Dies sind die Zahlen, über die Sie nachdenken.

| id        | n  | mean   | cv    | %zero | trend | seasonal | acf1(diff) |
|-----------|----|--------|-------|-------|-------|----------|------------|
| branch_01 | 72 | 1180.4 | 0.112 | 0.0   | 0.83  | 0.62     | -0.31      |

Hohe saisonale Stärke und ein klarer Trend sprechen für AutoETS und AutoARIMA gegenüber einer naiven Baseline; ein hoher %zero-Wert hätte stattdessen für ADIDA oder CrostonClassic gesprochen.

seasonal ist eine STL-Stärke – die saisonale Komponente gemessen an dem, was übrig bleibt, sobald der Trend entfernt ist – daher meldet eine wachsende Serie ihre Saisonalität dennoch ehrlich. Sie trägt ein Rauschniveau von etwa 0,3–0,5: Werte in diesem Band bedeuten „keine Evidenz“, nicht „leicht saisonal“.

3. Überprüfen Sie, was installiert ist mit tsf_list_models, damit Sie niemals ein Modell vorschlagen, das diese Maschine nicht ausführen kann.

4. Validieren Sie die Kandidaten kreuzweise – immer einschließlich SeasonalNaive, da ein Modell, das es nicht schlagen kann, nicht einsatzbereit ist:

{"kind": "cross_validation", "models": ["SeasonalNaive", "AutoETS", "AutoARIMA"],
 "h": 12, "n_windows": 4, "seasonality_used_for_mase": 12,
 "metrics": {"mase": {"SeasonalNaive": 1.0, "AutoETS": 0.71, "AutoARIMA": 0.68}},
 "ranking": {"mase": ["AutoARIMA", "AutoETS", "SeasonalNaive"]},
 "artifact": "~/.tslab-mcp/runs/cv_deposits_3f1a9c02.parquet"}

5. Prognostizieren Sie mit dem Gewinner. Der vollständige Frame geht nach Parquet; die Antwort enthält den Pfad, die Spalten und eine kurze Vorschau.

6. Exportieren Sie den Lauf und den Bericht. Schreiben Sie warum in die Notiz – es ist der einzige Teil Ihrer Überlegungen, der die Konversation überlebt:

{"manifest": "~/.tslab-mcp/runs/manifest_deposits_77b0e415.json", "n_runs": 3,
 "kinds": ["cross_validation", "forecast"]}

Das Manifest enthält den Quellpfad und den Hash, die Frequenz, jeden Aufruf mit seinen Argumenten und Artefaktpfaden, die fixierten Versionen von allem, was tatsächlich installiert ist – statsforecast, pandas und Python immer; TimeCopilot und torch auch, wenn das foundation-Extra dabei ist – und Ihre Notiz. Es reicht aus, um die Zahlen bei gestopptem Server zu reproduzieren.

tsf_export_report verwandelt dasselbe Manifest in etwas, das eine Person liest – Merkmale, Metriktabellen nach Besten geordnet, Prognosen, Anomalien und die Umgebung, in der Reihenfolge ihres Auftretens:

{"report": "~/.tslab-mcp/runs/report_deposits_5c31d0a7.html",
 "format": "html", "n_steps": 3,
 "steps": ["features", "cross_validation", "forecast"]}

Der Bericht ist eine reine Funktion des Manifests: Er liest kein Parquet und ruft kein Modell auf, daher rendert tsf_export_report mit manifest_path einen Lauf von vor Monaten neu, ohne dass etwas geladen ist. Das HTML bettet sein eigenes CSS ein und referenziert kein externes Skript, Stylesheet oder Schriftart, sodass es auch offline korrekt geöffnet wird.

Design

Vier Invarianten und die Gründe für ihre Existenz:

Handles, keine Dataframes.
Ein Kreuzvalidierungsrahmen umfasst
n_series × h × n_windows × n_models Zeilen. Wenn man ihn als Tool-Ergebnis
serialisiert, erschöpft das beim ersten Aufruf den Kontext der Sitzung und
verschlechtert jede spätere Interaktion. Tools übergeben einen Handle und geben
Zusammenfassungen, Aggregate und Dateipfade zurück; jeder Bulk-Pfad ist
begrenzt und meldet, was ausgelassen wurde, damit die Sitzung weiß, dass sie
das Parquet lesen soll, anstatt erneut zu fragen.

Blockierende Arbeiten berühren nie die Event-Schleife.
Das Kreuzvalidieren mehrerer Modelle über eine große Tabelle hinweg bedeutet
Minuten Rechenzeit. Jeder Tool-Body ist ein synchroner Closure, der über
anyio.to_thread.run_sync ausgeführt wird, sodass der stdio-Transport weiterhin
antwortet und der Client den Server nicht mitten im Lauf verwirft.

Die Umgebung wird entdeckt, nicht angenommen.
Modelle werden lazy importiert und geprüft, niemals als vorhanden
vorausgesetzt. tsf_list_models meldet, was hier tatsächlich aufgelöst wurde.
Wenn man also Chronos ohne die zusätzliche Abhängigkeit anfragt, erhält man
eine Nachricht, die das Extra benennt, anstatt zehn Minuten nach Beginn des
Laufs einen Traceback zu bekommen.

Das Backend wird dadurch bestimmt, was man anfragt: Eine Anfrage, deren Modelle
alle statistisch über statsforecast laufen, und nur eine Anfrage, die ein
vorab trainiertes Modell benötigt, greift auf TimeCopilot zu. Statistische Läufe
importieren daher niemals torch, und der Server startet in beiden Fällen
sofort.

statsforecast wird bewusst auf dem Standardwert n_jobs=1 belassen. Sein
Parallelmodus startet Worker-Prozesse, die das Einstiegsmodul erneut
importieren, was innerhalb eines MCP-Servers eher Konflikte und eine
stdout-Gefahr als Geschwindigkeitsvorteile bringt.

Das Manifest ist das Artefakt der Aufzeichnung.
Prosa im Gespräch ist Kommentar. Das Manifest ist das, was jemand in sechs
Monaten erneut ausführt, und das, was ein Prüfer liest, um zu sehen, welche
Modelle verglichen wurden und auf welcher Grundlage.

Python-Version

TimeCopilot macht mehrere Modelle von der Interpreter-Version abhängig, und
unter Python < 3.13 pinnt es tabpfn-time-series, was pandas unter 2.2
festlegt.

3.13 ist das empfohlene Ziel. In beiden Fällen meldet tsf_list_models, was
tatsächlich aufgelöst wurde, mit dem Grund für alles, was nicht aufgelöst
werden konnte.

Entwicklung

uv sync --all-groups
uv run pytest                  # fast suite
uv run pytest -m slow          # exercises TimeCopilot; slower, no weight downloads
uv run ruff check src tests
uv run mypy

Überprüfen Sie die Tool-Oberfläche mit dem MCP Inspector:

npx @modelcontextprotocol/inspector uv run tslab-mcp

Lizenz

MIT