# ml-lifecycle-mcp

An [MCP](https://modelcontextprotocol.io) 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`](https://github.com/Khuong-Quan-Nguyen/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

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

## Running the tests

```bash
python -m pytest -v
```

## Running the server

```bash
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`:

```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

```bash
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

```python
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'}
```