Skip to main content
Glama
BizDig Trade

BizDig Trade

by alonexun

BizDig Trade

License Python Tests

Deterministic MCP tool service for China export analysis / 外贸出口分析的 MCP 工具服务。

定位:6 个确定性数据工具(bt_*,MCP Server)+ 3 份方法论技能文档(skills/),为宿主 AI(如 WorkBuddy)提供外贸出口分析的数据底座与分析方法。所有工具均为纯确定性计算(本地字典 + UN Comtrade 官方数据),不含 LLM;推理、行业知识与联网信息收集由宿主 AI 承担。

bizdig-trade/
├── server/            # MCP Server(Streamable HTTP)+ 6 个 bt_ 工具注册
├── tools/             # 确定性计算核心(Comtrade 客户端/HS 匹配/市场筛选/生命周期)
├── data/export/       # 本地数据字典快照(HS2022/宏观指标/产业集群/区域表,随版本发布)
├── data/cache/        # 运行时缓存 + 每日配额计数(gitignore,仅存在于部署机)
├── skills/            # 3 份方法论 SKILL.md(供宿主 Agent 加载)
├── metering/          # API Key 生成、用量统计、免费额度限额
├── connector/         # WorkBuddy Connector 市场发布包
├── deploy/            # systemd + nginx 部署工件与手册
└── tests/             # pytest 测试套件(103 passed / 2 skipped)

一、WorkBuddy 个人用户接入指引

1. 添加 MCP Server

  1. 自行部署本服务(见 deploy/DEPLOY.md),或使用实例提供方提供的两个信息:服务地址(形如 https://<你的域名>/mcp)与 API Key(X-API-Key 请求头的值,服务方通过 python -m metering.gen_key "标签" 生成);

  2. 在 WorkBuddy 的 MCP 连接设置中新增连接,类型选择 Streamable HTTP;

  3. 地址填写 https://<你的域名>/mcp;

  4. 请求头添加 X-API-Key: <你的key>;

  5. 保存并启用连接,确认工具列表中出现 6 个 bt_ 开头的工具。

也可以直接在 WorkBuddy Connector 市场搜索并安装 BizDig Trade 连接器(Connector 包见 connector/),按表单填入服务地址与 API Key 即可,无需手工配置请求头。

2. 把 SKILL.md 提供给 Agent

MCP 只负责"给数据","怎么分析"由 3 份方法论文档规定。任选一种方式把 skills/ 下的 SKILL.md 内容交给 WorkBuddy 的 Agent:

  • 粘贴:对话开始时把对应主题的 SKILL.md 全文粘贴进对话;

  • 附件:把 SKILL.md 文件作为附件上传到当前对话;

  • 知识库:把 3 份文件加入 WorkBuddy 知识/知识库,Agent 按需检索。

三份文档各有"触发条件"一节,说明什么问题该用哪份方法:

  • 问题偏"出口去哪个市场、趋势如何" → SKILL_出口市场调研.md

  • 问题偏"货源、产业集群、内外贸" → SKILL_货源与供应链.md

  • 问题偏"客户类型、开发渠道、地缘风险" → SKILL_客户开发与地缘风险.md

3. 首次验证

接入完成后问一句:"燃料电池出口东南亚怎么样?"

正常表现:Agent 先调用 bt_hs_match 匹配 HS 编码,再调用 bt_market_screen 粗筛东南亚候选市场,然后对重点国家调用 bt_trade_curves / bt_bilateral,最终给出带 HS 编码、国家列表、六维评分与数据来源说明的分析。若收到 401,检查 X-API-Key 是否正确;若工具不可见,检查地址是否以 /mcp 结尾。


Related MCP server: census-trade-mcp-server

二、工具一览

工具

用途

关键参数

bt_hs_match

产品关键词 → HS 编码列表(字面/语义双通道匹配),无匹配时给出改写建议

keyword:产品关键词(中文/英文)或 4/6 位 HS 编码

bt_market_screen

基于 WDI 宏观指标(GDP/人均 GDP/增长率)预筛选候选出口市场,附生命周期阶段与确定性评分

hs_code:HS 编码;region:可选区域(中文名如"东南亚"或区域代码);min_gdp:可选最低 GDP 门槛(美元)

bt_trade_curves

贸易双曲线:目标国自华进口 + 中国全球出口的季度趋势、CAGR 与生命周期阶段

hs_code:HS 编码;country:目标国 ISO alpha-2 代码(如 VN/US/JP)

bt_bilateral

目标国自华年度进口额(镜像口径,比中国自报出口更完整可靠),年份自动回退

hs_code:HS 编码;country:目标国 ISO alpha-2 代码

bt_industry_map

产品关键词 → 行业分类 + 国内产业集群城市列表与集聚统计

keyword:产品关键词(也可传 HS 编码)

bt_validate

对 Agent 生成的结论(集群城市/商家名单)做本地交叉验证,输出综合置信度评分

hs_code:HS 编码;country:目标国 ISO alpha-2 代码;metrics:待验证指标字典(industry_clusters/merchants)

所有工具不抛异常:数据不可得、触发 UN Comtrade 每日配额软限(450 次)或超出免费额度时,返回 degraded: true 与中文说明,由宿主 Agent 降级处理。


三、SKILL.md 使用说明

skills/ 下 3 份方法论文档(中文)规定了宿主 Agent 的分析框架,每份均包含:触发条件(含例句)、角色与目标、方法论步骤(每步的 bt_ 工具、参数与返回解读)、工具组合建议(典型调用链)、输出结构(结论先行/六维评分/数据表格/置信度标注)、置信度标注要求(高=官方统计直接命中、中=推导/缓存、低=估算且必须明示)、边界与降级(degraded 措辞与联网分工)。

要点:

  • 工具是数据、技能是方法:Agent 应先按 SKILL.md 的步骤调用工具取数,再按其模板组织输出;

  • 置信度铁律:官方数据(data_source=comtrade)、缓存/推导(cache)、估算三类数字必须区分标注,低置信必须明示;

  • 联网分工:MCP 工具不联网收集情报;最新关税政策、地缘动态等实时信息由宿主 Agent 用其原生搜索能力补充(《SKILL_客户开发与地缘风险》内附逐国搜索 checklist);

  • 用户要"一份完整出口报告"时,按 7 段式(货品概览/货源集聚/内外贸对比/目标市场推荐/营销策略建议/场景策略/行动建议)联合三份技能完成。


四、权限声明与用量计量

  • 本服务仅访问部署机上的本地数据文件与 UN Comtrade 公共 API(comtradeplus.un.org);

  • 不读写用户本地文件,不访问其他任何网络资源;

  • X-API-Key 仅用于服务端请求鉴权与免费额度计量(每 Key 每日默认 20 次,超出当日降级);

  • 服务端在 SQLite 中记录调用日志(key 后 6 位、工具名、耗时、缓存命中、Comtrade 消耗),仅用于配额管理与用量统计,不含对话内容。


五、卸载说明

个人用户在 WorkBuddy 中移除 MCP 连接即完成卸载,客户端无本地残留。服务端不向用户设备写入任何文件;如需彻底停用某用户,服务方删除(或从 BIZDIG_API_KEYS 中移除)对应 API Key 即可。


六、本地开发

环境要求

Python 3.11+(仅需标准库 + 下方依赖;无数据库、无其他服务)。

安装与配置

pip install -r requirements.txt   # requests / pytest / mcp[cli]

在项目根目录创建 .env(参考 .env.example):

COMTRADE_API_KEY=<你的 UN Comtrade API Key,不配则实时拉取类工具降级>
BIZDIG_PORT=<监听端口,默认 8800>
BIZDIG_API_KEYS=<逗号分隔的 X-API-Key 白名单,不配则全放行>
BIZDIG_DAILY_LIMIT_PER_KEY=<每 Key 每日工具调用上限,默认 20;<=0 不限制>
BIZDIG_CACHE_DIR=<运行时缓存目录,默认 data/cache/(已 gitignore)>

免费额度:每个 API Key 每日默认 20 次工具调用(超出当日返回 degraded 降级结果,UTC 0 点重置)。额度说明注入在每个工具的描述中,Agent 会在首次调用时向用户转述。公共实例务必保持限额——服务端共享单个 Comtrade key(每日 450 次软限)。私有部署可设 <=0 放开。

启动与测试

python -m server.main        # 启动 MCP Server(Streamable HTTP,0.0.0.0:BIZDIG_PORT,路径 /mcp)
python -m pytest tests -v    # 运行测试套件(mock 网络,不消耗 Comtrade 配额)

API Key 管理

python -m metering.gen_key "用户标签"   # 生成新的 X-API-Key
python -m metering.stats                # 查看各 key 的调用统计

Linux 服务器部署(systemd + nginx + HTTPS)参见 deploy/DEPLOY.md。


七、数据来源与更新频率

数据

来源

更新方式与频率

双边贸易额/贸易双曲线

UN Comtrade Plus API(官方统计)

查询时实时拉取并写入 data/cache/ 运行时缓存(30 天 TTL,配额耗尽时作降级数据源);每日配额软限 450 次(计数持久化,重启不归零)。年度数据有 12–18 个月发布滞后,工具按候选年份链(近 4 年)自动回退

宏观指标(GDP/人均 GDP/增长率)

世界银行 WDI

随 data/export/market_profiles.json 静态发布,版本化更新

HS 编码字典/行业关键词/产业集群分布

本地 data/export/*.json(HS2022 章节 + 产业园分布)

随版本发布更新


License & Data Attribution

代码以 Apache License 2.0 开源发布。

第三方数据归属(数据本身遵循各自提供方的条款,不随本仓库的代码许可证重新授权):

  • 宏观指标(GDP/人均 GDP/增长率)编译自世界银行 World Development Indicators (WDI),数据文件按 CC BY 4.0 使用(© World Bank,worldbank.org);

  • 双边贸易数据运行时经 UN Comtrade Plus API(comtradeplus.un.org,联合国统计司)获取,使用时请遵守 UN Comtrade 使用条款;

  • HS2022 编码字典、行业关键词与产业集群数据由本项目维护。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Access UN Comtrade international merchandise and services trade statistics via MCP tools for country lookups, HS commodity search, bilateral trade flows, balances, rankings, and data availability.
      661 npm
      4
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for the U.S. Census Bureau's International Trade Data API, enabling queries of monthly export and import statistics by HS, NAICS, end-use, and other classifications, with tools for trade balance, top partners, and country code lookup.
      7
      Creative Commons Zero v1.0 Universal
    • A
      license
      A
      quality
      B
      maintenance
      Enables querying Brazilian foreign trade data through MCP tools for trade flows, freight costs, code resolution, and dataset caveats, with known data defects corrected in responses.
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Brazilian foreign trade from MDIC/ComexStat -- exports and imports since 2000 by HS code (SH4/SH6/NCM) and partner country, in USD FOB and kilograms -- plus crop production, supply-and-demand balances, climate readings and commodity forecasts for hubs such as soybean, coffee and beef. 15 read-only tools, remote at https://mcp.kyrodata.com/mcp; official registry com.kyrodata/kyrodata.
      15
      1
      MIT