sequenx-mcp 0.1.0__py3-none-any.whl

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/__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/_version.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+sequenx_mcp/__init__.py,sha256=uDWjETMHAREI7GEutCkQUMeSUKYEcNU3jyKbWHI4FD4,199
+sequenx_mcp/__main__.py,sha256=7PUkI_f04uChGSNpjPu-6l7pdCEkK84spTRzKZagAJY,147
+sequenx_mcp/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+sequenx_mcp/errors.py,sha256=oCUpvdhAVY1-cL36Zxovp2NS7y6V-MOcpWsyn0_RGmU,2854
+sequenx_mcp/server.py,sha256=EFeJvwsrRwHADbtVH_DhLv56mUxu0TmbNK0JacE6KJY,4548
+sequenx_mcp/tools.py,sha256=B7fWJOMgdDGmUzwZX74VHchT9rIZQNDKlHCzB3fMCfs,2974
+sequenx_mcp-0.1.0.dist-info/METADATA,sha256=60fMaPXf_Q8umMeqQQY6Zq3kqW6xADLvAnD_PQcAqe0,4402
+sequenx_mcp-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sequenx_mcp-0.1.0.dist-info/top_level.txt,sha256=jP7ZO66U7u9jSljIRK7_notOIeo1uH_Y5xHIc0P8QLo,12
+sequenx_mcp-0.1.0.dist-info/RECORD,,

sequenx_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sequenx_mcp-0.1.0.dist-info/top_level.txt

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