Skip to main content
Glama
trade-agent-mcp

trade-agent-mcp

by hanjiajiade

外贸业务主理人 · MCP Server

Foreign Trade Business Producer — 把外贸销售岗的全套方法论, 封装成 10 个可被任何 MCP 客户端直接调用的确定性工具。

Python MCP Tools Transport License


目录


Related MCP server: Territory News MCP Server

一、它解决什么问题

外贸业务员的日常,本质上是一条重复率极高的信息流水线:

收到询盘 → 这公司是真的吗 → 这市场能做吗 → 推什么品 → 写给谁 → 报多少钱

每一步都在做同一件事:拿信息、套方法、出结构化结论。但大模型直接干这事有三个硬伤:

硬伤

后果

这里的做法

算不准

报价、汇率、到岸成本,口算即错

calc_quotation 纯确定性计算,不经过模型

会编造

查不到就"合理补全"一个注册号

classify_claim 强制三分类,查不到就是「待核实」

不可复现

同样的问题每次答案不一样

工具是规则/模板实现,同输入必同输出

所以这个项目不是"又一个会聊天的外贸助手",而是一套方法论的固化:把资深业务员的判断逻辑拆成可调用、可审计、可自动评测的工具,Agent 只负责调度和表达。

一句话:你策展能力,Agent 只是入口。


二、能力矩阵

* 为必填参数。完整 JSON Schema 见 tools.json。


三、快速开始

git clone https://github.com/hanjiajiade/trade-agent-mcp.git
cd trade-agent-mcp

pip install -r requirements.txt     # 或 pip install .
python mcp_server.py                # 默认 streamable-http @ 0.0.0.0:8080

自检(HTTP 模式):

python -c "import urllib.request,json; req=urllib.request.Request('http://127.0.0.1:8080/mcp', data=json.dumps({'jsonrpc':'2.0','id':1,'method':'initialize','params':{'protocolVersion':'2025-03-26','capabilities':{},'clientInfo':{'name':'probe','version':'0'}}}).encode(), headers={'Content-Type':'application/json','Accept':'application/json, text/event-stream'}); print(urllib.request.urlopen(req, timeout=10).status)"

预期输出 200。


四、接入配置

A. stdio(本地客户端 / MCP 市场托管拉起)

{
  "mcpServers": {
    "trade-agent-mcp": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

安装后也可直接用入口命令:

{
  "mcpServers": {
    "trade-agent-mcp": {
      "command": "trade-agent-mcp",
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

B. 远程 Streamable HTTP / SSE(部署后填 URL)

{
  "mcpServers": {
    "trade-agent-mcp": {
      "url": "https://your.domain/mcp"
    }
  }
}

解析顺序:显式环境变量 → 自动探测 → 默认

  1. 设了 MCP_TRANSPORT 就以它为准;

  2. 没设,但检测到 stdin 不是终端(说明是被 MCP 客户端当子进程拉起的)→ 走 stdio;

  3. 都不满足 → 走 streamable-http。

容器里 stdin 同样不是终端,会被第 2 条误判。因此 Dockerfile 内已显式写死 ENV MCP_TRANSPORT=streamable-http,服务器部署无需担心。


五、核心工具详解

calc_quotation — 报价核算

成本 → 各贸易术语 → 到岸成本 → 建议售价 → 实际毛利率,一次性算穿。

{
  "incoterm": "CIF",
  "cost_currency": "CNY",
  "quote_currency": "USD",
  "moq": 500,
  "unit_landed_cost": 859.1,
  "suggested_unit_price": 1073.88,
  "unit_profit": 214.77,
  "actual_margin": 0.2,
  "breakdown": {
    "exw_出厂成本": 100,
    "freight_to_port_本地费用": 0.0,
    "fob_离岸价": 100.0,
    "international_freight_国际运费": 15,
    "cfr_成本加运费": 115.0,
    "insurance_保险费": 6,
    "cif_到岸价": 121.0,
    "duty_关税": 0.0,
    "other_landed_cost_其他到岸成本": 0.0,
    "landed_cost_总到岸成本": 121.0,
    "suggested_price_建议售价": 1073.88,
    "profit_单件利润": 214.77,
    "actual_margin_实际毛利率": 0.2
  },
  "notes": ["报价币种 USD 按汇率 7.1 换算(成本币种 CNY)"],
  "_discipline": "报价为测算值,关税/运费/汇率以实际成交与目的国海关口径为准,需专业确认。"
}

check_redflags — 红旗规则引擎

命中即升级,输出 clear / review / block 三档裁定。

{
  "verdict": "block",
  "hits": [
    "免费邮箱域名冒充公司(如 @gmail/@163 自述为采购方)",
    "以关税/保证金/运费等名目要求预付或代付"
  ],
  "hit_count": 2,
  "note": "裁定为规则模式识别,非法律/信用结论;命中 block 须人工复核并索取证照材料。"
}

classify_claim — 结论三分类

任何一条结论,强制归入 已验证事实 / 合理推断 / 待核实。 带来源不一定就是事实,不带来源一律不得升格——这是整套纪律的地基。

plan_pipeline — 总控编排

判断信息充分度与调查深度(quick / standard / deep),派发应调用的工具, 并显式列出缺什么信息。它不替你做决定,它告诉你还差什么。


六、方法论层:为什么它不会胡编

工具是骨架,纪律是外壳。SYSTEM_PROMPT.md 是本服务的系统提示词层,把它设为 Agent 的 system prompt,工具输出就会自动带上可信分析的外壳。

核心三条:

原则

含义

三分类

每个结论必须标明是事实、推断还是待核实,不许含糊带过

来源可追溯

机构名 + URL + 日期,缺一不可;没有来源就老实标「待核实」

不编造

检索不到时返回结构化的检索计划(查什么、去哪查),而不是编一个答案

方法论来源:Perplexity「客户背调」合集 + D&B 风控结构(实体锚定、登记处核验、七轴证据、三档置信度 Confirmed / Reported / Alleged)。

web_search 与 research_company 在未配置 API key 时,返回的是检索计划—— 包含该查哪些查询、去哪些权威来源查。这不是降级,而是设计:

  • 保证服务永远有输出,可离线运行、可被自动评测;

  • 把"不知道"显式暴露出来,而不是让模型悄悄补全。

配上 TAVILY_API_KEY 或 SERPER_API_KEY 后,自动切换为真实检索结果。


七、实战:一条询盘怎么走完

以真实案例 Chile Brasil Projetos Ambientais(巴西净水设备采购方)为例:

步骤

调用

结果

1. 判断该查多深

plan_pipeline

信息不足 → 判定 deep

2. 实体核验

research_company

6 组查询变体均无法在公开源定位该实体

3. 结论定性

classify_claim

「待核实」——没有为了给结论而降格

4. 最终裁定

check_redflags

REVIEW,建议索取证照与注册号后再推进

这个案例的价值恰恰在于它的结论是"查不到"。一个会编造的助手会给你一份漂亮的巴西市场报告; 这套工具给你的是一次诚实的失败,以及下一步该去哪里查。


八、部署

Docker(推荐)

cp .env.example .env    # 按需填入变量
docker compose up -d --build

云主机

监听 0.0.0.0:$PORT,路由 /mcp。用 Nginx 反代 + Let's Encrypt 即可对外提供 https://your.domain/mcp。

生产环境请务必显式设置 MCP_TRANSPORT=streamable-http,不要依赖自动探测。

投稿/上架自检清单

  • MCP initialize 成功

  • tools/list 在 15 秒内返回至少 1 个工具

  • 每个工具的入参是合法 JSON Schema(python scripts/export_tools.py 可重新导出核对)

  • 至少调用一次核心工具并得到非错误响应

  • 从外部网络(非开发机)访问仍可用

  • 上架后不再更改工具名或输入 Schema


九、环境变量

变量

必填

说明

MCP_TRANSPORT

否

streamable-http(默认) / stdio

HOST

否

默认 0.0.0.0

PORT

否

默认 8080

TAVILY_API_KEY

否

启用 web_search / research_company 真实检索

SERPER_API_KEY

否

同上,走 Serper Google 检索

密钥只走环境变量,不写进源码;.env 已被 .gitignore 排除。


十、目录结构

trade-agent-mcp/
├── mcp_server.py           # FastMCP 服务入口,10 个工具
├── SYSTEM_PROMPT.md        # 方法论层(Agent 系统提示词)
├── tools.json              # 工具定义(由 scripts/export_tools.py 生成)
├── pyproject.toml          # 打包配置(pip install . / 命令入口)
├── requirements.txt        # mcp[cli] / requests
├── scripts/
│   └── export_tools.py     # 导出 tools.json
├── Dockerfile              # 已写死 streamable-http
├── docker-compose.yml
├── .env.example
├── icon.png
└── README.md

十一、路线图

  • 10 个工具 + 总控编排

  • stdio / Streamable HTTP 双传输

  • 真实握手验证(10 工具、protocolVersion 2025-03-26)

  • 多语种开发信(西语 / 葡语 / 阿语)

  • 汇率与关税实时接口

  • 判例库:积累真实询盘的红旗样本

  • 发布到 MCP 服务市场


十二、边界与免责

  • 工具为确定性 / 结构化实现,可独立运行与被自动评测;分析性表达由接入方 Agent 叠加 SYSTEM_PROMPT.md 完成。

  • 报价、市场规模、合规判断均为测算与参考值,以实际成交与目的国监管口径为准,需专业确认。

  • 不提供规避制裁、出口管制、海关申报、付款风控方面的建议。

  • 红旗裁定属规则模式识别,不是法律或信用结论;命中 block 须人工复核。


License

MIT © 2026 hanjiajiade

Available Tools

10 tools
calc_quotationA

外贸报价/利润核算。给定成本与贸易术语,算出 FOB/CIF/CFR、到岸成本、建议售价与利润。

Args: product_cost: 工厂成本/采购成本(EXW 或出厂价),成本币种。 currency: 成本币种(CNY/USD/EUR)。 moq: 最小起订量(用于单价展示)。 incoterm: 贸易术语 EXW/FOB/CIF/CFR/DDP。 freight_to_port: 出厂到起运港本地费用(EXW 时填入)。 international_freight: 国际运费(到目的港)。 insurance: 保险费。 duty_rate: 目的国关税税率(0-1,如 0.1 表示 10%)。 other_landed_cost: 其他到岸成本(清关/仓储/内陆派送等)。 target_margin: 目标毛利率(0-1)。 exchange_rate: 成本币种 -> 报价币种 汇率(同币=1)。 quote_currency: 报价币种(留空=与成本币种相同)。

Inputs: product_cost (required), moq, currency, incoterm, +8 more.

check_redflagsB

统一红旗规则引擎:根据客户/供应商画像命中红旗,给出 clear/review/block 裁定。

红旗命中即升级,不等同最终定性;本工具只做模式识别。

Inputs: refuses_video, refuses_sample, domain_age_days, rushes_contract, +7 more.

classify_claimB

把一条结论归类为「已验证事实 / 合理推断 / 待核实」,并给出信号依据。

Args: text: 待分类的结论文本。 has_source: 是否附带来源(机构名+URL+日期)。

Inputs: text (required), has_source.

draft_outreachA

生成开发信首封(100-150 词量级)+ 主题 A/B + 3 封递进跟进。模板化、确定性、可运行。

Args: target_company: 目标公司名。 country: 目标国别。 product: 产品/品类。 persona: 客户画像要点(决策人关注点)。 certs: 相关认证(如 CE/ANVISA/INMETRO)。 contact: 称呼。 me: 发件人署名。 language: en / zh(其他语言回退 en)。 tone: professional / casual。

Inputs: country (required), product (required), target_company (required), me, +5 more.

generate_personaB

根据已知信息生成一页纸客户/账户画像(决策人、痛点、切入点、异议)。缺信息显式标注待核实。

Inputs: company (required), country (required), industry, products, +2 more.

plan_pipelineB

总控编排:判断信息充分度与调查深度,派发 skill,列出缺信息与研究问题。

Args: client_name: 客户/公司名。 website: 官网。 country: 国别。 inquiry_text: 询盘/邮件正文。 has_cnpj: 是否已提供注册号。 has_bank_info: 是否已提供银行信息。 report_depth: auto/quick/standard/deep。

Inputs: country, website, has_cnpj, client_name, +3 more.

research_companyC

资信背调计划:实体锚定清单、登记处、研究问题、红旗监视、缺信息。可选启用真实检索。

Inputs: name (required), extra, country.

scan_marketB

市场扫描:有数据则按模板结构化输出;无数据返回检索计划(权威来源 + 查询)。

Inputs: region (required), category (required), provided_data.

score_productsA

对多个候选产品按多指标加权评分与排序,辅助选品决策。

Args: products: 每项形如 {"name":..., "market_demand":0-100, "competition":0-100(越低越好填高分), "margin":0-100, "compliance_risk":0-100(越低越好填高分), "fit":0-100}。 weights: 各指标权重(默认 market_demand .3 / competition .2 / margin .25 / compliance .15 / fit .1)。

Inputs: products (required), weights.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools target clearly distinct activities: research, market scanning, pricing, red flags, search, scoring, outreach, persona, orchestration, and claim classification. Minor overlap exists between plan_pipeline and research_company/scan_market (all plan or list missing info) and between research_company and check_redflags (both address red flags), but descriptions mostly clarify boundaries.

    Naming Consistency5/5

    All ten tool names follow the same snake_case verb_noun pattern: research_company, scan_market, calc_quotation, check_redflags, web_search, score_products, draft_outreach, generate_persona, plan_pipeline, classify_claim. There is no mixing of conventions or vague generic verbs.

    Tool Count5/5

    Ten tools is well-scoped for a trade-agent server. Each tool serves a distinct stage in the trade workflow—research, market analysis, quotation, risk assessment, search, product scoring, outreach, persona generation, orchestration, and claim verification—without redundancy or bloat.

    Completeness5/5

    The toolset covers the full trade-agent lifecycle: finding and qualifying companies, scanning markets, calculating quotations, checking red flags, scoring products, generating personas and outreach emails, orchestrating pipelines, and classifying claims. There are no obvious dead ends; missing formal document generation (e.g., PIs) is a minor extension, not a core gap.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      AI agent toolset for cross-border e-commerce and foreign trade, enabling customer discovery, communication, data analysis, and supplier search via MCP protocol.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides real-time account intelligence, deal signals, and strategic openers to AI agents and MCP-compatible orchestrators, enabling automated sales workflows such as pre-call battlecards, deal reactivation, and territory monitoring.
      12
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to discover companies showing buying signals, enrich them with public homepage data, score them against custom rules, and draft review-ready briefs.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to find leads, read buying signals, write and send email and LinkedIn outreach, handle replies, and report results, with built-in safety gates, approvals, limits, and compliance controls.
      10
      Apache 2.0