ml-lifecycle-mcp

An MCP server that exposes a time series forecasting model as a tool, with a built-in audit trail for every call.

Why this project

Two things prompted this:

1. A conversation with an RBC contact about the Model Context Protocol as a way to expose internal ML/data tools to LLM clients in a standardized way.
2. RBC Borealis's own research focus areas include time series analysis and NLP — this project picks time series as the first concrete capability, built the way I'd want a production tool to be built, not a notebook demo.

The goal isn't "wrap a model in MCP." It's: what does it take for an ML capability to be trustworthy enough to hand to an autonomous client? That means typed interfaces, input validation, tests that cover the failure modes (not just the happy path), and — carried over from a separate project of mine, ai-governance-gateway — an audit log of every call, since "what happened and with what inputs" is the first question anyone asks when a model-backed system misbehaves.

Architecture

src/ml_lifecycle_mcp/
  forecasting.py   # the model: Holt-Winters exponential smoothing (statsmodels),
                    # wrapped behind a typed function so the tool layer never
                    # touches statsmodels directly
  audit.py          # AuditLogger — context manager that records every call
                     # (timing, input shape, success/failure) as JSON lines
  server.py         # FastMCP server: registers `forecast_timeseries` as an
                     # MCP tool, wraps it with the audit logger
  web.py             # Starlette app: a browser UI over the same model +
                      # the same audit log, for demoing without an MCP client
  static/            # index.html / style.css / app.js — the browser UI
tests/
  test_forecasting.py  # model correctness + input validation
  test_audit.py        # logging behavior, including the failure path
  test_server.py        # the tool function as a client would call it
  test_web.py            # the HTTP API as a browser would call it

Design choices worth knowing about, and their limitations:

• Confidence intervals are approximated from in-sample residual standard deviation under a normal-residual assumption, not from statsmodels' simulation-based intervals. That's a reasonable trade for a lightweight service, but it understates uncertainty for short or non-stationary series. A production version would switch to get_prediction() with simulated paths.
• Audit logging defaults to shape-only (list length, types), not raw values, since forecasting inputs may be business-sensitive. log_values=True exists for local debugging but shouldn't be turned on against real data without a retention/PII policy — same lesson as the governance gateway project.
• One tool, on purpose. This was scoped to be small and correct rather than broad. An NLP tool (sentiment/summarization) following the same pattern — typed wrapper, audited, tested — is the natural next addition.
• The web UI adds zero new dependencies. mcp already pulls in starlette and uvicorn transitively, so web.py uses those directly instead of adding FastAPI on top. It shares the same AuditLogger instance (same default log file) as the MCP server, so a call made from Claude Desktop and a call made from the browser both show up in one audit trail — the log shouldn't care which door a request came through.

Setup

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Running the tests

python -m pytest -v

Running the server

python -m ml_lifecycle_mcp.server

This starts an MCP server over stdio. To use it from Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "ml-lifecycle-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "ml_lifecycle_mcp.server"]
    }
  }
}

Then ask Claude something like: "Forecast the next 5 points of [10, 12, 13, 15, 14, 17, 19, 20]" — it will call forecast_timeseries and every call gets written to audit_log.jsonl in the working directory.

Running the web UI

python -m ml_lifecycle_mcp.web

Open http://127.0.0.1:8000. Paste a series, set a horizon, hit run forecast — you'll see the series plotted with the forecast segment and its 80% confidence band, and the audit log panel underneath updates with every call. This is the same model and the same audit trail the MCP tool uses, just reachable without an MCP client — useful for a live demo when you don't want to depend on Claude Desktop being configured correctly in the room.

Example

from ml_lifecycle_mcp.server import forecast_timeseries

forecast_timeseries(values=[10, 12, 13, 15, 14, 17, 19, 20], horizon=3)
# {'forecast': [21.21, 22.60, 23.98],
#  'lower_80': [20.32, 21.70, 23.08],
#  'upper_80': [22.11, 23.49, 24.87],
#  'method': 'holt_winters_trend'}