SW MCP Project

#公开软件第11条团队项目

此存储库用于管理第11条公开软件中的团队项目。目标是系统地记录需求、实施代码和交付项，并保持协作流程。

项目概述

MCP服务器-产品信息收集和分析系统

目标：实施MCP服务器，快速收集和加工详细信息，以便用户判断是否购买特定产品。

主要功能

1. 产品名称规范化：将用户输入转换为制造商标准的正式型号名称
2. 滚动图像：在田川等购物中心收集产品详细页面图像
3. Base64编码：将抓取的图像从内存编码为Base64，以供LLM访问
4. 产品比较：同时规范多个产品并收集图像，以差异为主进行比较分析

系统流

单产品分析

1. 在LLM界面中以自然语言输入您想要的产品。
2. MCP服务器将输入规范化为制造商标准的正式型号名称。
3. 使用标准化的型号名称抓取每个制造商和分销商的详细页面图像。
4. 将图像编码为Base64并传递给LLM。
5. 分析LLM收集的图像，得出主要规格、优缺点、推荐与否等。

产品比较分析

1. 在LLM界面中输入用户想要比较的多个产品。
2. MCP服务器对每个产品进行规范化并收集图像。
3. 将收集的信息结构化并传递给LLM。
4. LLM将围绕产品之间的差异（设计、特性、价位等）进行比较分析。

角色分担

• MCP服务器：负责规范化、滚动、数据加工等管线
• 前端/客户端：可视化结果，帮助您做出决策。

技术堆栈

• 后端：FastAPI
• MCP服务器：fastmcp（Anthropic Claude MCP协议）
• 网络爬虫：Playwright（异步）
• 数据处理：Python 3.x
• API：RESTful API

安装方法

1.存储库克隆

git clone 
cd SW_MCP_Project

2.创建和激活Python虚拟环境

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

3.安装依赖性

FastAPI服务器依赖性

cd fastapi
pip install -r requirements.txt

MCP服务器依赖性（使用MCP服务器时）

# 루트 디렉터리에서
pip install mcp anyio

或者一次性安装所有依赖性：

# 루트 디렉터리에서
pip install -r fastapi/requirements.txt
pip install mcp anyio

4.安装Playwright浏览器

playwright install chromium

参考：Playwright用于抓取图像，以异步方式工作。

项目结构

SW_MCP_Project/
├── fastapi/                        # FastAPI 백엔드 서버
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py                 # FastAPI 애플리케이션 및 REST API 엔드포인트
│   │   ├── normalize_product_name.py  # 제품명 정규화 로직 (다나와 검색)
│   │   ├── new_single_page_crawler.py # 이미지 크롤링 로직 (Playwright)
│   │   ├── compare_products.py     # 제품 비교 로직 (정규화 + 이미지 수집)
│   │   └── schemas.py              # Pydantic 스키마 정의
│   └── requirements.txt            # FastAPI 서버 의존성
├── mcp_server.py                   # MCP 서버 엔트리포인트 (Claude 연동)
├── mcp_config.json                  # MCP 서버 설정 파일 (Claude Desktop/Cursor용)
├── README.md                        # 프로젝트 문서
└── .gitignore                       # Git 무시 파일

主要文件说明

• fastapi/app/main.py：FastAPI REST API服务器。 /normalize-product-name, /crawl, /compare-products 提供端点
• fastapi/app/normalize_product_name.py：在达那瓦搜索产品名称并提取型号名称/URL
• fastapi/app/new_single_page_crawler.py：使用Playwright进行动态页面滚动和图像Base64编码
• fastapi/app/compare_products.py：用于比较多个产品的业务逻辑。集成产品规范化和图像收集
• mcp_server.py：通过MCP协议与Claude通信的服务器。将FastAPI逻辑作为MCP Tool公开
• mcp_config.json：在Claude Desktop/Cursor中注册MCP服务器的配置文件示例

API端点

1.产品名称正规化

发布 /normalize-product-name

将产品名称转换为型号名称和URL并保存。

请求：

{
  "product_name": "삼성 블루스카이 5500"
}

答复：

{
  "product_name": "삼성 블루스카이 5500",
  "model_name": "AX060CG500G",
  "url": "http://prod.danawa.com/info/...",
  "saved": true,
  "message": "제품명 '삼성 블루스카이 5500'이 모델명 'AX060CG500G'과 URL로 저장되었습니다."
}

2.滚动图像

发布 /crawl

使用保存的产品URL抓取图像并将其编码为Base64。

请求：

{
  "product_name": "삼성 블루스카이 5500"
}

答复：

{
  "product_name": "삼성 블루스카이 5500",
  "url": "http://prod.danawa.com/info/...",
  "image_count": 2,
  "images": [
    {
      "url": "https://...",
      "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mime_type": "image/jpeg",
      "index": 1,
      "original_size_bytes": 245760,
      "optimized_size_bytes": 89234
    },
    {
      "url": "https://...",
      "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mime_type": "image/png",
      "index": 2,
      "original_size_bytes": 189234,
      "optimized_size_bytes": 87654
    }
  ],
  "success": true,
  "message": "제품 '삼성 블루스카이 5500'의 이미지 2개를 성공적으로 크롤링하고 base64로 인코딩했습니다."
}

3.产品比较

发布 /compare-products

输入两个或多个产品名称，规范每个产品，收集图像并以可比较的形式返回。

请求：

{
  "product_names": ["삼성 블루스카이 5500", "블루스카이 7000"]
}

答复：

{
  "products": [
    {
      "product_name": "삼성 블루스카이 5500",
      "model_name": "AX060CG500G",
      "url": "http://prod.danawa.com/info/...",
      "image_count": 2,
      "images": [
        {
          "url": "https://...",
          "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
          "mime_type": "image/jpeg",
          "index": 1,
          "original_size_bytes": 245760,
          "optimized_size_bytes": 89234
        }
      ]
    },
    {
      "product_name": "블루스카이 7000",
      "model_name": "AX060CG700G",
      "url": "http://prod.danawa.com/info/...",
      "image_count": 3,
      "images": [...]
    }
  ],
  "total_products": 2,
  "success": true,
  "message": "2개 제품의 정보를 수집했습니다.\n\n[비교 가이드]\n수집된 제품 정보를 바탕으로 다음 항목을 중심으로 차이점을 비교해주세요:\n1. 제품 디자인: 색상, 형태, 크기 등의 차이\n2. 제품 특징: 기능, 성능, 사양 등의 차이\n3. 가격대: 다나와 링크를 통해 최신 가격 확인 가능\n4. 주요 차이점: 각 제품의 고유한 특징과 장단점\n\n공통점보다는 차이점에 집중하여 비교 설명해주세요.",
  "comparison_hint": {
    "focus": "차이점",
    "comparison_points": [
      "제품 디자인 (색상, 형태, 크기)",
      "제품 특징 (기능, 성능, 사양)",
      "가격대",
      "주요 차이점 및 고유 특징"
    ],
    "note": "공통점보다는 차이점에 집중하여 비교해주세요."
  }
}

使用方法

1.运行服务器

cd fastapi
python -m app.main
# 또는
uvicorn app.main:app --reload

服务器基本上 http://localhost:8000在中运行。

1-1.运行MCP服务器（Claude联动）

使用MCP服务器，您可以直接从Claude Desktop或Cursor分析产品信息。

设置方法

1. MCP依赖性安装 （如果尚未安装）

   pip install mcp anyio

1. 将服务器添加到MCP设置文件

对于Claude Desktop：

- 窗户： %APPDATA%\Claude\claude_desktop_config.json - 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

在配置文件中添加以下内容：

   {
     "mcpServers": {
       "product-analyzer": {
         "command": "python",
         "args": ["mcp_server.py"],
         "cwd": "C:\\Users\\home\\Desktop\\sw\\SW_MCP_Project",
         "env": {}
       }
     }
   }

注意: cwd 请将路径更改为实际项目路径。

对于Cursor：

- 在设置中添加MCP服务器或 - mcp_config.json 将文件的内容复制到Cursor的MCP设置中。

1. 重新启动Claude Desktop/Cursor

- 修改配置文件后，必须重新启动Claude Desktop或Cursor。

提供的MCP Tools

MCP服务器提供三种工具：

1. normalize_product_name

- 将自然语言产品名称规范化为制造商型号名称和商品URL - 示例：“三星蓝天5500”→型号“AX060CG500G”+URL

1. crawl_product_images

- 在保存的产品URL中最多滚动4张图像 - 编码为Base64并转发给Claude - 注意：首先 normalize_product_name必须调用。

1. compare_products

- 输入两个或多个产品名称来规范每个产品并收集图像 - 提供结构化数据以进行比较分析 - 专注于设计、特性、价位等方面的差异

使用示例

在Claude中可以使用：

"삼성 블루스카이 5500"과 "블루스카이 7000"을 비교해줘

或单产品分析：

"삼성 블루스카이 5500" 제품에 대해 분석해줘

Claude自动调用所需的MCP Tool收集和分析产品信息。

2.检查API文档

在浏览器中 http://localhost:8000/docs 您可以连接并在Swagger UI中测试API。

主要功能说明

产品名称规范化（normalize_product_name.py)

• 在达纳瓦按产品名称搜索
• 提取第一个结果的模型名
• 产品名称转换自动处理（如“三星蓝天”→“三星电子蓝天”、“LG”→“LG电子”）
• Playwright失败时基于requests/BeautifulSoup的回退处理
• 将模型名和URL存储在内存中

滚动图像（new_single_page_crawler.py)

• 使用Playwright滚动动态页面
• [id^="partContents_"] 收集选择器中的图像
• 将图像编码为Base64并返回
• 为了应对Claude限制（图像1MB），最多提取4张，并使用Pillow自动缩放/重新压缩
• 提供原始和优化的图像大小信息（original_size_bytes, optimized_size_bytes)
• Windows事件循环疑难解答（在单独的线程中运行）

产品比较（compare_products.py, /compare-products 端点和 compare_products MCP工具）

• 模块化结构: compare_products.py将业务逻辑与分离，以提高可重用性和可维护性
• 输入两个或多个产品名称，自动规范每个产品
• 收集每个产品的图像并以结构化形式返回
• 以差异为主的比较：比较分析LLM在产品设计、特点、价位等方面的差异
• 提供比较指南：提供比较点，包括设计、特点、价位、关键差异
• 某些产品处理失败时，其他产品处理仍在继续。
• 错误处理：在每个产品处理失败时提供详细的错误消息

设置环境变量

与Claude配合使用时，可以将图像处理选项调整为环境变量：

• LLM_IMAGE_MAX_COUNT：最大图像数（默认值：4）
• LLM_IMAGE_MAX_BYTES：最大图像大小（以字节为单位）
• LLM_IMAGE_MAX_DIMENSION：最大图像尺寸（以像素为单位）

示例：

# Windows PowerShell
$env:LLM_IMAGE_MAX_COUNT=6
$env:LLM_IMAGE_MAX_BYTES=1048576

# Linux/Mac
export LLM_IMAGE_MAX_COUNT=6
export LLM_IMAGE_MAX_BYTES=1048576

注意事项

一般注意事项

• Windows环境：Playwright运行时可能会出现事件循环问题，因此已实施为在单独的线程中运行。
• 保存图像：抓取的图像在内存中编码为Base64并返回，但不会保存为文件。
• API使用顺序：产品名称首先 /normalize-product-name 注册为端点后 /crawl 必须使用端点。

使用MCP服务器时的注意事项

• 布线: mcp_config.json 或Claude Desktop设置文件中的 cwd 必须将路径正确设置为实际项目路径。
• Python路径: command如果是“python”，请设置虚拟环境在活动状态下运行或使用绝对路径。
• 依赖性：MCP服务器运行前的所有依赖性（特别是 mcp, anyio，Playwright）已安装。

故障排除

如果找不到产品

1. 请确认产品名称的准确性（空格、数字等）
2. 请检查是否包括制造商名称（例如“三星电子蓝天5500”）
3. 请直接在田纳瓦搜索，确认正确的产品名称。

如果MCP服务器不工作

1. 重新启动Claude Desktop/Cursor
2. 请检查配置文件的路径是否正确
3. 检查是否启用了Python虚拟环境
4. 请确保安装了所有依赖项（pip list确认）

滚动失败时

1. 请检查您的互联网连接
2. 请确保已安装Playwright浏览器（playwright install chromium)
3. 请确认是否可以访问Dana和网站

提交规则

• feat: ... 添加新功能
• fix: ... 错误修复
• docs: ... 更新文档或注释
• refactor: ... 在功能不变的情况下改进代码结构
• test: ... 添加和修改测试代码
• chore: ... 构建、设置、依赖性等其他任务

共同原则

• 一次提交只包含一个目的。
• 提交消息以韩语或英语保持一致。
• 如果有问题编号 feat: #12 사용자 인증 추가如所示包含在消息中。
• PR之前 git status, git diff请务必查看更改历史记录。