Redegades Forecast MCP

重新定义MCP预测

MCP服务，用于交付周期和销售预测，具有受控的数据库访问、预定的预测生成和快速检索预先计算的输出。

范围

该存储库是独立的预测MCP模块（旨在作为主平台中的Git子模块）。它实现了：

• 带查询允许列表和参数筛选的受控DB API包装器。
• 用于本地开发和测试的虚拟数据库。
• 统计基线预测。
• 蒙特卡罗分位数预测(P10, P50, P90).
• 标准预测响应结构(timestamp +值）。
• 用于预计算预测的调度程序服务（cron风格），而不是按需运行时计算。

架构决策（已商定）

1. 将单独的预测MCP服务器作为模块化服务运行。
2. 使用具有安全查询ID的受控DB执行层，而不是任意SQL输入。
3. 根据时间表预计算预测并存储 forecast_outputs.
4. 代理/UI读取预先计算的值（低延迟的默认单行响应）。
5. 保持实现Docker化，以实现本地/产品奇偶校验。

数据源

生产来源

• MS SQL Server数据湖。
• 主要交付周期提取查询存储在 sql/ic_orders_lead_time.sql.
• 查询基于 DATA_LAKE.IC_ORDERS 和 DATA_LAKE.PART_MASTER.

当地发展来源

• SQLite虚拟模式(ic_orders, part_master, sales_history, forecast_outputs).
• 种子使用 scripts/init_dummy_db.py.

仓库的规划

redegades-forecast-mcp/
  mcp_service/
    api.py
    config.py
    database.py
    models.py
    query_filter.py
    query_registry.py
    scheduler.py
    forecasting/
      baseline.py
      monte_carlo.py
      jobs.py
  scripts/
    init_dummy_db.py
    run_forecast_job.py
  sql/
    ic_orders_lead_time.sql
  docker-compose.yml
  Dockerfile
  requirements.txt

快速入门（本地）

1. 复制环境文件。

cp .env.example .env

1. 构建和运行服务。

docker compose up --build

1. API端点：

• GET http://localhost:8080/ （重定向到Swagger UI /docs)
• GET http://localhost:8080/health
• GET http://localhost:8080/v1/queries
• POST http://localhost:8080/v1/query/execute
• GET http://localhost:8080/v1/forecast/latest?domain=lead_time&series_key=__ALL__

预测端点参数

对于 GET /v1/forecast/latest:

• domain （必填）：

- lead_time - sales

• series_key （可选，默认 __ALL__):

- __ALL__ 用于总体预测 - 特定零件号（对于虚拟数据： PART-0001, PART-0002, ...)

• limit （可选，默认 1):

- 从最新预计算运行返回的点数。

示例：

curl "http://localhost:8080/v1/forecast/latest?domain=lead_time&series_key=__ALL__&limit=1"

curl "http://localhost:8080/v1/forecast/latest?domain=sales&series_key=PART-0001&limit=6"

非Docker本地运行

1. 安装依赖项。

pip install -r requirements.txt

1. 初始化虚拟数据。

python scripts/init_dummy_db.py

1. 手动运行一个预测作业。

python scripts/run_forecast_job.py

1. 启动API。

uvicorn mcp_service.api:app --host 0.0.0.0 --port 8080

1. 启动调度程序（独立终端）。

python -m mcp_service.scheduler

1. 为MCP客户端启动MCP服务器（stdio传输）。

python -m mcp_service.mcp_server

安全查询模型

此服务阻止直接执行任意SQL。查询请求必须：

1. 使用分配列表 query_id 从 mcp_service/query_registry.py.
2. 仅提供预期参数。
3. 通过参数过滤检查 mcp_service/query_filter.py.

当前查询有效负载合同：

• ic_orders_lead_time_extract

- 必需的 params: start_date - 可选的 params: part_no - 例子：

  {
    "query_id": "ic_orders_lead_time_extract",
    "params": { "start_date": "2024-01-01", "part_no": "PART-0001" },
    "limit": 100
  }

• sales_monthly_history

- 必需的 params: start_date - 可选的 params: part_no - 例子：

  {
    "query_id": "sales_monthly_history",
    "params": { "start_date": "2024-01-01" },
    "limit": 100
  }

• precomputed_forecast_values

- 必需的 params: domain, series_key - 可选的 params：无 - 例子：

  {
    "query_id": "precomputed_forecast_values",
    "params": { "domain": "lead_time", "series_key": "__ALL__" },
    "limit": 30
  }

预测策略

交付周期预测

• 已关闭订单的历史序列(date_entered 到 complete_date).
• 产品级别预测(series_key = PART_NO)和骨料(__ALL__).
• 统计基线+蒙特卡洛分位数(P10, P50, P90).

销售预测

• 每月数量汇总 sales_history.
• 产品水平和总体预测。
• 相同的基线+分位数输出合约。

标准预测响应

示例响应来自 GET /v1/forecast/latest:

{
  "domain": "lead_time",
  "series_key": "__ALL__",
  "generated_at": "2026-02-19T03:00:00",
  "source": "precomputed_table",
  "points": [
    {
      "timestamp": "2026-02-20T00:00:00",
      "value": 17.8,
      "p10": 13.5,
      "p50": 17.7,
      "p90": 22.1
    }
  ]
}

安全护栏

• 没有任意SQL端点。
• 查询ID分配列表和参数架构强制。
• 在请求参数中检测到危险的SQL令牌。
• 针对代理消费重新聚焦的API表面。
• 数据访问层和预测执行层之间的分离。

UI集成说明

此MCP支持计划平台报告选项卡：

• 从预先计算的预测行读取KPI卡。
• 交付周期和销售额的预测部分。
• 嵌入式代理面板可以快速请求最新的预测记录。
• 可选的右键单击/Ask Agent交互应调用MCP端点进行上下文检索。

任务状态

• \[x\] 使用查询过滤器实现DB API包装器。
• \[x\] 创建用于测试的虚拟数据库。
• \[x\] 实施初始预测脚本（统计基线）。
• \[x\] 添加蒙特卡洛模块(P10, P50, P90).
• \[x\] 定义标准预测响应结构。
• \[x\] 将MCP服务进行Docker化，并构建集成。

后续实施步骤

1. 用VPN访问的MS SQL数据湖连接替换SQLite虚拟源。
2. 通过环境变量映射生产模式名称和凭据。
3. 与Jason一起验证KPI定义（最终指标合同）。
4. 在生产推出之前添加模型回溯测试和错误跟踪。