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_rateconfidence_level: 置信水平,默认 0.95use_trend_blend: 是否在结构模型与近年加权均值间做组合,默认 truerecent_window: 近年加权均值窗口(年),默认 7holdout_years: 滚动交叉验证留出年数,默认 5forecast_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. 准备
- 在 pypi.org 注册账号。
- 创建 API Token(Account settings → API tokens,scope 选整个账号或项目)。
- 修改
pyproject.toml中的authors、project.urls为真实信息。 - 包名唯一:
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
Metadata
Release files for annual-series-forecast-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| annual_series_forecast_mcp-0.1.0.tar.gz | 14.1 kB | Without provenance | Details for annual_series_forecast_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| annual_series_forecast_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for annual_series_forecast_mcp-0.1.0-py3-none-any.whl |
Total release size: 27.3 kB
Release files / annual_series_forecast_mcp-0.1.0.tar.gz
| Download URL | annual_series_forecast_mcp-0.1.0.tar.gz |
|---|---|
| Size | 14.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7e78e6af565151a7cbded65e1d0f860e473d79ef6a35e6b5361990e376f795d0
|
|
BLAKE2b-256 checksum How to use checksums |
18b92a0b9720f952d3da54ef235d15bef5e2d06db3267530dabf40d37aa74909
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / annual_series_forecast_mcp-0.1.0-py3-none-any.whl
| Download URL | annual_series_forecast_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d35ab15d9c366b9b0a8df2e2e47566a489a5e31a81ef57b0f3679475491f40b4
|
|
BLAKE2b-256 checksum How to use checksums |
87fdb1a3c792828a77df423a0840d34c90ded902cb47cc2be2b362dd46888e36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for annual-series-forecast-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.