sequenx-mcp 0.1.0__tar.gz

sequenx_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: sequenx-mcp
+Version: 0.1.0
+Summary: MCP server exposing the SequenxAI public API as tools for AI hosts
+Author-email: SequenxAI <lcw_1497007939@163.com>
+License-Expression: LicenseRef-Proprietary
+Keywords: mcp,time-series,forecasting,sequenxai
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: sequenx-ai>=0.1.0
+
+# sequenx-mcp (SequenxAI MCP server)
+
+MCP server that exposes the SequenxAI public API as tools for AI hosts (Claude
+Desktop, Cursor, …). It is a thin adapter: every tool maps one-to-one onto an
+existing operation and calls the Python SDK — there is no second HTTP client and
+no business logic here (see
+[`docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md`](../../docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md)).
+
+Not published on PyPI yet; it lives in this repository.
+
+## Install
+
+The server depends on the sibling SDK, which is not on PyPI either — install it
+from this repository first:
+
+```bash
+pip install -e packages/sequenx-py
+pip install -e packages/sequenx-mcp
+```
+
+## Run
+
+The server speaks stdio, the transport a local MCP host starts as a child
+process:
+
+```bash
+SEQUENX_API_KEY=sqx_live_... python -m sequenx_mcp
+```
+
+| Variable | Meaning |
+|---|---|
+| `SEQUENX_API_KEY` | The `sqx_live_*` key the tools call with (required). |
+| `SEQUENX_API_BASE_URL` | Base URL override; default `https://api.sequenxai.com/v1`. |
+
+Host configuration (any MCP host that starts stdio servers):
+
+```json
+{
+  "mcpServers": {
+    "sequenx": {
+      "command": "python",
+      "args": ["-m", "sequenx_mcp"],
+      "env": { "SEQUENX_API_KEY": "sqx_live_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Endpoint | What it does |
+|---|---|---|
+| `list_models` | `GET /v1/models` | The public model catalog for the key: ids, the default model, per-model context / horizon limits and capabilities. |
+| `clean_data` | `POST /v1/clean` | The free cleaning dry-run: cleaning report and effective policy. No inference, no billing. Takes `series`, `options`, `freq`, `model` and `clean_series`. |
+| `forecast` | `POST /v1/forecast` | Synchronous forecast over inline rows: points and intervals, data-quality report, billed usage. Takes `series`, `h`, `model`, `freq`, `level` and `options`. |
+
+Input rows are the contract's long table: `unique_id`, `ds`, `y`.
+
+**Limits.** `forecast` takes inline rows only — the public API has no dataset
+upload, so the tool is for small-to-medium series. The model reads only the most
+recent points of a series: a longer history is truncated by the API and
+reported (`model_input[].truncated` plus a `context_truncated` warning), and
+`list_models` gives each model's context window. The server adds no limit of
+its own. For larger data use the REST or SDK batch path:
+`POST /v1/forecast/batch`, then poll `GET /v1/forecast/batch/{job_id}`.
+
+**Errors.** A tool error carries the contract's error body
+(`{"error": {code, message, request_id, category, retryable, details?}}`), so
+the host agent sees a structured error instead of a silent empty answer. The MCP
+framework prefixes the message with its own text, so the envelope travels
+*inside* the error text. `403` is not retried; `429` carries `retry_after` and
+`limit_type` (`rpm` / `daily`) in `details`.
+
+Three codes are the SDK's own, because the contract's code list covers
+server-side failures only: `HTTP_<status>` (a response without a code),
+`REQUEST_FAILED` (a response body the SDK could not read) and `TRANSPORT_ERROR`
+(the request never reached the server).
+
+## Development
+
+```bash
+pip install -e packages/sequenx-py
+pip install -e packages/sequenx-mcp -r packages/sequenx-mcp/requirements-dev.txt
+cd packages/sequenx-mcp
+python -m pytest -q
+python -m ruff check src tests
+```
+
+Gitee Go runs the suite via `scripts/ci/gitee-verify.sh mcp`.
+
+Use a separate virtualenv for this package: `mcp` 2.x installs `httpx2`, and a
+control-plane environment that has `httpx2` next to `httpx` breaks Starlette's
+test client (`services/api` needs `httpx` 1.x).

sequenx_mcp-0.1.0/README.md

@@ -0,0 +1,93 @@
+# sequenx-mcp (SequenxAI MCP server)
+
+MCP server that exposes the SequenxAI public API as tools for AI hosts (Claude
+Desktop, Cursor, …). It is a thin adapter: every tool maps one-to-one onto an
+existing operation and calls the Python SDK — there is no second HTTP client and
+no business logic here (see
+[`docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md`](../../docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md)).
+
+Not published on PyPI yet; it lives in this repository.
+
+## Install
+
+The server depends on the sibling SDK, which is not on PyPI either — install it
+from this repository first:
+
+```bash
+pip install -e packages/sequenx-py
+pip install -e packages/sequenx-mcp
+```
+
+## Run
+
+The server speaks stdio, the transport a local MCP host starts as a child
+process:
+
+```bash
+SEQUENX_API_KEY=sqx_live_... python -m sequenx_mcp
+```
+
+| Variable | Meaning |
+|---|---|
+| `SEQUENX_API_KEY` | The `sqx_live_*` key the tools call with (required). |
+| `SEQUENX_API_BASE_URL` | Base URL override; default `https://api.sequenxai.com/v1`. |
+
+Host configuration (any MCP host that starts stdio servers):
+
+```json
+{
+  "mcpServers": {
+    "sequenx": {
+      "command": "python",
+      "args": ["-m", "sequenx_mcp"],
+      "env": { "SEQUENX_API_KEY": "sqx_live_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Endpoint | What it does |
+|---|---|---|
+| `list_models` | `GET /v1/models` | The public model catalog for the key: ids, the default model, per-model context / horizon limits and capabilities. |
+| `clean_data` | `POST /v1/clean` | The free cleaning dry-run: cleaning report and effective policy. No inference, no billing. Takes `series`, `options`, `freq`, `model` and `clean_series`. |
+| `forecast` | `POST /v1/forecast` | Synchronous forecast over inline rows: points and intervals, data-quality report, billed usage. Takes `series`, `h`, `model`, `freq`, `level` and `options`. |
+
+Input rows are the contract's long table: `unique_id`, `ds`, `y`.
+
+**Limits.** `forecast` takes inline rows only — the public API has no dataset
+upload, so the tool is for small-to-medium series. The model reads only the most
+recent points of a series: a longer history is truncated by the API and
+reported (`model_input[].truncated` plus a `context_truncated` warning), and
+`list_models` gives each model's context window. The server adds no limit of
+its own. For larger data use the REST or SDK batch path:
+`POST /v1/forecast/batch`, then poll `GET /v1/forecast/batch/{job_id}`.
+
+**Errors.** A tool error carries the contract's error body
+(`{"error": {code, message, request_id, category, retryable, details?}}`), so
+the host agent sees a structured error instead of a silent empty answer. The MCP
+framework prefixes the message with its own text, so the envelope travels
+*inside* the error text. `403` is not retried; `429` carries `retry_after` and
+`limit_type` (`rpm` / `daily`) in `details`.
+
+Three codes are the SDK's own, because the contract's code list covers
+server-side failures only: `HTTP_<status>` (a response without a code),
+`REQUEST_FAILED` (a response body the SDK could not read) and `TRANSPORT_ERROR`
+(the request never reached the server).
+
+## Development
+
+```bash
+pip install -e packages/sequenx-py
+pip install -e packages/sequenx-mcp -r packages/sequenx-mcp/requirements-dev.txt
+cd packages/sequenx-mcp
+python -m pytest -q
+python -m ruff check src tests
+```
+
+Gitee Go runs the suite via `scripts/ci/gitee-verify.sh mcp`.
+
+Use a separate virtualenv for this package: `mcp` 2.x installs `httpx2`, and a
+control-plane environment that has `httpx2` next to `httpx` breaks Starlette's
+test client (`services/api` needs `httpx` 1.x).

sequenx_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sequenx-mcp"
+dynamic = ["version"]
+description = "MCP server exposing the SequenxAI public API as tools for AI hosts"
+authors = [{ name = "SequenxAI", email = "lcw_1497007939@163.com" }]
+keywords = ["mcp", "time-series", "forecasting", "sequenxai"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+dependencies = [
+    "mcp>=2.3,<3",
+    "pydantic>=2.7,<3",
+    # The sibling SDK in this repository; install it first
+    # (pip install -e packages/sequenx-py) — it is not on PyPI yet.
+    "sequenx-ai>=0.1.0",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "sequenx_mcp._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# Same rule set as the other Python packages in the monorepo.
+select = ["E", "F", "I", "B", "W", "UP"]

sequenx_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sequenx_mcp-0.1.0/src/sequenx_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""MCP server exposing the SequenxAI public API as tools for AI hosts."""
+
+from ._version import __version__
+from .server import build_server, main
+
+__all__ = ["__version__", "build_server", "main"]

sequenx_mcp-0.1.0/src/sequenx_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m sequenx_mcp``: run the MCP server over stdio."""
+
+from .server import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sequenx_mcp-0.1.0/src/sequenx_mcp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sequenx_mcp-0.1.0/src/sequenx_mcp/errors.py

@@ -0,0 +1,71 @@
+"""Map the SDK's typed errors onto the contract's error shape.
+
+The contract answers with ``ErrorResponse`` = ``{"error": {code, message,
+request_id, details?}}`` and does not use RFC 7807 (see
+``docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md`` §3.2). A tool therefore
+reports the API's own error body as the tool error message, so the host agent
+sees a structured error instead of a silent empty answer. The MCP framework
+prefixes the message with its own text ("Error executing tool …"), so the
+envelope travels inside the message rather than as the whole message.
+
+The body keeps the contract's ``ErrorDetail`` fields — ``code``, ``message``,
+``request_id``, ``category``, ``retryable`` and ``details`` — and adds the
+retry hints the RFC asks the host to see (``retry_after`` and ``limit_type``)
+inside ``details``. ``category`` and ``retryable`` are only present when the
+upstream body carried them.
+
+Three codes are the SDK's own, because no contract code covers them: the
+contract's list (``x-error-codes`` in openapi.yaml) describes server-side
+failures only. ``HTTP_<status>`` is a response without a code, ``REQUEST_FAILED``
+a response the SDK could not read, ``TRANSPORT_ERROR`` a request that never
+reached the server.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server.mcpserver.exceptions import ToolError
+from sequenx import RateLimitedError, SequenxError, TransportError
+
+
+def error_body(exc: SequenxError) -> dict[str, Any]:
+    """The contract's ErrorDetail body for an SDK error."""
+    details: dict[str, Any] = {}
+    if isinstance(exc.details, dict):
+        details.update(exc.details)
+    elif exc.details is not None:
+        details["details"] = exc.details
+    if isinstance(exc, RateLimitedError):
+        if exc.retry_after is not None:
+            details["retry_after"] = exc.retry_after
+        if exc.limit_type is not None:
+            details["limit_type"] = exc.limit_type
+    if exc.code:
+        code = exc.code
+    elif exc.status is not None:
+        code = f"HTTP_{exc.status}"
+    elif isinstance(exc, TransportError):
+        # No response reached us at all.
+        code = "TRANSPORT_ERROR"
+    else:
+        # A client-side failure (e.g. a response without a JSON body).
+        code = "REQUEST_FAILED"
+    body: dict[str, Any] = {
+        "code": code,
+        "message": str(exc),
+        "request_id": exc.request_id,
+    }
+    if exc.category is not None:
+        body["category"] = exc.category
+    if exc.retryable is not None:
+        body["retryable"] = exc.retryable
+    if details:
+        body["details"] = details
+    return {"error": body}
+
+
+def tool_error(exc: SequenxError) -> ToolError:
+    """A tool error carrying the contract's error body as its message."""
+    return ToolError(json.dumps(error_body(exc), ensure_ascii=False))

sequenx_mcp-0.1.0/src/sequenx_mcp/server.py

@@ -0,0 +1,115 @@
+"""The MCP server: three tools over the SequenxAI public API."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Annotated, Any
+
+from mcp.server.mcpserver import MCPServer
+from pydantic import Field
+from sequenx import SequenxClient
+
+from . import tools
+from ._version import __version__
+from .tools import Point
+
+INSTRUCTIONS = (
+    "Time-series forecasting on the SequenxAI platform. The data is passed inline as "
+    "long-table rows (unique_id, ds, y). Start with list_models to learn the models and "
+    "their limits, clean_data to preview how the data will be cleaned (free), and "
+    "forecast to get the prediction and the usage that was billed."
+)
+
+LIST_MODELS_DESCRIPTION = (
+    "List the public time-series models available to this API key: each model's id, the "
+    "default model, its context and horizon limits and its capabilities. Call it before "
+    "forecasting to learn the limits; the catalog is owned by the server and changes "
+    "without a version bump."
+)
+
+CLEAN_DATA_DESCRIPTION = (
+    "Run the free cleaning dry run: the same cleaning stage as a forecast, returning the "
+    "cleaning report (with every automatic decision) and the effective policy. No "
+    "inference, no billing. Input is inline rows (unique_id, ds, y); freq, model, "
+    "clean_series and options are the contract's CleanRequest fields."
+)
+
+FORECAST_DESCRIPTION = (
+    "Forecast one or more series from inline rows (unique_id, ds, y): point forecast plus "
+    "intervals, the data-quality report and the billed usage. The tool takes the request "
+    "fields h, model, freq, level and options; the remaining contract fields (quantile "
+    "policy, covariates, joint groups, ...) are available through REST or the SDK. Two "
+    "limits to know: the model reads only the most recent points of a series, so a longer "
+    "history is truncated by the API and reported (model_input[].truncated plus a "
+    "context_truncated warning) — list_models gives each model's context window; and a "
+    "host tool call cannot carry a large table, so for larger data use the REST or SDK "
+    "batch path: POST /v1/forecast/batch, then poll GET /v1/forecast/batch/{job_id}."
+)
+
+# The contract's horizon bounds (ForecastRequest.h: 1..2048).
+Horizon = Annotated[int, Field(ge=1, le=2048)]
+
+
+def build_server(client: SequenxClient) -> MCPServer:
+    """The MCP server with the three tools, bound to one API client."""
+    server = MCPServer(name="sequenx", version=__version__, instructions=INSTRUCTIONS)
+
+    @server.tool(name="list_models", description=LIST_MODELS_DESCRIPTION)
+    def list_models_tool() -> dict[str, Any]:
+        return tools.list_models(client)
+
+    @server.tool(name="clean_data", description=CLEAN_DATA_DESCRIPTION)
+    def clean_data_tool(
+        series: list[Point],
+        options: dict[str, Any] | None = None,
+        freq: str | None = None,
+        model: str | None = None,
+        clean_series: bool | None = None,
+    ) -> dict[str, Any]:
+        return tools.clean_data(
+            client, series, options=options, freq=freq, model=model, clean_series=clean_series
+        )
+
+    @server.tool(name="forecast", description=FORECAST_DESCRIPTION)
+    def forecast_tool(
+        series: list[Point],
+        h: Horizon,
+        model: str | None = None,
+        freq: str | None = None,
+        level: list[int] | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return tools.forecast(
+            client, series, h=h, model=model, freq=freq, level=level, options=options
+        )
+
+    return server
+
+
+def _quiet_httpx() -> None:
+    """The MCP SDK configures the root logger, so httpx's per-request INFO lines would
+    reach the host's stderr on every tool call. The protocol lives on stdout; these lines
+    are noise there."""
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+
+def main() -> int:
+    """Run the server over stdio (the transport a local MCP host uses)."""
+    api_key = os.environ.get("SEQUENX_API_KEY")
+    if not api_key:
+        print(
+            "set SEQUENX_API_KEY=<sqx_live_... key> to run the SequenxAI MCP server",
+            file=sys.stderr,
+        )
+        return 2
+    base_url = os.environ.get("SEQUENX_API_BASE_URL") or SequenxClient.DEFAULT_BASE_URL
+    _quiet_httpx()
+    client = SequenxClient(api_key, base_url=base_url)
+    try:
+        build_server(client).run()
+    finally:
+        client.close()
+    return 0

sequenx_mcp-0.1.0/src/sequenx_mcp/tools.py

@@ -0,0 +1,97 @@
+"""The three tools: thin adapters over the public API.
+
+Each tool maps one-to-one onto an existing operation (RFC
+``docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md`` §2) and calls the Python
+SDK — there is no second HTTP client and no business logic here. The server
+adds no limits of its own: the control plane owns the point caps and the model
+context, and it reports what it did (``model_input[].truncated`` plus a
+``context_truncated`` warning).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+from sequenx import SequenxClient, SequenxError
+
+from .errors import tool_error
+
+# tool name -> (the SDK method it calls, the contract path, the contract method)
+TOOL_OPERATIONS = {
+    "list_models": ("models", "/models", "get"),
+    "clean_data": ("clean", "/clean", "post"),
+    "forecast": ("forecast", "/forecast", "post"),
+}
+
+
+class Point(BaseModel):
+    """One row of the contract's long table (contract: TimeSeriesPoint)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    unique_id: str
+    ds: str
+    y: float | None
+
+
+def rows_of(series: list[Point]) -> list[dict[str, Any]]:
+    """The rows as the API takes them (the contract's long table)."""
+    return [point.model_dump() for point in series]
+
+
+def list_models(client: SequenxClient) -> dict[str, Any]:
+    """GET /models: the public model catalog for this key."""
+    try:
+        return dict(client.models())
+    except SequenxError as exc:
+        raise tool_error(exc) from exc
+
+
+def clean_data(
+    client: SequenxClient,
+    series: list[Point],
+    options: dict[str, Any] | None = None,
+    freq: str | None = None,
+    model: str | None = None,
+    clean_series: bool | None = None,
+) -> dict[str, Any]:
+    """POST /clean: the free cleaning dry-run (report + effective policy)."""
+    extra: dict[str, Any] = {}
+    if options is not None:
+        extra["options"] = options
+    if freq is not None:
+        extra["freq"] = freq
+    if model is not None:
+        extra["model"] = model
+    if clean_series is not None:
+        extra["clean_series"] = clean_series
+    try:
+        return dict(client.clean(rows_of(series), **extra))
+    except SequenxError as exc:
+        raise tool_error(exc) from exc
+
+
+def forecast(
+    client: SequenxClient,
+    series: list[Point],
+    h: int,
+    model: str | None = None,
+    freq: str | None = None,
+    level: list[int] | None = None,
+    options: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """POST /forecast: a synchronous forecast over inline rows."""
+    extra: dict[str, Any] = {}
+    if model is not None:
+        extra["model"] = model
+    if freq is not None:
+        extra["freq"] = freq
+    if level is not None:
+        extra["level"] = level
+    if options is not None:
+        extra["options"] = options
+    try:
+        return dict(client.forecast(rows_of(series), h=h, **extra))
+    except SequenxError as exc:
+        raise tool_error(exc) from exc

sequenx_mcp-0.1.0/src/sequenx_mcp.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: sequenx-mcp
+Version: 0.1.0
+Summary: MCP server exposing the SequenxAI public API as tools for AI hosts
+Author-email: SequenxAI <lcw_1497007939@163.com>
+License-Expression: LicenseRef-Proprietary
+Keywords: mcp,time-series,forecasting,sequenxai
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: sequenx-ai>=0.1.0
+
+# sequenx-mcp (SequenxAI MCP server)
+
+MCP server that exposes the SequenxAI public API as tools for AI hosts (Claude
+Desktop, Cursor, …). It is a thin adapter: every tool maps one-to-one onto an
+existing operation and calls the Python SDK — there is no second HTTP client and
+no business logic here (see
+[`docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md`](../../docs/plans/phase_3/06-MCP服务器与宿主Agent工具面.md)).
+
+Not published on PyPI yet; it lives in this repository.
+
+## Install
+
+The server depends on the sibling SDK, which is not on PyPI either — install it
+from this repository first:
+
+```bash
+pip install -e packages/sequenx-py
+pip install -e packages/sequenx-mcp
+```
+
+## Run
+
+The server speaks stdio, the transport a local MCP host starts as a child
+process:
+
+```bash
+SEQUENX_API_KEY=sqx_live_... python -m sequenx_mcp
+```
+
+| Variable | Meaning |
+|---|---|
+| `SEQUENX_API_KEY` | The `sqx_live_*` key the tools call with (required). |
+| `SEQUENX_API_BASE_URL` | Base URL override; default `https://api.sequenxai.com/v1`. |
+
+Host configuration (any MCP host that starts stdio servers):
+
+```json
+{
+  "mcpServers": {
+    "sequenx": {
+      "command": "python",
+      "args": ["-m", "sequenx_mcp"],
+      "env": { "SEQUENX_API_KEY": "sqx_live_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Endpoint | What it does |
+|---|---|---|
+| `list_models` | `GET /v1/models` | The public model catalog for the key: ids, the default model, per-model context / horizon limits and capabilities. |
+| `clean_data` | `POST /v1/clean` | The free cleaning dry-run: cleaning report and effective policy. No inference, no billing. Takes `series`, `options`, `freq`, `model` and `clean_series`. |
+| `forecast` | `POST /v1/forecast` | Synchronous forecast over inline rows: points and intervals, data-quality report, billed usage. Takes `series`, `h`, `model`, `freq`, `level` and `options`. |
+
+Input rows are the contract's long table: `unique_id`, `ds`, `y`.
+
+**Limits.** `forecast` takes inline rows only — the public API has no dataset
+upload, so the tool is for small-to-medium series. The model reads only the most
+recent points of a series: a longer history is truncated by the API and
+reported (`model_input[].truncated` plus a `context_truncated` warning), and
+`list_models` gives each model's context window. The server adds no limit of
+its own. For larger data use the REST or SDK batch path:
+`POST /v1/forecast/batch`, then poll `GET /v1/forecast/batch/{job_id}`.
+
+**Errors.** A tool error carries the contract's error body
+(`{"error": {code, message, request_id, category, retryable, details?}}`), so
+the host agent sees a structured error instead of a silent empty answer. The MCP
+framework prefixes the message with its own text, so the envelope travels
+*inside* the error text. `403` is not retried; `429` carries `retry_after` and
+`limit_type` (`rpm` / `daily`) in `details`.
+
+Three codes are the SDK's own, because the contract's code list covers
+server-side failures only: `HTTP_<status>` (a response without a code),
+`REQUEST_FAILED` (a response body the SDK could not read) and `TRANSPORT_ERROR`
+(the request never reached the server).
+
+## Development
+
+```bash
+pip install -e packages/sequenx-py
+pip install -e packages/sequenx-mcp -r packages/sequenx-mcp/requirements-dev.txt
+cd packages/sequenx-mcp
+python -m pytest -q
+python -m ruff check src tests
+```
+
+Gitee Go runs the suite via `scripts/ci/gitee-verify.sh mcp`.
+
+Use a separate virtualenv for this package: `mcp` 2.x installs `httpx2`, and a
+control-plane environment that has `httpx2` next to `httpx` breaks Starlette's
+test client (`services/api` needs `httpx` 1.x).

sequenx_mcp-0.1.0/src/sequenx_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/sequenx_mcp/__init__.py
+src/sequenx_mcp/__main__.py
+src/sequenx_mcp/_version.py
+src/sequenx_mcp/errors.py
+src/sequenx_mcp/server.py
+src/sequenx_mcp/tools.py
+src/sequenx_mcp.egg-info/PKG-INFO
+src/sequenx_mcp.egg-info/SOURCES.txt
+src/sequenx_mcp.egg-info/dependency_links.txt
+src/sequenx_mcp.egg-info/requires.txt
+src/sequenx_mcp.egg-info/top_level.txt
+tests/test_contract_drift.py
+tests/test_server.py
+tests/test_tools.py

sequenx_mcp-0.1.0/src/sequenx_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sequenx_mcp-0.1.0/src/sequenx_mcp.egg-info/requires.txt

@@ -0,0 +1,3 @@
+mcp<3,>=2.3
+pydantic<3,>=2.7
+sequenx-ai>=0.1.0

sequenx_mcp-0.1.0/src/sequenx_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+sequenx_mcp

sequenx_mcp-0.1.0/tests/test_contract_drift.py

@@ -0,0 +1,167 @@
+"""The MCP tools must match the contract (packages/contracts/openapi.yaml).
+
+The tool input schemas are read from the server itself, so this test checks what
+a host actually sees, not a hand-written copy of it.
+"""
+
+import ast
+import asyncio
+import pathlib
+import re
+
+import yaml
+from sequenx import SequenxClient
+from sequenx._endpoints import ENDPOINTS
+
+from sequenx_mcp.server import build_server
+from sequenx_mcp.tools import TOOL_OPERATIONS
+
+_PACKAGE = pathlib.Path(__file__).resolve().parents[1]
+_CONTRACT = (
+    pathlib.Path(__file__).resolve().parents[3]
+    / "packages"
+    / "contracts"
+    / "openapi.yaml"
+)
+
+# The request fields each tool exposes (a subset of the contract's request).
+_TOOL_FIELDS = {
+    "list_models": set(),
+    "clean_data": {"series", "options", "freq", "model", "clean_series"},
+    "forecast": {"series", "h", "model", "freq", "level", "options"},
+}
+
+# The tool descriptions must not hardcode a model id: the catalog is owned by the
+# server and the public model list changes without a version bump (RFC §7.5).
+# Exact ids are matched as whole tokens; the model families are matched as
+# prefixes, so "timestral-209m" is caught too. The list holds the ids the
+# catalog can serve (public and internal); retired names are not part of it.
+_MODEL_IDS = (
+    "omni-1.0",
+    "traffic-1.0",
+    "traffic",
+    "t0-gamma",
+    "hodos",
+)
+_MODEL_PREFIXES = ("chronos-", "timesfm-", "timestral-")
+
+
+def _spec() -> dict:
+    return yaml.safe_load(_CONTRACT.read_text())
+
+
+def _tools() -> dict:
+    server = build_server(SequenxClient("sqx_live_test", base_url="https://api.test/v1"))
+    return {tool.name: tool for tool in asyncio.run(server.list_tools())}
+
+
+def test_the_server_publishes_exactly_the_three_tools():
+    assert set(_tools()) == set(TOOL_OPERATIONS)
+
+
+def test_every_tool_maps_to_an_open_contract_operation():
+    paths = _spec()["paths"]
+    for name, (_, path, method) in TOOL_OPERATIONS.items():
+        assert path in paths, name
+        assert method in paths[path], name
+
+
+def test_the_sdk_serves_the_operation_behind_every_tool():
+    for name, (method_name, path, method) in TOOL_OPERATIONS.items():
+        served = [
+            spec
+            for spec in ENDPOINTS.values()
+            if spec.method.lower() == method and spec.path == path
+        ]
+        assert served, name
+        assert callable(getattr(SequenxClient, method_name)), name
+
+
+def test_every_tool_calls_the_sdk_method_it_claims():
+    """The tool function and the endpoint it claims must not drift apart."""
+    tree = ast.parse((_PACKAGE / "src" / "sequenx_mcp" / "tools.py").read_text())
+    calls: dict[str, set[str]] = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.FunctionDef):
+            continue
+        calls[node.name] = {
+            call.func.attr
+            for call in ast.walk(node)
+            if isinstance(call, ast.Call)
+            and isinstance(call.func, ast.Attribute)
+            and isinstance(call.func.value, ast.Name)
+            and call.func.value.id == "client"
+        }
+    for name, (method_name, _, _) in TOOL_OPERATIONS.items():
+        assert method_name in calls[name], name
+
+
+def test_the_tool_input_fields_are_the_declared_ones_and_exist_in_the_contract():
+    schemas = _spec()["components"]["schemas"]
+    tools = _tools()
+    for name in TOOL_OPERATIONS:
+        tool_props = set(tools[name].input_schema.get("properties", {}))
+        assert tool_props == _TOOL_FIELDS[name], name
+        if not _TOOL_FIELDS[name]:
+            continue
+        request_schema = "CleanRequest" if name == "clean_data" else "ForecastRequest"
+        properties = set(schemas[request_schema]["properties"])
+        assert tool_props <= properties, name
+        # Every field the contract requires must be expressible by the tool.
+        assert set(schemas[request_schema]["required"]) <= tool_props, name
+
+
+def test_the_horizon_bounds_match_the_contract():
+    contract_h = _spec()["components"]["schemas"]["ForecastRequest"]["properties"]["h"]
+    tool_h = _tools()["forecast"].input_schema["properties"]["h"]
+    assert tool_h.get("minimum") == contract_h["minimum"]
+    assert tool_h.get("maximum") == contract_h["maximum"]
+
+
+def test_the_row_model_matches_the_contract_point():
+    schemas = _spec()["components"]["schemas"]["TimeSeriesPoint"]
+    point = _tools()["forecast"].input_schema["$defs"]["Point"]
+    assert set(point["required"]) == set(schemas["required"])
+    assert set(point["properties"]) == set(schemas["properties"])
+
+
+def _names_a_model_id(text: str) -> str | None:
+    """The model id the text names first, if any.
+
+    Exact ids match as whole tokens (so "traffic" also trips on ordinary prose —
+    a loud, cheap false positive); the model families match as prefixes. The
+    match that starts earliest in the text wins.
+    """
+    matches: list[tuple[int, str]] = []
+    for model_id in _MODEL_IDS:
+        found = re.search(rf"(?<![\w-]){re.escape(model_id)}(?![\w-])", text)
+        if found:
+            matches.append((found.start(), model_id))
+    for prefix in _MODEL_PREFIXES:
+        found = text.find(prefix)
+        if found >= 0:
+            matches.append((found, prefix))
+    return min(matches)[1] if matches else None
+
+
+def test_no_tool_description_names_a_model_id():
+    for name, tool in _tools().items():
+        assert _names_a_model_id(tool.description or "") is None, name
+
+
+def test_the_server_instructions_name_no_model_id():
+    server = build_server(SequenxClient("sqx_live_test", base_url="https://api.test/v1"))
+    assert _names_a_model_id(server.instructions or "") is None
+
+
+def test_the_client_side_codes_are_outside_the_contract_list():
+    """The SDK adds codes for failures no contract code covers (server-side only)."""
+    listed = _spec()["components"]["schemas"]["ErrorDetail"]["x-error-codes"]
+    contract_codes = {entry["code"] for entry in listed}
+    for code in ("HTTP_404", "REQUEST_FAILED", "TRANSPORT_ERROR"):
+        assert code not in contract_codes
+
+
+def test_the_guard_reports_the_id_the_text_names_first():
+    assert _names_a_model_id("timestral-209m and omni-1.0") == "timestral-"
+    assert _names_a_model_id("omni-1.0 then timestral-209m") == "omni-1.0"

sequenx_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,30 @@
+"""The command line contract of the server."""
+
+from mcp.server.mcpserver import MCPServer
+from sequenx import SequenxClient
+
+from sequenx_mcp.server import main
+
+
+def test_without_a_key_the_server_refuses_to_start(monkeypatch, capsys):
+    monkeypatch.delenv("SEQUENX_API_KEY", raising=False)
+    assert main() == 2
+    assert "SEQUENX_API_KEY" in capsys.readouterr().err
+
+
+def test_with_a_key_the_server_runs_over_stdio(monkeypatch):
+    monkeypatch.setenv("SEQUENX_API_KEY", "sqx_live_test")
+    monkeypatch.delenv("SEQUENX_API_BASE_URL", raising=False)
+    ran = []
+    monkeypatch.setattr(MCPServer, "run", lambda self, *a, **kw: ran.append(True))
+    assert main() == 0
+    assert ran == [True]
+
+
+def test_the_client_is_closed_when_the_server_stops(monkeypatch):
+    monkeypatch.setenv("SEQUENX_API_KEY", "sqx_live_test")
+    closed = []
+    monkeypatch.setattr(MCPServer, "run", lambda self, *a, **kw: None)
+    monkeypatch.setattr(SequenxClient, "close", lambda self: closed.append(True))
+    assert main() == 0
+    assert closed == [True]

sequenx_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,264 @@
+import json
+
+import httpx
+import pytest
+from mcp.server.mcpserver.exceptions import ToolError
+
+from sequenx_mcp.server import build_server
+from sequenx_mcp.tools import Point, clean_data, forecast, list_models
+
+SERIES = [Point(unique_id="m-1", ds="2026-01-01T00:00:00Z", y=1.5)]
+
+MODEL_LIST = {
+    "default": "omni-1.0",
+    "models": [{"id": "omni-1.0", "name": "Omni 1.0"}],
+    "request_id": "req_1",
+}
+
+
+def test_list_models_returns_the_catalog(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/models"
+        return httpx.Response(200, json=MODEL_LIST)
+
+    assert list_models(make_client(handler)) == MODEL_LIST
+
+
+def test_clean_data_calls_the_clean_endpoint(make_client):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["method"], seen["path"] = request.method, request.url.path
+        seen["body"] = request.read()
+        return httpx.Response(
+            200,
+            json={
+                "request_id": "req_2",
+                "freq": "D",
+                "cleaning_report": {"decisions": []},
+                "effective_policy": {"preset": "default"},
+            },
+        )
+
+    out = clean_data(make_client(handler), SERIES)
+    assert seen["method"] == "POST" and seen["path"] == "/v1/clean"
+    assert b'"unique_id"' in seen["body"]
+    assert out["request_id"] == "req_2"
+
+
+def test_forecast_calls_the_forecast_endpoint_with_a_key(make_client):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["method"], seen["path"] = request.method, request.url.path
+        seen["key"] = request.headers.get("idempotency-key")
+        seen["body"] = request.read()
+        return httpx.Response(
+            200,
+            json={
+                "request_id": "req_3",
+                "model_used": "omni-1.0",
+                "forecast": [],
+                "data_quality": {"status": "ok", "missing_ratio": 0.0},
+                "usage": {"series_count": 1, "input_data_points": 1, "latency_ms": 12},
+            },
+        )
+
+    out = forecast(make_client(handler), SERIES, h=24, model="omni-1.0")
+    assert seen["method"] == "POST" and seen["path"] == "/v1/forecast"
+    assert seen["key"]
+    assert b'"h":24' in seen["body"] and b"omni-1.0" in seen["body"]
+    assert out["model_used"] == "omni-1.0"
+
+
+def test_an_api_error_becomes_a_tool_error_with_the_contract_body(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            422,
+            json={
+                "error": {
+                    "code": "SERIES_TOO_LONG",
+                    "message": "too long",
+                    "request_id": "req_x",
+                    "details": {"field": "series"},
+                }
+            },
+        )
+
+    with pytest.raises(ToolError) as exc:
+        forecast(make_client(handler), SERIES, h=8)
+    body = json.loads(str(exc.value))
+    assert body["error"]["code"] == "SERIES_TOO_LONG"
+    assert body["error"]["message"] == "too long"
+    assert body["error"]["request_id"] == "req_x"
+    assert body["error"]["details"] == {"field": "series"}
+
+
+def test_a_rate_limit_error_carries_the_retry_after(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            429,
+            headers={"retry-after": "30"},
+            json={
+                "error": {
+                    "code": "RATE_LIMIT_EXCEEDED",
+                    "message": "slow down",
+                    "request_id": "req_y",
+                }
+            },
+        )
+
+    # max_retries=0: the SDK would otherwise honour Retry-After and wait.
+    with pytest.raises(ToolError) as exc:
+        list_models(make_client(handler, max_retries=0))
+    body = json.loads(str(exc.value))
+    assert body["error"]["code"] == "RATE_LIMIT_EXCEEDED"
+    assert body["error"]["details"]["retry_after"] == 30.0
+
+
+def test_a_long_history_is_left_to_the_api(make_client):
+    """The server adds no limit of its own: the control plane owns the caps."""
+    rows = [Point(unique_id="m-1", ds="2026-01-01", y=1.0) for _ in range(5000)]
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["rows"] = request.read().count(b"unique_id")
+        return httpx.Response(200, json={"request_id": "r", "forecast": []})
+
+    forecast(make_client(handler), rows, h=8)
+    assert seen["rows"] == 5000
+
+
+def test_the_server_exposes_exactly_three_tools(make_client):
+    import asyncio
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=MODEL_LIST)
+
+    server = build_server(make_client(handler))
+    tools = asyncio.run(server.list_tools())
+    assert {tool.name for tool in tools} == {"list_models", "clean_data", "forecast"}
+    forecast_tool = next(tool for tool in tools if tool.name == "forecast")
+    assert "batch" in forecast_tool.description
+    assert "context_truncated" in forecast_tool.description
+
+
+def test_a_tool_call_returns_the_payload(make_client):
+    import asyncio
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=MODEL_LIST)
+
+    server = build_server(make_client(handler))
+    result = asyncio.run(server.call_tool("list_models", {}))
+    assert result.is_error is False
+    assert result.structured_content == MODEL_LIST
+
+
+def test_a_transport_failure_carries_the_sdk_code(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("boom")
+
+    client = make_client(handler, max_retries=0)
+    with pytest.raises(ToolError) as exc:
+        list_models(client)
+    body = json.loads(str(exc.value))
+    assert body["error"]["code"] == "TRANSPORT_ERROR"
+    assert "boom" in body["error"]["message"]
+
+
+def test_the_optional_request_fields_reach_the_api(make_client):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = request.read()
+        return httpx.Response(200, json={"request_id": "r", "forecast": []})
+
+    client = make_client(handler)
+    forecast(client, SERIES, h=24, level=[80, 90])
+    assert b'"level":[80,90]' in seen["body"]
+    clean_data(client, SERIES, freq="1h", model="omni-1.0", clean_series=False)
+    assert b'"freq":"1h"' in seen["body"]
+    assert b'"model":"omni-1.0"' in seen["body"]
+    assert b'"clean_series":false' in seen["body"]
+
+
+def test_an_error_without_a_body_code_keeps_the_http_status(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"detail": "not found"})
+
+    with pytest.raises(ToolError) as exc:
+        list_models(make_client(handler))
+    body = json.loads(str(exc.value))
+    assert body["error"]["code"] == "HTTP_404"
+
+
+def test_the_error_body_keeps_the_contract_detail_fields(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            422,
+            json={
+                "error": {
+                    "code": "SERIES_TOO_LONG",
+                    "message": "too long",
+                    "request_id": "req_x",
+                    "category": "limit_exceeded",
+                    "retryable": False,
+                }
+            },
+        )
+
+    with pytest.raises(ToolError) as exc:
+        forecast(make_client(handler), SERIES, h=8)
+    body = json.loads(str(exc.value))
+    assert body["error"]["category"] == "limit_exceeded"
+    assert body["error"]["retryable"] is False
+
+
+def test_a_rate_limit_error_carries_the_retry_hints(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            429,
+            headers={"retry-after": "30", "x-ratelimit-limit-type": "daily"},
+            json={"error": {"code": "POINTS_EXCEEDED", "message": "m", "request_id": "r"}},
+        )
+
+    with pytest.raises(ToolError) as exc:
+        list_models(make_client(handler, max_retries=0))
+    body = json.loads(str(exc.value))
+    assert body["error"]["details"]["retry_after"] == 30.0
+    assert body["error"]["details"]["limit_type"] == "daily"
+
+
+def test_a_client_side_failure_is_not_reported_as_a_transport_error(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"")
+
+    with pytest.raises(ToolError) as exc:
+        list_models(make_client(handler))
+    body = json.loads(str(exc.value))
+    assert body["error"]["code"] == "REQUEST_FAILED"
+
+
+def test_a_non_json_body_is_reported_as_the_contract_envelope(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"<html>not json</html>")
+
+    with pytest.raises(ToolError) as exc:
+        list_models(make_client(handler))
+    body = json.loads(str(exc.value))
+    assert body["error"]["code"] == "REQUEST_FAILED"
+    assert "non-JSON body" in body["error"]["message"]
+
+
+def test_the_error_body_omits_absent_detail_fields(make_client):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            422, json={"error": {"code": "SERIES_TOO_SHORT", "message": "m", "request_id": "r"}}
+        )
+
+    with pytest.raises(ToolError) as exc:
+        forecast(make_client(handler), SERIES, h=8)
+    body = json.loads(str(exc.value))
+    assert "category" not in body["error"]
+    assert "retryable" not in body["error"]