# MCP Product Search Server

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的产品搜索服务器，让 Claude 能够根据关键词检索产品目录并返回结构化数据。

## 功能

提供三个工具供 Claude 调用：

| 工具 | 说明 |
|---|---|
| `search` | 按关键词搜索产品，支持分类、价格、评分过滤 |
| `list_categories` | 列出所有产品分类及数量 |
| `get_product` | 按 ID 查询单个产品的完整信息 |

## 快速开始

### 1. 克隆项目

```bash
git clone <your-repo-url>
cd mcp-product-search
```

### 2. 创建虚拟环境并安装依赖

**macOS / Linux：**

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]"
```

**Windows：**

```bash
python -m venv .venv
.venv\Scripts\activate
pip install "mcp[cli]"
```

> 需要 Python 3.10 及以上版本。可用 `python3 --version` 检查。

### 3. 在浏览器中测试

```bash
mcp dev server.py
```

浏览器会自动打开 MCP Inspector。如果没有自动打开，手动访问终端输出的地址（通常是 `http://localhost:6274`）。

**连接步骤：**

1. 将左侧 **Command** 改为虚拟环境中 Python 的绝对路径：
   - macOS/Linux：`/绝对路径/mcp-product-search/.venv/bin/python`
   - Windows：`C:\绝对路径\mcp-product-search\.venv\Scripts\python.exe`
2. **Arguments** 填 `server.py`
3. 点击 **Connect**，左下角显示 **Connected** 即成功
4. 点击顶部 **Tools** 标签，选择工具，填写参数，点击 **Run Tool**

![MCP Inspector 连接成功示意](https://modelcontextprotocol.io/images/inspector.png)

### 4. 接入 Claude Desktop

找到配置文件：
- **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`

添加以下内容（替换为实际的绝对路径）：

```json
{
  "mcpServers": {
    "product-search": {
      "command": "/绝对路径/mcp-product-search/.venv/bin/python",
      "args": ["/绝对路径/mcp-product-search/server.py"]
    }
  }
}
```

**查看当前目录的绝对路径：**

```bash
# macOS / Linux
pwd

# Windows
cd
```

保存配置文件后，**完全退出并重启 Claude Desktop**。

### 5. 接入 Claude Code（命令行）

```bash
claude mcp add product-search \
  /绝对路径/mcp-product-search/.venv/bin/python \
  /绝对路径/mcp-product-search/server.py
```

## 使用示例

接入 Claude 后，可以这样提问：

```
帮我搜索苹果品牌的笔记本电脑
找一款评分 4.8 以上、价格不超过 300 美元的耳机
列出所有产品分类
查询产品 P003 的详细信息
```

Claude 会自动判断调用哪个工具，并基于返回的结构化数据给出回答。

## 工具参数说明

### `search`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `keyword` | string | 是 | — | 匹配产品名称、描述、品牌、分类和标签 |
| `category` | string | 否 | — | 按分类过滤，如 `"Laptops"`、`"Headphones"` |
| `max_price` | float | 否 | — | 最高价格（USD） |
| `min_rating` | float | 否 | — | 最低评分（0–5） |
| `limit` | int | 否 | `10` | 返回结果数量上限（最多 50） |

返回结果按评分从高到低、价格从低到高排序。

**返回示例：**

```json
{
  "keyword": "apple",
  "filters": { "category": "Laptops", "max_price": null, "min_rating": null },
  "total_results": 1,
  "products": [
    {
      "id": "P001",
      "name": "Apple MacBook Pro 14-inch M3",
      "category": "Laptops",
      "brand": "Apple",
      "price": 1999.0,
      "currency": "USD",
      "stock": 42,
      "rating": 4.8,
      "description": "14-inch Liquid Retina XDR display, M3 chip, 18GB RAM, 512GB SSD.",
      "tags": ["laptop", "apple", "macbook", "m3", "professional", "portable"]
    }
  ]
}
```

### `list_categories`

无参数。返回所有分类名称及对应产品数量。

### `get_product`

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `product_id` | string | 是 | 产品 ID，如 `"P001"`（不区分大小写） |

## 项目结构

```
mcp-product-search/
├── server.py        # MCP 服务器，定义工具
├── products.py      # 产品目录与搜索逻辑
├── pyproject.toml   # 项目依赖
└── README.md
```

## 扩展产品数据

当前产品目录是写在 `products.py` 中的 12 条示例数据，替换为真实数据只需修改 `search_products()` 函数，`server.py` 无需改动。

| 数据来源 | 改法 |
|---|---|
| 本地 JSON/CSV | 启动时读文件填充 `CATALOG` |
| SQLite / PostgreSQL | 用 SQL 查询替换遍历逻辑 |
| 电商 API | 函数内部发 HTTP 请求 |
| Elasticsearch | 调用 ES 全文搜索接口 |