内容
# 电子商务MCP服务器
用于从印度主要电子商务平台搜索、价格比较和详情提取的生产级高并发模型上下文协议（MCP）服务器：**Amazon.in**、**Flipkart**、**Meesho** 和 **Myntra**。
该服务器设计为双重部署模式：
1. **本地模式（STDIO）**：直接与本地LLM客户端（如Claude Desktop、Cursor或VS Code）集成。
2. **部署服务器模式（SSE/HTTP）**：在Docker中作为隔离的Web服务运行，托管在云提供商（Render、Railway、Fly.io、AWS）上，并具有API密钥身份验证。
---
## 生产架构概述
系统分为清晰的架构层，以强制执行关注点分离、可扩展性和可测试性。
```mermaid
graph TD
Client[MCP Client: Cursor / Claude / Custom SSE Client] --> |STDIO / SSE| Entrypoint[MCP Server Layer: FastMCP]
Entrypoint --> Auth[Auth & Rate Limiting Middleware]
Auth --> Tools[MCP Tools: search, compare, details]
Tools --> Cache[Caching Layer: SQLite / Redis]
Cache --> ScraperManager[Scraper Coordinator]
subgraph Scraping Engine
ScraperManager --> |Parallel Tasks| AmazonScraper[Amazon Scraper]
ScraperManager --> FlipkartScraper[Flipkart Scraper]
ScraperManager --> MeeshoScraper[Meesho Scraper]
ScraperManager --> MyntraScraper[Myntra Scraper]
end
subgraph Browser Management Pool
AmazonScraper & FlipkartScraper & MeeshoScraper & MyntraScraper --> BrowserPool[Browser Context Pool]
BrowserPool --> |Semaphore Throttled| PW[Playwright Chromium Instances]
PW --> Proxies[Rotating Proxy Gateway]
end
subgraph System & Operations
Logger[Structured Logger: STDERR / Files]
Metrics[Prometheus Metrics Engine]
SignalHandler[SIGTERM / SIGINT Cleanup]
end
```
---
## 功能
* **双协议支持**：在STDIO（本地）和SSE（服务器发送事件）之间即时切换。
* **动态浏览器上下文池**：使用Playwright的无痕浏览器上下文池，通过信号量限制以最大化搜索并发性，同时限制RAM/CPU使用。
* **嵌入式SQLite WAL缓存**：零开销本地数据库（`data/mcp_cache.db`）在WAL（预写日志）模式下运行。缓存平台搜索（10分钟TTL）和产品规格（24小时TTL）。
* **状态Cookie保存**：保存浏览器会话Cookie以最小化反机器人登录挑战的频率。
* **高级反机器人逃避**：伪造语言、插件、WebGL图形渲染器，掩盖`navigator.webdriver`标志，并使用类似人类的鼠标/滚动模式。
* **自我纠正价格**：智能解析价格网格，排序当前销售价格和原始MRP，而不依赖于特定的字符编码符号。
* **JSON脚本提取**：从React脚本（`window.__myx`）中读取Myntra和Meesho搜索和PDP值，使用多行正则表达式模式（`re.DOTALL`）。
---
## 项目结构
```text
ecommerce-mcp/
├── Dockerfile # 生产容器定义（预加载Playwright）
├── requirements.txt # 应用程序依赖项
├── pyproject.toml # Pytest配置
├── .env.example # 配置模板
├── .gitignore
│
├── config/
│ └── settings.py # 通过Pydantic Settings配置模式
│
├── data/ # 持久化SQLite缓存存储目录
├── logs/ # 持久化应用程序日志目录
│
├── src/ # 核心代码库
│ ├── main.py # 主要服务器CLI入口点
│ ├── core/ # 低级系统（浏览器池、WAL缓存、DB、日志记录、身份验证）
│ ├── schemas/ # Pydantic数据契约（产品、比较结果、详情）
│ ├── scrapers/ # 提取器子模块（Amazon、Flipkart、Meesho、Myntra）
│ └── tools/ # MCP协议操作（搜索、比较、详情）
│
└── tests/ # 测试套件（使用模拟路由器进行100%离线运行）
```
---
## 本地安装和设置
### 1. 先决条件
确保已安装Python 3.12+。
### 2. 安装依赖项
克隆存储库并设置虚拟环境：
```bash
# 创建虚拟环境
python -m venv .venv
# 激活虚拟环境（Windows PowerShell）
& .venv/Scripts/Activate.ps1
# 激活虚拟环境（macOS/Linux）
source .venv/bin/activate
# 安装依赖项
pip install -r requirements.txt
# 安装Playwright Chromium二进制文件
playwright install chromium
```
### 3. 配置设置
复制`.env.example`到`.env`并填写任何旋转住宅代理凭证（强烈建议用于生产服务器以防止数据中心IP阻止）。
```bash
cp .env.example .env
```
---
## 本地运行（离线模式）
在本地计算机上运行服务器是使用它的推荐方式，因为它避免了任何无服务器资源限制（如`/tmp`存储容量），并且具有完全的文件系统写入权限。
### 步骤1：初始化本地虚拟环境
确保已创建、激活虚拟环境并安装所有依赖项：
```bash
# 创建虚拟环境
python -m venv .venv
# 激活虚拟环境
# Windows（PowerShell）：
& .venv/Scripts/Activate.ps1
# Windows（cmd）：
.venv\Scripts\activate.bat
# macOS/Linux：
source .venv/bin/activate
# 安装依赖项（包括Playwright）
pip install -r requirements.txt
# 在本地安装Playwright Chromium二进制文件
playwright install chromium
```
### 步骤2：设置本地环境变量
在项目根目录中创建`.env`文件以设置您的密钥：
```env
GROQ_API_KEY=your_groq_api_key_here
# 可选配置参数：
HEADLESS=true
PORT=8000
```
### 步骤3：本地运行服务器
#### 选项A：作为HTTP/SSE服务运行（端口8000）
要将服务器作为HTTP/SSE Web服务运行，您可以通过HTTP请求或本地测试客户端进行查询：
```bash
# Windows：
.venv\Scripts\python.exe src/main.py --transport sse --port 8000
# macOS/Linux：
.venv/bin/python src/main.py --transport sse --port 8000
```
这将启动Uvicorn，在`http://localhost:8000/mcp`上托管无状态SSE端点。您可以使用以下命令在本地测试它：
```bash
# 运行本地客户端测试脚本
.venv\Scripts\python.exe test_client.py
```
#### 选项B：连接到Claude Desktop（本地STDIO模式）
要将此本地服务器直接集成到**Claude Desktop**：
1. 打开Claude Desktop配置文件：
* Windows路径：`%APPDATA%\Claude\claude_desktop_config.json`
* macOS路径：`~/Library/Application Support/Claude/claude_desktop_config.json`
2. 将本地服务器路径添加到配置中：
```json
{
"mcpServers": {
"ecommerce-scraper-local": {
"command": "c:\\Users\\DELL\\Desktop\\Ecommerce-mcp\\.venv\\Scripts\\python.exe",
"args": ["c:\\Users\\DELL\\Desktop\\Ecommerce-mcp\\src\\main.py", "--transport", "stdio", "--headful"],
"env": {
"GROQ_API_KEY": "your_groq_api_key_here"
}
}
}
}
```
*(注意：如果您希望在后台运行抓取程序而不显示浏览器窗口，可以从参数中省略`"--headful"`。)*
3. 重启Claude Desktop。工具将出现在提示框中！
#### 选项C：连接到Cursor（本地STDIO模式）
要将此本地服务器添加到**Cursor**：
1. 打开Cursor并转到**设置** > **功能** > **MCP**。
2. 点击**+ 添加新的MCP服务器**。
3. 填写详细信息：
* **名称**：`ecommerce-local`
* **类型**：`command`
* **命令**：`c:\Users\DELL\Desktop\Ecommerce-mcp\.venv\Scripts\python.exe c:\Users\DELL\Desktop\Ecommerce-mcp\src\main.py --transport stdio --headful`
4. 点击**保存**。
---
## 绕过机器人检测和离线访问（手动运行）
由于电子商务平台（Amazon、Flipkart、Meesho、Myntra）使用高级反机器人系统（例如Akamai、Cloudflare或HTTP/2帧层面的协议阻止），来自数据中心或本地终端的无头自动化抓取有时可能会被阻止。
要在本地计算机上可靠地使用抓取器，您应该在**手动/有头模式**下运行它或配置代理：
### 1. 以有头模式运行（手动验证）
在有头模式下运行服务器会在您的桌面上启动真正的Chromium浏览器窗口。抓取本地数据时强烈建议这样做：
* **如何运行**：在`.env`文件中更改`HEADLESS=false`或使用`--headful` CLI标志启动服务器：
```bash
.venv\Scripts\python.exe src/main.py --transport sse --port 9000 --headful
```
* **绕过CAPTCHA**：如果网站（例如Amazon或Flipkart）显示机器人验证屏幕，您将看到浏览器窗口在屏幕上弹出。您只需在浏览器窗口中手动解决CAPTCHA。
* **状态保存**：解决后，服务器自动保存会话Cookie。后续在该平台上的搜索将使用Cookie并自动绕过挑战。
### 2. 离线模式（WAL缓存）
服务器具有内置的SQLite预写日志缓存系统，位于`data/mcp_cache.db`：
* **零Web流量**：搜索查询缓存10分钟，深层产品规格/详情缓存24小时。
* **离线访问**：如果您搜索已抓取的查询或产品，MCP服务器会直接从SQLite缓存数据库返回它，而无需触发任何浏览器操作，也无需互联网连接。
* 这允许您完全离线工作，立即查询缓存的产品，并防止机器人阻止！
### 3. 设置旋转代理（可选）
如果您希望在不进行手动干预的情况下大规模运行无头抓取，请在`.env`文件中配置旋转住宅代理：
```env
PROXY_SERVER=http://your-proxy-provider.com:8000
PROXY_USERNAME=your_username
PROXY_PASSWORD=your_password
```
---
## 生产容器部署（Docker）
要部署到Render、Railway或AWS等云服务：
### 1. 构建Docker镜像
```bash
docker build -t ecommerce-mcp .
```
### 2. 运行容器
传递您的安全`API_KEY`令牌和可选的代理网关作为环境变量：
```bash
docker run -d \
-p 8000:8000 \
-e TRANSPORT=sse \
-e API_KEY=my_secure_secret_token_123 \
-e PROXY_SERVER=http://myproxyprovider.com:8000 \
-e PROXY_USERNAME=user \
-e PROXY_PASSWORD=pass \
--name ecommerce-mcp-server \
ecommerce-mcp
```
### 3. 连接到已部署的SSE服务器
连接到已部署服务器的MCP客户端将发送订阅服务器流的请求帧：
* 端点：`http://<your-domain>/sse`
* 头部身份验证（如果设置了`API_KEY`）：`Authorization: Bearer my_secure_secret_token_123`
---
## 部署到FastMCP云（Prefect Horizon）
Prefect Horizon是由FastMCP团队构建的托管平台，用于托管MCP服务器。它使用Git驱动的部署：
1. **提交和推送**：确保所有更改和`fastmcp.json`都已提交并推送到您的GitHub存储库。
2. **连接到Horizon**：
- 进入您的Prefect Horizon/FastMCP云仪表板。
- 点击“部署服务器”并授权您的GitHub帐户。
- 选择您的`ecommerce-mcp`存储库。
3. **触发构建**：FastMCP云将解析`fastmcp.json`配置，自动安装Pytest/Playwright依赖项，在后台启动Chromium，并将服务器部署为安全的HTTPS端点。
---
## MCP工具模式
服务器向LLM注册了3个操作：
1. `search_products`：查询选定的平台并发返回聚合列表。
* 参数：`query`（str），`platforms`（list[str]，默认为全部），`limit`（int，默认为5）。
2. `compare_prices`：抓取平台，聚合项目，按价格排序，并标记最便宜的产品。
* 参数：`query`（str），`platforms`（list[str]，默认为全部）。
3. `get_product_details`：获取完整的产品描述，规格，图像URL，库存状态和商家销售名称。
* 参数：`url`（str），`platform`（str）。
---
## 运行测试
所有测试都通过Playwright的`route`拦截器路由网络调用，使测试套件能够完全离线运行。
```bash
# 运行所有测试
pytest -vv
```
