Metadata-Version: 2.4
Name: sequenx-mcp
Version: 0.1.1
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)).

Published on PyPI as `sequenx-mcp` (it depends on the SDK, `sequenx-ai`, which
comes in automatically).

## Install

```bash
pip install sequenx-mcp
```

To work on the server itself, install both packages from this repository in
editable mode:

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