futures-kb
It is an MCP server that supplies OpenClaw/agents with compact futures market data, manual fundamental metrics, controlled crawler runs, research search, and persistent report storage/retrieval for SH, V, and JM.
Get a compact daily report context packet for caustic soda, PVC, and coking coal (daily_report_context).
Submit structured manual data such as spot prices, inventory, and operating rates (manual_data_submit).
Run allowlisted local market-data crawlers for a symbol and trade date (market_run_crawler).
Save generated reports outside the model context, with upsert behavior (report_save).
List past reports with metadata and short summaries, optionally filtered by date, symbol, or query (report_list).
Read a selected past report with a token budget and offset-based continuation (report_read).
Search news, announcements, and research notes; returns at most three short excerpts with citations (research_search).
Avoids bloating the model context by returning only counts, statuses, short summaries, and explicitly requested report chunks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@futures-kb get daily report context for caustic soda, PVC, coking coal"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Futures AI KB
一个面向 OpenClaw 的期货数据与往期报告 MCP 服务。 将烧碱、PVC、焦煤行情、手工数据、资讯和报告保存在模型上下文之外,由 AI 按需调用。
当前版本:v0.2.9 MVP
适用品种:烧碱 SH、PVC V、焦煤 JM
为什么需要它
让 OpenClaw 每天生成期货报告时,如果直接读取完整数据库、爬虫结果和往期报告,会导致:
上下文持续膨胀。
token 成本随天数增长。
旧数据污染当天分析。
模型自行计算指标,容易出现口径错误。
Futures AI KB 把这些数据放在独立服务中,只向 OpenClaw 返回当前任务所需的最小数据包。
Related MCP server: SolidRockQuant
核心特性
SQLite 行情、手工指标、资讯、爬虫运行记录和往期报告存储。
FuturesIntelTool SQLite 和日报目录只读兼容。
烧碱、PVC、焦煤日线特征计算。
MA5、MA20、1/5 日涨跌、持仓变化、成交量 Z-Score、基差和异常标记。
MCP stdio 与 Streamable HTTP。
FastAPI 数据导入和查询接口。
受控爬虫执行,只允许本地白名单命令。
往期报告持久化,但普通日报不自动读取。
AI 通过
report_list和report_read按需查询历史。OpenClaw Skill 和 Automation 接入示例。
单元测试、API 测试和真实 MCP stdio 集成测试。
架构
flowchart LR
C[Crawler] --> API[FastAPI Service]
M[Manual Data] --> API
R[Research Notes] --> API
API --> DB[(SQLite)]
DB --> F[Feature Engine]
DB --> PR[(Past Reports)]
F --> MCP[MCP Server]
PR --> MCP
MCP --> OC[OpenClaw]
SK[OpenClaw Skill] --> OC
OC --> OUT[Daily Report]
OUT --> PR设计原则:
原始行情、爬虫结果、新闻全文不进入模型上下文。
所有指标由确定性代码计算。
MCP 返回短字段、短摘要和引用。
每份日报使用独立会话。
往期报告只在模型明确调用时加载。
报告保存后,不自动拼接到下一次日报。
MCP 工具
工具 | 作用 | 默认是否进入上下文 |
| 返回当天精简日报数据包 | 是,报告任务调用后 |
| 提交现货、库存、开工率等结构化数据 | 只返回接收数量 |
| 运行本地白名单爬虫 | 只返回运行状态 |
| 检索新闻、公告和研报摘要 | 最多三条短摘要 |
| 保存完整往期报告 | 不返回正文 |
| 返回往期报告目录和摘要 | 只在 AI 调用时 |
| 按 token 预算读取指定报告 | 只在 AI 调用时 |
快速开始
环境要求
Python 3.12+
OpenClaw,可选;只使用 HTTP API 时不需要
安装和测试
git clone <your-repository-url>
cd futures-ai-kb
uv sync --extra dev
uv run pytest生成本地演示数据
uv run futures-kb-seed --date 2026-09-19 --days 60启动 HTTP API
uv run futures-kb-api默认地址:http://127.0.0.1:8787
启动 MCP Server
stdio:
uv run futures-kb-mcpStreamable HTTP:
uv run futures-kb-mcp --transport streamable-http --host 127.0.0.1 --port 8790接入 OpenClaw
先复制爬虫配置模板:
Copy-Item config\crawlers.example.json config\crawlers.local.json注册 stdio MCP:
$repo = (Resolve-Path .).Path
$python = Join-Path $repo ".venv\Scripts\python.exe"
openclaw mcp add futures-kb `
--command $python `
--arg '-m' `
--arg 'futures_kb.mcp_server' `
--cwd $repo `
--include 'daily_report_context,manual_data_submit,market_run_crawler,research_search,report_save,report_list,report_read'
openclaw mcp doctor futures-kb --probe安装 Skill:
skills/futures-daily-report/SKILL.md将整个 skills/futures-daily-report 目录放到 OpenClaw 的 workspace skill 根目录。
完整说明见 OpenClaw 接入文档。
日报和往期报告流程
1. OpenClaw 调用 daily_report_context
2. OpenClaw 生成日报
3. OpenClaw 调用 report_save
4. 完整报告写入 SQLite
5. 日报会话结束并归档
用户以后询问历史:
6. OpenClaw 调用 report_list
7. 选择 report_id
8. OpenClaw 调用 report_read
9. 根据 next_offset 决定是否需要继续读取daily_report_context 不返回往期报告正文。
只有 report_read 会按需返回指定报告,默认单次最多 2,000 token。
HTTP API
行情
POST /api/v1/market/bars手工数据
POST /api/v1/manual-data资讯
POST /api/v1/research爬虫
POST /api/v1/crawlers/{source}/run?trade_date=2026-09-19日报数据包
GET /api/v1/report-context?trade_date=2026-09-19&symbols=SH,V,JM往期报告
POST /api/v1/reports
GET /api/v1/reports
GET /api/v1/reports/{report_id}配置
环境变量 | 默认值 | 说明 |
|
| SQLite 数据库路径 |
|
| 爬虫白名单配置 |
|
| 爬虫原始输出目录 |
| 空 | 设置后 HTTP 写接口和报告接口要求 |
|
| API 监听地址 |
|
| API 监听端口 |
安全说明
默认仅监听
127.0.0.1。不要把无认证 API 暴露到公网。
爬虫命令来自本地受信任配置,OpenClaw 不能提交任意命令。
不建议让模型直接执行数据库 SQL 或任意文件路径。
不要把真实 Cookie、API Key 和交易账户凭据提交到 Git。
本项目的分析输出不构成投资建议。
更多信息见 SECURITY.md。
测试
uv run pytest当前测试覆盖:
行情和手工数据幂等写入。
指标和日报数据包。
FastAPI 接口。
爬虫白名单和标准输出导入。
MCP 工具发现和调用。
真实 MCP stdio 子进程连接。
往期报告保存、列表、按需读取和 token 截断。
日报上下文不自动包含往期报告。
项目结构
src/futures_kb/ 核心服务、存储、指标、API、MCP
skills/ OpenClaw Skill
config/ 爬虫配置模板
docs/ 架构、流程和接入文档
examples/ 本地假爬虫
tests/ 单元、API、MCP 和 stdio 集成测试文档
Roadmap
PostgreSQL/TimescaleDB 存储后端。
新闻和研报混合检索。
Reranker 和引用评估。
更完整的合约换月和连续合约处理。
Docker Compose。
Web 管理界面。
数据源插件接口。
报告质量评测集。
免责声明
本项目用于数据工程、报告自动化和研究辅助,不构成投资建议。期货市场风险较高,任何交易决策都应由使用者独立判断并自行承担风险。
License
English Summary
Futures AI KB is an external market-data and report-retrieval service for OpenClaw. It keeps raw futures data, crawler output, research articles, and historical reports outside the model context. OpenClaw receives a compact computed daily packet and reads selected past reports only through explicit MCP calls.
Supported symbols:
SH: Caustic soda futuresV: PVC futuresJM: Coking coal futures
Core stack: Python, FastAPI, SQLite, MCP 2.x, OpenClaw Skill.
Available Tools
7 toolsdaily_report_contextDaily report contextB
Return one compact computed packet for SH, V, and JM. This is the only market payload that should enter the report context.
Inputs: trade_date (required), symbols. Returns: object
manual_data_submitSubmit manual daily dataA
Validate and upsert structured spot, inventory, operating-rate, or other daily metrics. The tool returns counts only, not the submitted dataset.
Inputs: records (required). Returns: object
market_run_crawlerRun allowlisted market crawlerB
Run the configured native crawler or FuturesIntelTool refresh for one supported symbol and date. Only run status is returned.
Inputs: source (required), trade_date (required). Returns: object
report_listList past reportsA
Return compact report metadata and short summaries only. Use this before reading any past report; full report content is never returned.
Inputs: limit, query, date_to, symbols, +1 more. Returns: object
report_readRead selected past reportB
Read one selected report with a token budget. Use next_offset to continue only when necessary.
Inputs: report_id (required), offset, max_tokens. Returns: object
report_saveSave generated reportB
Persist a completed report outside model context. Re-saving the same date, type, title, and source updates the existing report.
Inputs: payload (required). Returns: object
research_searchSearch research notesB
Search FuturesIntelTool or native news, announcements, and research notes. Returns at most three short excerpts with citations.
Inputs: query (required), limit, symbols. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct responsibility: market context generation, manual data submission, crawler execution, report persistence, report listing, report reading, and research search. There is no meaningful overlap or ambiguity between tool purposes.
The report_* tools follow a noun-verb pattern (save/list/read), and manual_data_submit is similar, but daily_report_context, market_run_crawler, and research_search do not follow the same convention. This mixed structure makes the naming pattern less predictable.
Seven tools is a well-scoped size for a futures knowledge base server, covering data ingestion, crawling, reporting, and research without unnecessary bloat. Each tool contributes a distinct capability.
The tool set covers the main workflow: submit/ingest data, generate report context, save/list/read reports, and search research. Minor gaps exist, such as no direct way to query or delete submitted data and no explicit report deletion, but the core lifecycle is otherwise supported.
Maintenance
Related MCP Connectors
China A-share market data for research, backtesting and AI agents via MCP.
Real SEC, 13F, insider, congress & macro data your AI agent can cite. Hosted MCP, 24 tools.
Mycel unified MCP gateway: China realtime data and 20 tool modules. API key required.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides web search, page fetching, and A-stock data access (financial reports, announcements, research reports, penalties, IR meetings) via MCP tools.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to perform quantitative research and backtesting for China A-shares and futures, including data fetching, backtesting, factor analysis, and experiment tracking through MCP tools.2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides AI agents with standard MCP tool calls to run A-share market research workflows—macro analysis, daily review generation, strategy backtesting, watchlist scanning, stock analysis, and risk monitoring—while preserving manual confirmation for trade decisions.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to query A-share, US equity, ETF, index, and crypto market data and run technical analysis, fundamentals, money-flow, news, and SEC/A-share filing tools through a unified MCP interface. It also supports CSV/JSON code-export and can be deployed as a standalone HTTP API.-