内容
# 外贸硅基军团 MCP Server v2.0
> 面向跨境电商和外贸企业的 AI Agent 工具集 — 从 Mock 升级为生产就绪架构
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://python.org)
[]()
## 概述
外贸硅基军团 MCP Server v2.0 是基于 MCP (Model Context Protocol) 协议的外贸工具服务，提供从客户发现到成交转化的全链路外贸能力。v2.0 从全 Mock 数据架构升级为生产就绪架构，引入确定性优先层、真实 API 对接、并行工具调用和成本控制机制。
### v2.0 核心改进
| 改进项 | 说明 |
|--------|------|
| **确定性优先层** | HS编码/国家代码/邮箱/电话等高频简单请求走规则表/正则，零LLM成本 |
| **真实API对接** | 邮件发送对接 Resend API、客户发现对接 Google Custom Search、供应商查找抓取阿里巴巴 |
| **并行工具调用** | `batch_execute` 工具支持 asyncio 并行执行多个独立调用 |
| **成本控制** | MAX_LOOPS 限制 + COST_BUDGET 预算 + Replan-not-retry 失败处理 |
| **Tool Use Examples** | 每个工具 docstring 包含 ≥2 个使用范例，提升AI模型选择准确性 |
| **PII自动脱敏** | 返回结果中的邮箱/电话自动脱敏 |
| **核心数据锚定** | 海关数据标注 `data_source: demo`，区分真实与演示数据 |
## 架构
```
┌──────────────────────────────────────────────────────┐
│ MCP Client (AI) │
│ Claude / Cursor / CodeBuddy / 元宝 │
└──────────────────┬───────────────────────────────────┘
│ MCP Protocol (Streamable HTTP)
┌──────────────────▼───────────────────────────────────┐
│ server.py (MCP协议层) │
│ 工具注册 + Tool Use Examples + PII脱敏 │
├────────────┬──────────────┬──────────────────────────┤
│ │ │ │
│ ┌─────────▼─────────┐ │ ┌──────────────────────┐ │
│ │ deterministic.py │ │ │ batch_tools.py │ │
│ │ (确定性优先层) │ │ │ (并行调度层) │ │
│ │ - HS编码验证 │ │ │ - asyncio 并行 │ │
│ │ - 国家代码映射 │ │ │ - MAX_LOOPS 控制 │ │
│ │ - 汇率缓存 │ │ │ - COST_BUDGET 预算 │ │
│ │ - 邮箱/电话验证 │ │ │ - Replan-not-retry │ │
│ └───────────────────┘ │ └──────────────────────┘ │
│ │ │
│ ┌──────────────────────▼────────────────────────┐ │
│ │ tools/ (工具实现层) │ │
│ ├──────────────┬──────────────┬─────────────────┤ │
│ │ email_tools │customer_tools│ customs_tools │ │
│ │ (Resend API) │(Google CSE) │ (Demo模式) │ │
│ ├──────────────┼──────────────┼─────────────────┤ │
│ │whatsapp_tools│supplier_tools│ │ │
│ │ (Demo模式) │ (Alibaba) │ │ │
│ └──────────────┴──────────────┴─────────────────┘ │
└──────────────────────────────────────────────────────┘
```
## 文件结构
```
github_repo/
├── server.py # 主MCP Server入口 (16个工具 + 2个资源)
├── deterministic.py # 确定性优先层 (正则/查表/缓存)
├── batch_tools.py # 并行工具调用 + 成本控制
├── tools/
│ ├── __init__.py
│ ├── email_tools.py # 邮件工具 (Resend API)
│ ├── customer_tools.py # 客户发现 (Google CSE)
│ ├── customs_tools.py # 海关数据 (Demo)
│ ├── whatsapp_tools.py # WhatsApp (Demo)
│ └── supplier_tools.py # 供应商查找 (Alibaba)
├── requirements.txt
├── mcp.json # MCP协议元数据
├── Dockerfile
├── LICENSE
└── README.md
```
## 工具列表
### 业务工具 (11个)
| 工具名 | 功能 | 数据源 | 需要 API Key |
|--------|------|--------|-------------|
| `discover_customers` | 发现潜在外贸客户 | Google Custom Search | ✅ |
| `search_company_info` | 查询公司详细信息 | Google Custom Search | ✅ |
| `send_email` | 发送外贸开发信 | Resend API | ✅ |
| `batch_send_emails` | 批量发送邮件 | Resend Batch API | ✅ |
| `get_email_tracking` | 邮件追踪数据 | Resend API | ✅ |
| `send_whatsapp_message` | 发送WhatsApp消息 | Demo | ❌ |
| `send_whatsapp_product_card` | 发送产品卡片 | Demo | ❌ |
| `get_whatsapp_message_status` | WhatsApp消息状态 | Demo | ❌ |
| `query_import_data` | 进口海关数据 | Demo | ❌ |
| `query_export_data` | 出口海关数据 | Demo | ❌ |
| `find_suppliers_by_product` | 供应商查找 | Alibaba.com | ❌ |
### 确定性工具 (4个) — 零LLM成本
| 工具名 | 功能 |
|--------|------|
| `validate_hs_code_tool` | HS编码格式验证 |
| `lookup_country_code` | 国家代码中英文/ISO互查 |
| `validate_email_tool` | 邮箱格式验证 |
| `validate_phone_tool` | 国际电话号码验证 |
### 并行调度工具 (1个)
| 工具名 | 功能 |
|--------|------|
| `batch_execute` | 并行执行多个工具调用，含成本控制 |
## 快速开始
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 配置环境变量
```bash
# 邮件发送 (Resend — 免费3000封/月)
export RESEND_API_KEY="re_xxxxxxxxxxxx"
export RESEND_FROM_EMAIL="your-verified@yourdomain.com"
# 获取: https://resend.com/api-keys
# 客户发现 (Google Custom Search — 免费100次/天)
export GOOGLE_SEARCH_API_KEY="your-api-key"
export GOOGLE_SEARCH_CSE_ID="your-cse-id"
# 获取: https://developers.google.com/custom-search/v1/overview
# 创建CSE: https://programmablesearchengine.google.com/
# 成本控制 (可选)
export MAX_LOOPS=5 # 每轮最大工具调用数
export COST_BUDGET=0.10 # 每轮成本预算上限(USD)，0或空=无限制
```
> **注意**: 未配置 API Key 时，对应工具会返回引导信息而非崩溃。确定性工具和 Demo 工具无需配置。
### 3. 启动服务
```bash
python server.py
# 服务启动在 http://localhost:8000/mcp
```
### 4. MCP 客户端配置
```json
{
"mcpServers": {
"silicon-army": {
"url": "http://localhost:8000/mcp",
"type": "streamable-http"
}
}
}
```
## 确定性优先层
确定性优先层在调用真实工具前先检查是否能通过规则/正则/查表直接回答：
```
用户请求 → 确定性检查 → 命中？→ 直接返回(零成本)
↓ 未命中
调用真实工具/API
```
- **HS编码验证**: 正则匹配 4-10 位数字，自动去除点号/空格
- **国家代码查询**: 50+ 常用国家中英文/ISO2/ISO3 互查，O(1) 查表
- **邮箱格式验证**: RFC 兼容正则
- **电话格式验证**: E.164 国际格式 + 国家代码提取
- **汇率缓存**: 从 `open.er-api.com` 免费获取，1小时本地缓存
## 并行工具调用
使用 `batch_execute` 工具并行执行多个独立调用：
```python
# 同时查询进口数据 + 查找供应商 + 搜索客户
batch_execute(calls=[
{"tool": "query_import_data", "arguments": {"hs_code": "854140", "country": "德国"}},
{"tool": "find_suppliers_by_product", "arguments": {"product_keyword": "LED lighting"}},
{"tool": "discover_customers", "arguments": {"keyword": "LED lighting", "market": "德国"}}
])
```
**成本控制机制**:
- `MAX_LOOPS`: 限制每轮工具调用数（默认5）
- `COST_BUDGET`: 限制每轮预估成本（默认无限制）
- `Replan-not-retry`: 步骤失败时返回当前状态 + 重新规划建议，而非盲目重试
## PII 脱敏
返回结果中的邮箱和电话号码自动脱敏：
- 邮箱: `contact@acme.com` → `c***@acme.com`
- 电话: `+8613800138000` → `+86****00`
## Docker 部署
```bash
docker build -t silicon-army-mcp .
docker run -p 8000:8000 \
-e RESEND_API_KEY="re_xxx" \
-e RESEND_FROM_EMAIL="noreply@yourdomain.com" \
-e GOOGLE_SEARCH_API_KEY="xxx" \
-e GOOGLE_SEARCH_CSE_ID="xxx" \
silicon-army-mcp
```
## 使用 MCP Inspector 测试
```bash
npx -y @modelcontextprotocol/inspector
# 连接到 http://localhost:8000/mcp
```
## 环境变量一览
| 变量名 | 用途 | 必需 | 默认值 |
|--------|------|------|--------|
| `RESEND_API_KEY` | Resend 邮件 API | 邮件功能必需 | - |
| `RESEND_FROM_EMAIL` | 发件人邮箱 | 否 | `onboarding@resend.dev` |
| `GOOGLE_SEARCH_API_KEY` | Google CSE API Key | 客户发现必需 | - |
| `GOOGLE_SEARCH_CSE_ID` | Google CSE Engine ID | 客户发现必需 | - |
| `WHATSAPP_TOKEN` | WhatsApp Business API (预留) | 否 | - |
| `WHATSAPP_PHONE_ID` | WhatsApp Phone ID (预留) | 否 | - |
| `MAX_LOOPS` | 每轮最大工具调用数 | 否 | 5 |
| `COST_BUDGET` | 每轮成本预算(USD) | 否 | 无限制 |
## 适用场景
- 🎯 **跨境电商客户开发**: AI自动发现潜在买家 → 发送开发信 → 追踪 → 跟进
- 📊 **海关数据分析**: 进出口数据查询、市场趋势分析、竞品监控
- 📧 **多渠道营销触达**: 邮件(Resend) + WhatsApp 双渠道，批量发送 + 追踪
- 🔍 **供应商查找**: 按产品关键词从阿里巴巴筛选供应商
- ⚡ **高效并行查询**: 一次调用同时执行多个独立工具，降低延迟
## 技术架构
- **框架**: FastMCP (Python) — MCP 2025-03-26 协议
- **传输**: Streamable HTTP
- **并行**: asyncio + 信号量(并发度5)
- **缓存**: 汇率本地缓存(TTL 1小时)
- **安全**: PII自动脱敏 + 环境变量管理密钥
- **部署**: Docker 容器化
## License
MIT License - 详见 [LICENSE](LICENSE)
## 关于
**杭州云旅科技有限公司** — 专注AI+外贸领域的智能体产品研发
- 邮箱: wxy13336021626@foxmail.com
- 品牌矩阵: 云旅AI（公司品牌）/ 外贸硅基军团（产品线）/ 百雀AI（产品名）
