Mercari MCP 服务器

一个用于搜索Mercari商品的MCP（Model Context Protocol）智能体工具。

功能特性

• 🔍 关键词搜索：根据关键词搜索Mercari商品
• 📋 商品详情：获取特定商品的详细信息
• 🏷️ 分类搜索：按商品分类进行搜索
• 💰 价格筛选：支持价格范围过滤
• 📦 状态筛选：根据商品状态筛选
• 📊 排序选项：支持多种排序方式
• 🔄 分页浏览：支持分页查看搜索结果

依赖项

• Python 3.8+
• MCP SDK
• mercapi
• pydantic
• httpx

安装

1. 克隆项目：

git clone <repository-url>
cd mercari-mcp

2. 安装依赖：

pip install -e .

或者使用虚拟环境：

python -m venv .venv
source .venv/bin/activate  # 在Windows上使用: .venv\Scripts\activate
pip install -e .

使用方法

作为MCP服务器运行

1. stdio模式（标准输入输出）

python -m mercari_mcp.server

2. SSE模式（Server-Sent Events）

python scripts/run_sse_server.py

或者指定端口和主机：

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 (可选): 每页数量

示例：

{
  "keyword": "iPhone",
  "price_min": 10000,
  "price_max": 50000,
  "condition": "like_new",
  "sort": "price",
  "order": "asc"
}

2. get_mercari_item_detail

获取商品详情

参数：

• item_id (必需): 商品ID

示例：

{
  "item_id": "m12345678"
}

3. search_mercari_by_category

按分类搜索商品

参数：

• category_name (必需): 分类名称
• price_min (可选): 最低价格
• price_max (可选): 最高价格
• condition (可选): 商品状态
• sort (可选): 排序方式
• page (可选): 页码
• limit (可选): 每页数量

示例：

{
  "category_name": "电子产品",
  "price_min": 5000,
  "price_max": 30000
}

配置

MCP客户端配置

stdio模式配置

在您的MCP客户端配置中添加以下内容：

{
  "mcpServers": {
    "mercari-mcp": {
      "command": "python",
      "args": ["-m", "mercari_mcp.server"]
    }
  }
}

SSE模式配置

在您的MCP客户端配置中添加以下内容：

{
  "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. 安装开发依赖：

pip install -e ".[dev]"

2. 运行测试：

pytest

3. 代码格式化：

black src/
isort src/

4. 类型检查：

mypy src/

测试

测试stdio模式

python scripts/test_mcp.py

测试SSE模式

首先启动SSE服务器：

python scripts/run_sse_server.py

然后在另一个终端运行测试：

python scripts/test_sse_server.py

故障排除

常见问题

1. 模块导入错误

   • 确保已正确安装所有依赖
   • 检查Python路径和虚拟环境

2. API调用失败

   • 检查网络连接
   • 确认mercapi库是否正确安装

3. MCP连接问题

   • 检查MCP客户端配置
   • 确认服务器正在运行

调试

启用调试日志：

export PYTHONPATH=src
python -m mercari_mcp.server --log-level DEBUG

许可证

MIT License

贡献

欢迎提交问题和合并请求！

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

更新日志

v0.1.0

• 初始版本
• 基本的商品搜索功能
• 商品详情获取功能
• 分类搜索功能