<div align="center">

<img src="icon.png" width="112" alt="外贸业务主理人" />

# 外贸业务主理人 · MCP Server

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

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org)
[![MCP](https://img.shields.io/badge/MCP-FastMCP%20official%20SDK-0F6E56)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/Tools-10-185FA5)](tools.json)
[![Transport](https://img.shields.io/badge/Transport-stdio%20%7C%20streamable--http-BA7517)](#四接入配置)
[![License](https://img.shields.io/badge/License-MIT-5F5E5A)](LICENSE)

</div>

---

## 目录

| | |
|---|---|
| [一、它解决什么问题](#一它解决什么问题) | [二、能力矩阵](#二能力矩阵) |
| [三、快速开始](#三快速开始) | [四、接入配置](#四接入配置) |
| [五、核心工具详解](#五核心工具详解) | [六、方法论层](#六方法论层为什么它不会胡编) |
| [七、实战：一条询盘怎么走完](#七实战一条询盘怎么走完) | [八、部署](#八部署) |
| [九、环境变量](#九环境变量) | [十、目录结构](#十目录结构) |
| [十一、路线图](#十一路线图) | [十二、边界与免责](#十二边界与免责) |

---

## 一、它解决什么问题

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

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

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

| 硬伤 | 后果 | 这里的做法 |
|---|---|---|
| 算不准 | 报价、汇率、到岸成本，口算即错 | `calc_quotation` 纯确定性计算，不经过模型 |
| 会编造 | 查不到就"合理补全"一个注册号 | `classify_claim` 强制三分类，查不到就是「待核实」 |
| 不可复现 | 同样的问题每次答案不一样 | 工具是规则/模板实现，同输入必同输出 |

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

> 一句话：**你策展能力，Agent 只是入口。**

---

## 二、能力矩阵

<table>
<thead>
<tr><th width="150">工具</th><th width="200">作用</th><th>关键入参</th></tr>
</thead>
<tbody>
<tr><td><code>calc_quotation</code></td><td>报价与利润核算<br/><sub>EXW/FOB/CFR/CIF/DDP 全链路</sub></td><td><code>product_cost*</code> <code>incoterm*</code> <code>target_margin</code> <code>exchange_rate</code> <code>quote_currency</code></td></tr>
<tr><td><code>check_redflags</code></td><td>欺诈红旗规则引擎<br/><sub>输出 clear / review / block</sub></td><td><code>company_age_years</code> <code>asks_fee_upfront</code> <code>email_free_domain</code> <code>refuses_video</code> 等 11 项</td></tr>
<tr><td><code>classify_claim</code></td><td>结论三分类<br/><sub>已验证事实 / 合理推断 / 待核实</sub></td><td><code>text*</code> <code>has_source</code></td></tr>
<tr><td><code>research_company</code></td><td>资信背调<br/><sub>实体锚定 / 登记处 / 研究问题</sub></td><td><code>name*</code> <code>country</code> <code>extra</code></td></tr>
<tr><td><code>scan_market</code></td><td>市场扫描<br/><sub>有数据则结构化，无数据给检索计划</sub></td><td><code>region*</code> <code>category*</code> <code>provided_data</code></td></tr>
<tr><td><code>score_products</code></td><td>多指标加权选品</td><td><code>products*</code> <code>weights</code></td></tr>
<tr><td><code>generate_persona</code></td><td>一页纸客户画像<br/><sub>决策人 / 痛点 / 切入点 / 异议</sub></td><td><code>company*</code> <code>country*</code> <code>known_facts</code> <code>decision_maker_role</code></td></tr>
<tr><td><code>draft_outreach</code></td><td>开发信 + 主题 A/B + 3 封跟进</td><td><code>target_company*</code> <code>country*</code> <code>product*</code> <code>language</code> <code>tone</code></td></tr>
<tr><td><code>plan_pipeline</code></td><td>总控编排<br/><sub>判信息充分度与调查深度，派发工具</sub></td><td><code>client_name</code> <code>inquiry_text</code> <code>report_depth</code> 等</td></tr>
<tr><td><code>web_search</code></td><td>联网检索<br/><sub>配 key 走真实结果，否则给检索计划</sub></td><td><code>query*</code> <code>top_k</code></td></tr>
</tbody>
</table>

<sub>* 为必填参数。完整 JSON Schema 见 [`tools.json`](tools.json)。</sub>

---

## 三、快速开始

```bash
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 模式）：

```bash
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 市场托管拉起）

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

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

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

### B. 远程 Streamable HTTP / SSE（部署后填 URL）

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

<details>
<summary><b>传输模式是怎么决定的？</b></summary>

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

1. 设了 `MCP_TRANSPORT` 就以它为准；
2. 没设，但检测到 `stdin` 不是终端（说明是被 MCP 客户端当子进程拉起的）→ 走 `stdio`；
3. 都不满足 → 走 `streamable-http`。

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

</details>

---

## 五、核心工具详解

### `calc_quotation` — 报价核算

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

<details>
<summary>示例：成本 ¥100，CIF 报价，运费 15，保险 6，目标毛利 20%，汇率 7.1</summary>

```json
{
  "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": "报价为测算值，关税/运费/汇率以实际成交与目的国海关口径为准，需专业确认。"
}
```

</details>

### `check_redflags` — 红旗规则引擎

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

<details>
<summary>示例：公司成立 0 年 + 免费邮箱 + 要求预付</summary>

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

</details>

### `classify_claim` — 结论三分类

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

### `plan_pipeline` — 总控编排

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

---

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

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

核心三条：

| 原则 | 含义 |
|---|---|
| **三分类** | 每个结论必须标明是事实、推断还是待核实，不许含糊带过 |
| **来源可追溯** | 机构名 + URL + 日期，缺一不可；没有来源就老实标「待核实」 |
| **不编造** | 检索不到时返回**结构化的检索计划**（查什么、去哪查），而不是编一个答案 |

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

<details>
<summary>为什么检索类工具没配 key 也能用？</summary>

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

- 保证服务**永远有输出**，可离线运行、可被自动评测；
- 把"不知道"显式暴露出来，而不是让模型悄悄补全。

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

</details>

---

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

以真实案例 *Chile Brasil Projetos Ambientais*（巴西净水设备采购方）为例：

| 步骤 | 调用 | 结果 |
|---|---|---|
| 1. 判断该查多深 | `plan_pipeline` | 信息不足 → 判定 `deep` |
| 2. 实体核验 | `research_company` | 6 组查询变体均无法在公开源定位该实体 |
| 3. 结论定性 | `classify_claim` | 「待核实」——**没有为了给结论而降格** |
| 4. 最终裁定 | `check_redflags` | **REVIEW**，建议索取证照与注册号后再推进 |

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

---

## 八、部署

### Docker（推荐）

```bash
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
```

---

## 十一、路线图

- [x] 10 个工具 + 总控编排
- [x] stdio / Streamable HTTP 双传输
- [x] 真实握手验证（10 工具、protocolVersion 2025-03-26）
- [ ] 多语种开发信（西语 / 葡语 / 阿语）
- [ ] 汇率与关税实时接口
- [ ] 判例库：积累真实询盘的红旗样本
- [ ] 发布到 MCP 服务市场

---

## 十二、边界与免责

- 工具为**确定性 / 结构化**实现，可独立运行与被自动评测；分析性表达由接入方 Agent 叠加 `SYSTEM_PROMPT.md` 完成。
- 报价、市场规模、合规判断均为**测算与参考值**，以实际成交与目的国监管口径为准，需专业确认。
- **不提供**规避制裁、出口管制、海关申报、付款风控方面的建议。
- 红旗裁定属**规则模式识别**，不是法律或信用结论；命中 `block` 须人工复核。

---

## License

[MIT](LICENSE) © 2026 hanjiajiade