Silicon Army

面向跨境电商和外贸企业的 AI Agent 工具集 — 从 Mock 升级为生产就绪架构

MCP Protocol License: MIT Python Version

概述

外贸硅基军团 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. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

# 邮件发送 (Resend — 免费3000封/月)
export RESEND_API_KEY="re_xxxxxxxxxxxx"
export RESEND_FROM_EMAIL="[email protected]"
# 获取: 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. 启动服务

python server.py
# 服务启动在 http://localhost:8000/mcp

4. MCP 客户端配置

{
  "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 工具并行执行多个独立调用：

# 同时查询进口数据 + 查找供应商 + 搜索客户
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 脱敏

返回结果中的邮箱和电话号码自动脱敏：

• 邮箱: [email protected] → c***@acme.com
• 电话: +8613800138000 → +86****00

Docker 部署

docker build -t silicon-army-mcp .
docker run -p 8000:8000 \
  -e RESEND_API_KEY="re_xxx" \
  -e RESEND_FROM_EMAIL="[email protected]" \
  -e GOOGLE_SEARCH_API_KEY="xxx" \
  -e GOOGLE_SEARCH_CSE_ID="xxx" \
  silicon-army-mcp

使用 MCP Inspector 测试

npx -y @modelcontextprotocol/inspector
# 连接到 http://localhost:8000/mcp

环境变量一览

变量名	用途	必需	默认值
RESEND_API_KEY	Resend 邮件 API	邮件功能必需	-
RESEND_FROM_EMAIL	发件人邮箱	否	[email protected]
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

关于

杭州云旅科技有限公司 — 专注AI+外贸领域的智能体产品研发

• 邮箱: [email protected]
• 品牌矩阵: 云旅AI（公司品牌）/ 外贸硅基军团（产品线）/ 百雀AI（产品名）