Developer Guide

This guide explains how the project is structured, how to develop new features, and how to test changes.

Development Prerequisites

  • Python 3.10+

  • pip

  • Optional: sphinx if you want to build the documentation site

Setup

From the repo root:

pip install -e ".[dev]"

Validate the environment before running tests:

python -c "import sktime; print(sktime.__version__)"

If this command fails with ModuleNotFoundError: No module named 'sktime', reinstall project dependencies in the active virtual environment:

pip install -e ".[dev]"

If you work with SQL or file formats:

pip install -e ".[sql]"
pip install -e ".[files]"

Running The Server Locally

python -m sktime_mcp.server

Running Tests

pytest

Standard Local Checks

From the repo root:

make check

Auto-fix formatting and fixable lint issues:

make format-fix

If make is unavailable (common on Windows), run:

python -m ruff format --check .
python -m ruff check .
python -m pytest

Project Layout

  • src/sktime_mcp/server.py MCP entry point and tool router

  • src/sktime_mcp/tools/ MCP tool implementations

  • src/sktime_mcp/registry/ sktime estimator discovery and tag logic

  • src/sktime_mcp/composition/ pipeline validation rules

  • src/sktime_mcp/runtime/ executor and handle manager

  • src/sktime_mcp/data/ data source adapters and registry

  • examples/ runnable examples

Architecture Overview

High-level flow:

  1. MCP server receives a tool call

  2. The server routes to a tool implementation in tools/

  3. Tools use the registry/runtime layers to execute operations

  4. Results are sanitized and returned to the client

This separation keeps the MCP surface small while allowing deeper functionality in the runtime and data layers.

Adding A New MCP Tool

  1. Create a new module under src/sktime_mcp/tools/ with a *_tool function.

  2. Add a tool schema in src/sktime_mcp/server.py within list_tools().

  3. Add a handler in call_tool() to dispatch the tool name.

  4. Add tests in tests/.

  5. Document the tool in docs/source/user-guide.md.

Adding A New Data Source Adapter

  1. Implement a new adapter in src/sktime_mcp/data/adapters/ that inherits DataSourceAdapter.

  2. Register it in src/sktime_mcp/data/registry.py using DataSourceRegistry.register().

  3. Add tests covering load(), validate(), and to_sktime_format().

  4. Update docs/source/data-sources.md.

Adding A Demo Dataset

Update DEMO_DATASETS in src/sktime_mcp/runtime/executor.py with a new loader string. Ensure the loader function returns a sktime-compatible dataset.

Documentation Build

If you want to build the docs site locally:

pip install -r docs/requirements.txt
sphinx-build -b html docs/source docs/build/html

The config lives in docs/source/conf.py and the docs content is under docs/source/.