# Mercari MCP 服务器
一个用于搜索Mercari商品的MCP（Model Context Protocol）智能体工具。
## 功能特性
- 🔍 **关键词搜索**：根据关键词搜索Mercari商品
- 📋 **商品详情**：获取特定商品的详细信息
- 🏷️ **分类搜索**：按商品分类进行搜索
- 💰 **价格筛选**：支持价格范围过滤
- 📦 **状态筛选**：根据商品状态筛选
- 📊 **排序选项**：支持多种排序方式
- 🔄 **分页浏览**：支持分页查看搜索结果
## 依赖项
- Python 3.8+
- MCP SDK
- mercapi
- pydantic
- httpx
## 安装
1. 克隆项目：
```bash
git clone <repository-url>
cd mercari-mcp
```
2. 安装依赖：
```bash
pip install -e .
```
或者使用虚拟环境：
```bash
python -m venv .venv
source .venv/bin/activate # 在Windows上使用: .venv\Scripts\activate
pip install -e .
```
## 使用方法
### 作为MCP服务器运行
#### 1. stdio模式（标准输入输出）
```bash
python -m mercari_mcp.server
```
#### 2. SSE模式（Server-Sent Events）
```bash
python scripts/run_sse_server.py
```
或者指定端口和主机：
```bash
python scripts/run_sse_server.py --host 127.0.0.1 --port 8000
```
SSE模式提供以下端点：
- 🏠 服务器地址: http://127.0.0.1:8000
- 📡 SSE端点: http://127.0.0.1:8000/sse
- 🛠️ 工具列表: http://127.0.0.1:8000/tools
- 🔧 调用工具: POST http://127.0.0.1:8000/tools/{tool_name}
- 🏥 健康检查: http://127.0.0.1:8000/health
### 工具列表
#### 1. search_mercari_items
搜索Mercari商品
**参数：**
- `keyword` (必需): 搜索关键词
- `category_id` (可选): 分类ID
- `brand_id` (可选): 品牌ID
- `price_min` (可选): 最低价格
- `price_max` (可选): 最高价格
- `condition` (可选): 商品状态 (new, like_new, good, fair, poor)
- `sort` (可选): 排序方式 (created_time, price, popular)
- `order` (可选): 排序顺序 (asc, desc)
- `page` (可选): 页码
- `limit` (可选): 每页数量
**示例：**
```json
{
"keyword": "iPhone",
"price_min": 10000,
"price_max": 50000,
"condition": "like_new",
"sort": "price",
"order": "asc"
}
```
#### 2. get_mercari_item_detail
获取商品详情
**参数：**
- `item_id` (必需): 商品ID
**示例：**
```json
{
"item_id": "m12345678"
}
```
#### 3. search_mercari_by_category
按分类搜索商品
**参数：**
- `category_name` (必需): 分类名称
- `price_min` (可选): 最低价格
- `price_max` (可选): 最高价格
- `condition` (可选): 商品状态
- `sort` (可选): 排序方式
- `page` (可选): 页码
- `limit` (可选): 每页数量
**示例：**
```json
{
"category_name": "电子产品",
"price_min": 5000,
"price_max": 30000
}
```
## 配置
### MCP客户端配置
#### stdio模式配置
在您的MCP客户端配置中添加以下内容：
```json
{
"mcpServers": {
"mercari-mcp": {
"command": "python",
"args": ["-m", "mercari_mcp.server"]
}
}
}
```
#### SSE模式配置
在您的MCP客户端配置中添加以下内容：
```json
{
"mcpServers": {
"mercari-mcp-sse": {
"url": "http://127.0.0.1:8000/sse",
"description": "Mercari商品搜索MCP服务器（SSE模式）",
"transport": "sse"
}
}
}
```
### 环境变量
目前暂无特殊环境变量需要设置。
## 开发
### 项目结构
```
mercari-mcp/
├── src/
│ └── mercari_mcp/
│ ├── __init__.py
│ ├── server.py # MCP服务器主文件
│ └── mercapi_client.py # Mercapi客户端包装器
├── pyproject.toml
├── README.md
└── requirements.txt
```
### 开发环境设置
1. 安装开发依赖：
```bash
pip install -e ".[dev]"
```
2. 运行测试：
```bash
pytest
```
3. 代码格式化：
```bash
black src/
isort src/
```
4. 类型检查：
```bash
mypy src/
```
### 测试
#### 测试stdio模式
```bash
python scripts/test_mcp.py
```
#### 测试SSE模式
首先启动SSE服务器：
```bash
python scripts/run_sse_server.py
```
然后在另一个终端运行测试：
```bash
python scripts/test_sse_server.py
```
## 故障排除
### 常见问题
1. **模块导入错误**
- 确保已正确安装所有依赖
- 检查Python路径和虚拟环境
2. **API调用失败**
- 检查网络连接
- 确认mercapi库是否正确安装
3. **MCP连接问题**
- 检查MCP客户端配置
- 确认服务器正在运行
### 调试
启用调试日志：
```bash
export PYTHONPATH=src
python -m mercari_mcp.server --log-level DEBUG
```
## 许可证
MIT License
## 贡献
欢迎提交问题和合并请求！
1. Fork项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request
## 更新日志
### v0.1.0
- 初始版本
- 基本的商品搜索功能
- 商品详情获取功能
- 分类搜索功能
