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：

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

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

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

方式二：pip 安装

pip install annual-series-forecast-mcp
annual-series-forecast-mcp

方式三：源码开发

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

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

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

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

使用 python -m 的配置示例

{
  "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 示例:

[
  {"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 注册账号。
2. 创建 API Token（Account settings → API tokens，scope 选整个账号或项目）。
3. 修改 pyproject.toml 中的 authors、project.urls 为真实信息。
4. 包名唯一：annual-series-forecast-mcp 若已被占用，需改名后发布。

2. 构建与上传（uv）

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 自带发布：

uv publish

3. 验证

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

4. 版本更新

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

许可证

MIT License