silicon-army-mcp

# Tool List ## Overview The MCP Server v2.0 is an AI-powered toolset for cross-border e-commerce and foreign trade enterprises, providing a full-chain foreign trade capability from customer discovery to transaction conversion. The v2.0 version upgrades from a full Mock data architecture to a production-ready architecture, introducing a deterministic priority layer, real API connections, parallel tool calls, and a cost control mechanism. ### v2.0 Core Improvements | Improvement | Description | | --- | --- | | **Deterministic Priority Layer** | HS code / country code / email / phone number, etc. high-frequency simple requests go through rule tables / regular expressions, zero LLM cost | | **Real API Connection** | Email sending connects to Resend API, customer discovery connects to Google Custom Search, supplier search crawls Alibaba | | **Parallel Tool Call** | `batch_execute` tool supports asyncio parallel execution of multiple independent calls | | **Cost Control** | MAX_LOOPS limit + COST_BUDGET budget + Replan-not-retry failure handling | | **Tool Use Examples** | Each tool docstring contains ≥2 usage examples, improving AI model selection accuracy | | **PII Automatic Desensitization** | Return results automatically desensitize email / phone numbers | | **Core Data Anchoring** | Customs data labeled `data_source: demo`, distinguishing real and demo data | ## Architecture ``` ┌──────────────────────────────────────────────────────┐ │ MCP Client (AI) │ │ Claude / Cursor / CodeBuddy / Yuanbao │ └──────────────────┬───────────────────────────────────┘ │ MCP Protocol (Streamable HTTP) ┌──────────────────▼───────────────────────────────────┐ │ server.py (MCP Protocol Layer) │ │ Tool Registration + Tool Use Examples + PII Desensitization │ ├────────────┬──────────────┬──────────────────────────┤ │ │ │ │ │ ┌─────────▼─────────┐ │ ┌──────────────────────┐ │ │ │ deterministic.py │ │ │ batch_tools.py │ │ │ │ (Deterministic Priority Layer) │ │ │ (Parallel Scheduling Layer) │ │ │ - HS Code Verification │ │ │ - asyncio Parallel │ │ │ - Country Code Mapping │ │ │ - MAX_LOOPS Control │ │ │ - Exchange Rate Cache │ │ │ - COST_BUDGET Budget │ │ │ - Email / Phone Verification │ │ │ - Replan-not-retry │ │ └───────────────────┘ │ └──────────────────────┘ │ │ │ │ │ ┌──────────────────────▼────────────────────────┐ │ │ │ tools/ (Tool Implementation Layer) │ │ │ ├──────────────┬──────────────┬─────────────────┤ │ │ │ email_tools │customer_tools│ customs_tools │ │ │ │ (Resend API) │(Google CSE) │ (Demo Mode) │ │ │ ├──────────────┼──────────────┼─────────────────┤ │ │ │whatsapp_tools│supplier_tools│ │ │ │ │ (Demo Mode) │ (Alibaba) │ │ │ │ └──────────────┴──────────────┴─────────────────┘ │ └──────────────────────────────────────────────────────┘ ``` ## File Structure ``` github_repo/ ├── server.py # Main MCP Server Entry (16 tools + 2 resources) ├── deterministic.py # Deterministic Priority Layer (Regular Expressions / Table Lookup / Cache) ├── batch_tools.py # Parallel Tool Call + Cost Control ├── tools/ │ ├── __init__.py │ ├── email_tools.py # Email Tool (Resend API) │ ├── customer_tools.py # Customer Discovery (Google CSE) │ ├── customs_tools.py # Customs Data (Demo) │ ├── whatsapp_tools.py # WhatsApp (Demo) │ └── supplier_tools.py # Supplier Search (Alibaba) ├── requirements.txt ├── mcp.json # MCP Protocol Metadata ├── Dockerfile ├── LICENSE └── README.md ``` ## Tool List ### Business Tools (11) | Tool Name | Function | Data Source | Requires API Key | | --- | --- | --- | --- | | `discover_customers` | Discover Potential Foreign Trade Customers | Google Custom Search | ✅ | | `search_company_info` | Query Company Details | Google Custom Search | ✅ | | `send_email` | Send Foreign Trade Development Email | Resend API | ✅ | | `batch_send_emails` | Batch Send Emails | Resend Batch API | ✅ | | `get_email_tracking` | Email Tracking Data | Resend API | ✅ | | `send_whatsapp_message` | Send WhatsApp Message | Demo | ❌ | | `send_whatsapp_product_card` | Send Product Card | Demo | ❌ | | `get_whatsapp_message_status` | WhatsApp Message Status | Demo | ❌ | | `query_import_data` | Import Customs Data | Demo | ❌ | | `query_export_data` | Export Customs Data | Demo | ❌ | | `find_suppliers_by_product` | Supplier Search | Alibaba.com | ❌ | ### Deterministic Tools (4) — Zero LLM Cost | Tool Name | Function | | --- | --- | | `validate_hs_code_tool` | HS Code Format Verification | | `lookup_country_code` | Country Code English / ISO Mutual Inquiry | | `validate_email_tool` | Email Format Verification | | `validate_phone_tool` | International Phone Number Verification | ### Parallel Scheduling Tool (1) | Tool Name | Function | | --- | --- | | `batch_execute` | Parallel Execution of Multiple Tool Calls, Including Cost Control | ## Quick Start ### 1. Install Dependencies ```bash pip install -r requirements.txt ``` ### 2. Configure Environment Variables ```bash # Email Sending (Resend — Free 3000 emails/month) export RESEND_API_KEY="re_xxxxxxxxxxxx" export RESEND_FROM_EMAIL="your-verified@yourdomain.com" # Get: https://resend.com/api-keys # Customer Discovery (Google Custom Search — Free 100 searches/day) export GOOGLE_SEARCH_API_KEY="your-api-key" export GOOGLE_SEARCH_CSE_ID="your-cse-id" # Get: https://developers.google.com/custom-search/v1/overview # Create CSE: https://programmablesearchengine.google.com/ # Cost Control (Optional) export MAX_LOOPS=5 # Maximum Tool Calls per Round export COST_BUDGET=0.10 # Cost Budget per Round (USD), 0 or empty = unlimited ``` > **Note**: When API Key is not configured, the corresponding tool will return guidance information instead of crashing. Deterministic tools and demo tools do not require configuration. ### 3. Start Service ```bash python server.py # Service starts at http://localhost:8000/mcp ``` ### 4. MCP Client Configuration ```json { "mcpServers": { "silicon-army": { "url": "http://localhost:8000/mcp", "type": "streamable-http" } } } ``` ## Deterministic Priority Layer The deterministic priority layer checks if a real tool can be directly answered by a rule / regular expression / table lookup before calling the real tool: ``` User Request → Deterministic Check → Hit? → Direct Return (Zero Cost) ↓ Miss Call Real Tool / API ``` - **HS Code Verification**: Regular expression matching 4-10 digits, automatically removing dots and spaces - **Country Code Inquiry**: 50+ common country English / ISO2 / ISO3 mutual inquiry, O(1) table lookup - **Email Format Verification**: RFC compatible regular expression - **Phone Format Verification**: E.164 international format + country code extraction - **Exchange Rate Cache**: Free from `open.er-api.com`, 1-hour local cache ## Parallel Tool Call Use the `batch_execute` tool to execute multiple independent calls in parallel: ```python # Query import data + find suppliers + search customers batch_execute(calls=[ {"tool": "query_import_data", "arguments": {"hs_code": "854140", "country": "Germany"}}, {"tool": "find_suppliers_by_product", "arguments": {"product_keyword": "LED lighting"}}, {"tool": "discover_customers", "arguments": {"keyword": "LED lighting", "market": "Germany"}} ]) ``` **Cost Control Mechanism**: - `MAX_LOOPS`: Limit the maximum number of tool calls per round (default 5) - `COST_BUDGET`: Limit the estimated cost per round (default unlimited) - `Replan-not-retry`: Return current status + replanning suggestions when a step fails, instead of blindly retrying ## PII Desensitization Automatically desensitize email and phone numbers in return results: - Email: `contact@acme.com` → `c***@acme.com` - Phone: `+8613800138000` → `+86****00` ## Docker Deployment ```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 ``` ## Use MCP Inspector Test ```bash npx -y @modelcontextprotocol/inspector # Connect to http://localhost:8000/mcp ``` ## Environment Variables | Variable Name | Purpose | Required | Default Value | | --- | --- | --- | --- | | `RESEND_API_KEY` | Resend Email API | Required for Email Function | - | | `RESEND_FROM_EMAIL` | Sender Email | No | `onboarding@resend.dev` | | `GOOGLE_SEARCH_API_KEY` | Google CSE API Key | Required for Customer Discovery | - | | `GOOGLE_SEARCH_CSE_ID` | Google CSE Engine ID | Required for Customer Discovery | - | | `WHATSAPP_TOKEN` | WhatsApp Business API (Reserved) | No | - | | `WHATSAPP_PHONE_ID` | WhatsApp Phone ID (Reserved) | No | - | | `MAX_LOOPS` | Maximum Tool Calls per Round | No | 5 | | `COST_BUDGET` | Cost Budget per Round (USD) | No | Unlimited | ## Applicable Scenarios - 🎯 **Cross-Border E-Commerce Customer Development**: AI automatically discovers potential buyers → sends development emails → tracks → follows up - 📊 **Customs Data Analysis**: Import and export data query, market trend analysis, competitor monitoring - 📧 **Multi-Channel Marketing Outreach**: Email (Resend) + WhatsApp dual channels, batch sending + tracking - 🔍 **Supplier Search**: Screen suppliers from Alibaba by product keywords - ⚡ **Efficient Parallel Query**: One call executes multiple independent tools simultaneously, reducing latency ## Technical Architecture - **Framework**: FastMCP (Python) — MCP 2025-03-26 Protocol - **Transport**: Streamable HTTP - **Parallel**: asyncio + semaphore (concurrency 5) - **Cache**: Exchange rate local cache (TTL 1 hour) - **Security**: PII automatic desensitization + environment variable management key - **Deployment**: Docker containerization ## License MIT License - See [LICENSE](LICENSE) ## About **Hangzhou Yunlv Technology Co., Ltd.** — Focus on AI + Foreign Trade Intelligent Body Product Research and Development - Email: wxy13336021626@foxmail.com - Brand Matrix: Yunlv AI (Company Brand) / Foreign Trade Silicon-Based Legion (Product Line) / Baique AI (Product Name)