Metadata-Version: 2.4
Name: annual-series-forecast-mcp
Version: 0.1.0
Summary: 年度时间序列预测 MCP - 基于 ARIMA / 指数平滑的同比增速与水平值联合预测
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/your-org/annual-series-forecast-mcp
Project-URL: Repository, https://github.com/your-org/annual-series-forecast-mcp
Project-URL: Issues, https://github.com/your-org/annual-series-forecast-mcp/issues
Keywords: time-series,forecasting,MCP,ARIMA,exponential-smoothing,annual
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: statsmodels>=0.14.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# Annual Series Forecast MCP

年度时间序列预测 MCP (Model Context Protocol)。基于 ARIMA 与 Holt 指数平滑，对按年排列的序列做同比增速与水平值联合预测。

适用于含 `year`、`growth_rate`（同比增速%）及可选 `value`（水平绝对值）的年度数据，例如宏观经济指标、行业统计等。测试用例中的 GDP 等指标只是典型场景之一。

与 `time-series-forecast-mcp` 的区别：本服务面向「年度 + 增速/水平值」结构化输入，内置模型族选择与近年加权均值组合；后者面向原始数值序列，提供 AR/MA/ARIMA/GARCH/指数平滑等多种单模型。

## 安装与运行

### 方式一：uvx（推荐，无需手动安装）

需先安装 [uv](https://docs.astral.sh/uv/)：

```bash
# 本地试跑（stdio MCP 服务）
uvx annual-series-forecast-mcp
```

发布到 PyPI 后，其他机器可直接用包名运行；未发布前可指定源码路径：

```bash
uvx --from /path/to/annual-series-forecast-mcp annual-series-forecast-mcp
```

### 方式二：pip 安装

```bash
pip install annual-series-forecast-mcp
annual-series-forecast-mcp
```

### 方式三：源码开发

```bash
cd annual-series-forecast-mcp
pip install -e ".[test]"
python -m annual_series_forecast_mcp
```

### Cursor / Claude Desktop 配置（uvx）

配置文件路径示例：
- Windows: `%USERPROFILE%\.cursor\mcp.json`
- macOS/Linux: `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "annual-series-forecast": {
      "command": "uvx",
      "args": ["annual-series-forecast-mcp"]
    }
  }
}
```

若使用本地源码目录（未发布到 PyPI）：

```json
{
  "mcpServers": {
    "annual-series-forecast": {
      "command": "uvx",
      "args": [
        "--from",
        "C:/local/code/ai-base-3/annual-series-forecast-mcp",
        "annual-series-forecast-mcp"
      ]
    }
  }
}
```

### 使用 python -m 的配置示例

```json
{
  "mcpServers": {
    "annual-series-forecast": {
      "command": "python",
      "args": ["-m", "annual_series_forecast_mcp"]
    }
  }
}
```

### 工具列表

#### forecast_next_year

基于历史年度时间序列预测下一期。

**参数**:

- `history`: 历史记录列表（按年份升序），每项含 `year`；有水平值时含 `value`，否则含 `growth_rate`
- `confidence_level`: 置信水平，默认 0.95
- `use_trend_blend`: 是否在结构模型与近年加权均值间做组合，默认 true
- `recent_window`: 近年加权均值窗口（年），默认 7
- `holdout_years`: 滚动交叉验证留出年数，默认 5
- `forecast_level`: 是否预测水平值；`null` 时根据最近一期是否有 `value` 自动判断
- `p`, `d`, `q`: 手动指定 ARIMA 阶数（可选）

**history 示例**:

```json
[
  {"year": 2018, "value": 20842281, "growth_rate": 9.6},
  {"year": 2019, "value": 24348689, "growth_rate": 8.6},
  {"year": 2020, "value": 25328231, "growth_rate": 0.4},
  {"year": 2021, "value": 27739726, "growth_rate": 8.2},
  {"year": 2022, "value": 27508021, "growth_rate": -3.0},
  {"year": 2023, "value": 30722854, "growth_rate": 9.1},
  {"year": 2024, "value": 31563658, "growth_rate": 5.2}
]
```

**返回**:

- `target_year`: 预测目标年
- `forecast`: `growth_rate` / `value` 点预测及置信区间
- `models`: 选中模型参数
- `diagnostics`: 样本量、模型族、滚动 MAE 等

仅预测下一年。需要多年预测时，请多次调用并将上年预测追加到 `history`。

注：输入字段 `gdp` 可作为 `value` 的别名兼容旧数据格式。

## 依赖

- fastmcp >= 2.0.0
- numpy >= 1.24.0
- statsmodels >= 0.14.0

## 发布到 PyPI（维护者）

### 1. 准备

1. 在 [pypi.org](https://pypi.org) 注册账号。
2. 创建 API Token（Account settings → API tokens，scope 选整个账号或项目）。
3. 修改 `pyproject.toml` 中的 `authors`、`project.urls` 为真实信息。
4. **包名唯一**：`annual-series-forecast-mcp` 若已被占用，需改名后发布。

### 2. 构建与上传（uv）

```bash
cd annual-series-forecast-mcp

# 安装构建工具
uv pip install build twine

# 运行测试
uv run pytest tests/

# 构建 wheel / sdist
uv run python -m build

# 上传到 PyPI（会提示输入 __token__ 和密码即 API Token）
uv run twine upload dist/*
```

或使用 uv 自带发布：

```bash
uv publish
```

### 3. 验证

```bash
# 另一台机器或新环境
uvx annual-series-forecast-mcp --help
# 或试跑 MCP（会等待 stdio 输入）
uvx annual-series-forecast-mcp
```

### 4. 版本更新

修改 `pyproject.toml` 中的 `version`（如 `0.1.1`），重新 `build` 与 `upload`。已发布的版本号不可重复使用。

## 许可证

MIT License
