tslab-mcp

MCP-сервер, который предоставляет детерминированное прогнозирование временных рядов в виде инструментов, так что ваш агент является механизмом рассуждения, а каждое число поступает из обычного, воспроизводимого Python.

Никакая LLM не вызывается нигде в этом пакете. Никакой API-ключ не требуется (если только вы не запросите TimeGPT, который вызывает Nixtla API).

Зачем

Некоторые библиотеки прогнозирования поставляют агента, который читает признаки, выбирает модель и объясняет результат с помощью LLM в цикле. Вызов такого агента из вашего собственного агента вкладывает агента внутрь агента — два запроса, два счета, два источника недетерминизма и непрозрачный промежуточный слой, который делает обоснование выбора модели неаудитируемым.

Поэтому здесь управление инвертировано: библиотека прогнозирования — это инструмент, а ваш агент — тот, кто рассуждает. Он читает признаки, аргументирует выбор семейства моделей, перекрестно проверяет кандидатов и записывает обоснование в манифест. Каждое число на этом пути создается вызовом библиотеки, который можно перезапустить без LLM в цепочке.

Это разделение распространяется и на то, как построен сам пакет. Базовая установка запускает одиннадцать статистических моделей — AutoARIMA, AutoETS, Theta, CrostonClassic и другие — через statsforecast: примерно 340 МБ, без PyTorch, и запускается за секунды. Дополнительный пакет foundation добавляет предобученные модели TimeCopilot — Chronos, Moirai, TimesFM, TiRex, Toto и другие — плюс Prophet, для случаев, когда статистического базиса недостаточно. Запрос, который называет только статистические модели, никогда не импортирует TimeCopilot или torch; запрос, который называет хотя бы одну фундаментальную модель, полностью выполняется через TimeCopilot, который также несет в себе статистические модели. В любом случае tsf_list_models сообщает, что на самом деле установлено, прежде чем вы примете решение о модели.

Related MCP server: forecast-mcp

Установка

Требуется Python 3.10+ (рекомендуется 3.13, см. Версия Python).

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

Базовая установка запускает одиннадцать статистических моделей через statsforecast: примерно 340 МБ, без PyTorch, и запускается мгновенно. Для предобученных фундаментальных моделей — Chronos, Moirai, TimesFM, Toto, TiRex — и Prophet добавьте дополнительный пакет:

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

Дополнительный пакет foundation подтягивает TimeCopilot, который приносит torch, transformers и lightning: примерно 2 ГБ при первой установке, и первый вызов инструмента, который его касается, тратит ~30 секунд на импорт. Оба действия одноразовые, и ни одно из них не является платным, если только вы не запросите модель, которая их требует.

Из GitHub

uv и uvx оба принимают git-URL вместо имени пакета, что устанавливает текущий main без ожидания релиза:

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

Зафиксируйте ревизию для чего-либо, кроме случайного тестирования — ветка может перемещаться под вами. Коммит работает сегодня; тег версии тоже будет работать, как только он будет создан:

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

Из локальной копии

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

Настройка

Добавьте сервер в конфигурацию вашего MCP-клиента. Файл различается в зависимости от клиента — часто это .mcp.json в корне проекта — но сама запись имеет одинаковую форму:

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

TSLAB_MCP_HOME задает, куда записываются артефакты; по умолчанию это ~/.tslab-mcp, а результаты выполнения попадают в <home>/runs.

Транспорт только stdio, по замыслу: ваши данные считаются чувствительными и никогда не покидают машину. Сервер не делает исходящих запросов, кроме загрузки весов моделей, которые TimeCopilot сам выполняет для фундаментальных моделей, и вызовов Nixtla API, которые делает TimeGPT, если вы специально его запросите.

GitHub Copilot

Copilot обнаруживает MCP-серверы из файла mcp.json и предоставляет их инструменты в режиме агента — инструменты не появляются в режиме ask или edit.

VS Code. Поместите сервер в .vscode/mcp.json, чтобы поделиться им с репозиторием, или выполните MCP: Open User Configuration из палитры команд, чтобы сохранить его в своем профиле для всех рабочих областей. Обратите внимание, что ключ — servers, а не mcpServers:

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

Из локальной копии укажите путь к рабочему дереву:

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

Затем: откройте Chat, переключите селектор режима на Agent и с помощью кнопки Tools убедитесь, что восемь инструментов tsf_* перечислены и включены. MCP: List Servers показывает статус сервера и его логи, где объясняется неудачный запуск. Copilot ограничивает количество одновременно активных инструментов, поэтому, если вы запускаете несколько MCP-серверов, возможно, придется отключить некоторые, чтобы уместить все восемь.

Visual Studio. Та же форма JSON, в .mcp.json в корне решения (или %USERPROFILE%\.mcp.json для всех решений), затем включите инструменты из панели выбора инструментов в режиме агента Copilot Chat.

JetBrains, Eclipse и Xcode. Откройте панель выбора инструментов в режиме агента Copilot Chat, выберите Edit MCP configuration и добавьте ту же запись servers в открывшийся mcp.json.

Copilot coding agent (облачный агент на github.com) плохо подходит для этого сервера: он запускает ваши MCP-серверы в эфемерном окружении GitHub Actions, что означает оплату ~2 ГБ установки TimeCopilot при каждом запуске, и у него нет доступа к локальным файлам данных. Используйте его из своего редактора.

Инструменты

Все, кроме двух инструментов tsf_export_*, помечены как read-only; здесь ничего не удаляется, так что очистка ~/.tslab-mcp/runs — ваша забота, а не агента.

Начало сессии

Инструменты не навязывают порядок, поэтому начальный запрос превращает восемь вызываемых функций в анализ. Что-то вроде этого работает хорошо:

Используй инструменты tslab для прогнозирования рядов в /Users/me/data/deposits.csv, на 12 месяцев вперед.

Работай в таком порядке и показывай свои рассуждения на каждом шаге:

1. Загрузи файл и расскажи, что ты нашел — сколько рядов, какая частота, есть ли пропуски или отсутствующие значения.

2. Опиши признаки и скажи, какие семейства моделей они обосновывают и почему.

3. Проверь, какие модели на самом деле установлены, прежде чем предлагать.

4. Проведи перекрестную проверку твоего шорт-листа против базовой SeasonalNaive на 4 окнах. Пока только статистические модели.

5. Спрогнозируй с победителем, с интервалами 80% и 95%.

6. Экспортируй манифест запуска и HTML-отчет, и помести обоснование выбора модели в заметку: что ты выбрал, что показала таблица метрик и что ты отклонил.

Обобщи результаты и дай мне пути к parquet — не вставляй целые таблицы в чат.

Четыре вещи в этом запросе действительно важны:

• Абсолютный путь. Относительные пути разрешаются относительно рабочего каталога сервера, который выбирает ваш MCP-клиент, и вы обычно не можете его предсказать.

• Горизонт, соответствующий решению. h управляет как прогнозом, так и тем, сколько истории потребляет каждое окно CV; 12 месячных шагов — это год планирования, а не произвольное значение по умолчанию.

• «Пока только статистические модели.» Без этого агент может потянуться к фундаментальной модели и потратить несколько минут на загрузку весов, чтобы ответить на вопрос, который AutoETS решил бы за секунды. Снимите ограничение, когда дешевые модели установят базовый уровень.

• Запрос обоснования в заметке манифеста. Стенограмма чата одноразова; манифест — это та часть, которую кто-то может перезапустить и проверить. Если рассуждения существуют только в разговоре, они фактически потеряны.

Более короткие начальные запросы, когда вы знаете, что хотите:

Загрузи /Users/me/data/sales.parquet и опиши признаки. Пока не прогнозируй — я хочу сначала увидеть, с чем мы имеем дело.

Сравни SeasonalNaive, AutoETS и AutoARIMA на загруженном дескрипторе deposits на 6 окнах при h=12, затем скажи, превосходит ли что-то базовую модель настолько, чтобы стоить дополнительной сложности.

Вызовы только статистических моделей отвечают за секунды. Первый вызов, который называет фундаментальную модель, тратит ~30 секунд на импорт TimeCopilot, прежде чем сделать что-либо еще — эта пауза ожидаема, это не зависание, и она происходит только в том случае, если установлен дополнительный пакет foundation и запрос действительно обращается к такой модели.

Пример сессии

Начнем с CSV в длинном формате Nixtla:

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

1. Загрузите его. Панель остается в процессе сервера; дескриптор — это все, что несет сессия.

{"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. Опишите его. Это числа, над которыми вы рассуждаете.

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

Высокая сезонная сила и четкий тренд говорят в пользу AutoETS и AutoARIMA по сравнению с наивным базовым уровнем; высокий %zero говорил бы в пользу ADIDA или CrostonClassic.

seasonal — это сила STL — сезонная составляющая, измеренная относительно того, что остается после удаления тренда, — поэтому растущий ряд все равно честно сообщает о своей сезонности. Он имеет шумовой порог примерно 0.3–0.5: оценки в этом диапазоне означают «нет доказательств», а не «умеренно сезонный».

3. Проверьте, что установлено с помощью tsf_list_models, чтобы никогда не предлагать модель, которую эта машина не может запустить.

4. Проведите перекрестную проверку кандидатов — всегда включая SeasonalNaive, так как модель, которая не может его превзойти, не стоит развертывания:

{"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. Спрогнозируйте с победителем. Полный фрейм идет в parquet; ответ содержит путь, столбцы и краткий предпросмотр.

6. Экспортируйте запуск и отчет. Запишите почему в заметку — это единственная часть ваших рассуждений, которая переживет разговор:

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

Манифест содержит исходный путь и хэш, частоту, каждый вызов с его аргументами и путями артефактов, зафиксированные версии всего, что на самом деле установлено — statsforecast, pandas и Python всегда; TimeCopilot и torch тоже, если установлен дополнительный пакет foundation — и вашу заметку. Этого достаточно, чтобы воспроизвести числа при остановленном сервере.

tsf_export_report превращает тот же манифест в то, что читает человек — признаки, таблицы метрик, упорядоченные от лучших к худшим, прогнозы, аномалии и окружение, в порядке их возникновения:

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

Отчет является чистой функцией манифеста: он не читает parquet и не вызывает модель, поэтому tsf_export_report с manifest_path перерисовывает запуск месячной давности без загруженных данных. HTML встраивает свой собственный CSS и не ссылается на внешние скрипты, таблицы стилей или шрифты, поэтому он все еще корректно открывается в офлайн-режиме.

Дизайн

Четыре инварианта и причины их существования:

Дескрипторы, а не датафреймы. Один фрейм кросс-валидации содержит n_series × h × n_windows × n_models строк. Сериализация его в результат инструмента исчерпывает контекст сессии при первом же вызове и ухудшает каждый последующий оборот. Инструменты принимают дескриптор и возвращают сводки, агрегаты и пути к файлам; каждый массовый путь ограничен и сообщает, что было пропущено, чтобы сессия знала, что нужно прочитать parquet, а не запрашивать снова.

Блокирующая работа никогда не касается цикла событий. Кросс-валидация нескольких моделей на большой панели занимает минуты процессорного времени. Каждое тело инструмента представляет собой синхронное замыкание, отправляемое через anyio.to_thread.run_sync, поэтому транспорт stdio продолжает отвечать, и клиент не обрывает сервер на середине выполнения.

Окружение определяется, а не предполагается. Модели импортируются лениво и проверяются, никогда не предполагается, что они присутствуют. tsf_list_models сообщает, что на самом деле разрешилось, поэтому запрос Chronos без дополнительного пакета возвращает сообщение, указывающее на этот пакет, а не трейсбек через десять минут выполнения.

Бэкенд выбирается в зависимости от того, что вы запрашиваете: запрос, все модели в котором статистические, выполняется через statsforecast, и только запрос, которому нужна предварительно обученная модель, обращается к TimeCopilot. Таким образом, статистические запуски никогда не импортируют torch, и сервер запускается мгновенно в любом случае.

statsforecast намеренно оставлен с настройкой по умолчанию n_jobs=1. Его параллельный режим порождает рабочие процессы, которые повторно импортируют входной модуль, что внутри MCP-сервера приводит к конкуренции и риску для stdout, а не к ускорению.

Манифест — это артефакт для записи. Проза в диалоге — это комментарий. Манифест — это то, что кто-то перезапустит через шесть месяцев, и то, что читает рецензент, чтобы увидеть, какие модели сравнивались и на каком основании.

Python version

TimeCopilot gates several models on the interpreter version, and on Python < 3.13 it pins tabpfn-time-series, which caps pandas below 2.2.

3.13 — рекомендуемая версия. В любом случае tsf_list_models сообщает, что на самом деле разрешилось, с указанием причины для всего, что не разрешилось.

Development

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

Проверьте поверхность инструментов с помощью MCP Inspector:

npx @modelcontextprotocol/inspector uv run tslab-mcp

License

MIT