Stylist MCP Server

造型师MCP服务器

一个由人工智能驱动的时尚推荐MCP（模型上下文协议）服务器，使用ChromaDB进行语义搜索，使用Claude/GPT进行自然语言理解，提供智能服装建议。

特性

• 🎨 智能服装推荐：单件或整套服装组合
• 🌐 多种运输方式:

- stdio 用于本地Claude桌面/光标集成 - Streamable HTTP 用于远程访问（简单配置，如Tavily）

• 🔍 混合搜索：将元数据过滤与语义向量搜索相结合
• 🌍 多语言：支持中英文查询
• 🧥 全套装备协调：带有风格推理的上衣+下装组合或连衣裙
• 🔐 API密钥验证：使用可配置的API密钥进行安全的远程访问
• 🖼️ 图像URL：直接HTTPS链接到服装图像

快速开始

1.设置

# Clone and setup
git clone https://github.com/Polly2014/Stylist-MCP-Server.git
cd Stylist-MCP-Server
chmod +x setup.sh
./setup.sh

# Edit configuration
cp .env.example .env
nano .env  # Configure DRESSCODE_ROOT, CHROMADB_PATH, etc.

2.构建索引

source venv/bin/activate
python scripts/build_chromadb.py

3.运行服务器

# stdio mode (for Claude Desktop local)
python src/mcp_server.py

# HTTP mode (for remote access)
python src/mcp_server.py --http --port 8888

# Or with uvicorn directly
uvicorn src.mcp_server:starlette_app --host 0.0.0.0 --port 8888

配置

环境变量（设置于 .env):

数据和服务器

LLM提供者

Anthropic（代理大师） -开发模式：

Azure OpenAI -生产方式：

可用工具

stylist_recommend

智能解释用户查询的时尚推荐工具。

输入：

{
  "query": "recommend 3 casual outfits for a date",
  "include_reasoning": true,
  "include_image_urls": true
}

输出模式：

• single_item：返回单个服装的列表（例如，“T恤“，”给我看看衣服“）
• full_outfit：返回协调的服装组合（例如，“推荐3套”、“约会服装”）

示例响应（single_item模式）：

{
  "query": "recommend 5 casual T-shirts for summer",
  "mode": "single_item",
  "parsed_intent": {
    "language": "en",
    "recommendation_mode": "single_item",
    "count": 5,
    "garment_type": "t-shirt",
    "category": "upper_body",
    "style": "casual",
    "season": "summer"
  },
  "num_results": 5,
  "recommendations": [
    {
      "garment_id": "003841",
      "description": "White cotton t-shirt with round neck, short sleeves, relaxed fit",
      "similarity_score": 0.87,
      "category": "upper_body",
      "garment_type": "t-shirt",
      "colors": ["white"],
      "styles": ["casual", "minimalist"],
      "occasions": ["everyday", "casual"],
      "image_url": ""
    },
    {
      "garment_id": "003925",
      "description": "Light blue linen t-shirt, breathable fabric, classic cut",
      "similarity_score": 0.82,
      "category": "upper_body",
      "garment_type": "t-shirt",
      "colors": ["blue"],
      "styles": ["casual"],
      "occasions": ["everyday", "vacation"],
      "image_url": ""
    }
    // ... more items
  ],
  "stylist_advice": "These lightweight cotton and linen t-shirts are perfect for summer..."
}

示例响应（full_outfit模式）：

{
  "query": "推荐3套约会穿搭",
  "mode": "full_outfit",
  "parsed_intent": {
    "language": "zh",
    "recommendation_mode": "full_outfit",
    "count": 3,
    "occasion": "date",
    "style": "elegant"
  },
  "num_outfits": 3,
  "outfits": [
    {
      "type": "two_piece",
      "top": {
        "garment_id": "005123",
        "description": "Soft pink silk blouse with subtle ruffle details",
        "similarity_score": 0.85,
        "category": "upper_body",
        "garment_type": "blouse",
        "colors": ["pink"],
        "styles": ["romantic", "elegant"],
        "occasions": ["date", "party"],
        "image_url": ""
      },
      "bottom": {
        "garment_id": "012456",
        "description": "High-waisted black pencil skirt, knee length",
        "similarity_score": 0.83,
        "category": "lower_body",
        "garment_type": "skirt",
        "colors": ["black"],
        "styles": ["classic", "elegant"],
        "occasions": ["work", "date"],
        "image_url": ""
      },
      "score": 0.90,
      "reason": "The soft pink blouse pairs beautifully with the classic black skirt, creating a romantic yet sophisticated look perfect for a date."
    },
    {
      "type": "dress",
      "dress": {
        "garment_id": "020714",
        "description": "Elegant navy blue A-line dress with V-neck, midi length",
        "similarity_score": 0.88,
        "category": "dresses",
        "garment_type": "dress",
        "colors": ["navy", "blue"],
        "styles": ["elegant", "classic"],
        "occasions": ["date", "party", "formal"],
        "image_url": ""
      },
      "score": 0.88,
      "reason": "This navy A-line dress is timeless and flattering, ideal for a romantic dinner date."
    }
    // ... more outfits
  ],
  "stylist_advice": "这些穿搭都非常适合约会场合。粉色丝质上衣搭配黑色铅笔裙展现优雅气质，而海军蓝连衣裙则是经典之选，适合各种约会场景。"
}

客户端集成

克劳德桌面（本地stdio）

添加到 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "stylist-recommender": {
      "command": "python",
      "args": ["/path/to/Stylist-MCP-Server/src/mcp_server.py"],
      "env": {
        "DRESSCODE_ROOT": "/path/to/DressCode",
        "CHROMADB_PATH": "/path/to/chroma_db",
        "LLM_API_ENDPOINT": "http://localhost:23333/api/anthropic/v1/messages"
      }
    }
  }
}

远程访问（流式HTTP-推荐）⭐

最简单的远程连接方式，如Tavily：

{
  "mcpServers": {
    "stylist-recommender": {
      "url": "https://stylist.polly.wang/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

光标

添加到 .cursor/mcp.json:

{
  "mcpServers": {
    "stylist-recommender": {
      "url": "https://stylist.polly.wang/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Python客户端

import httpx

# Streamable HTTP client
async def call_stylist():
    async with httpx.AsyncClient() as client:
        # Initialize
        response = await client.post(
            "https://stylist.polly.wang/mcp",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json",
                "Accept": "application/json"
            },
            json={
                "jsonrpc": "2.0",
                "method": "initialize",
                "params": {
                    "protocolVersion": "2024-11-05",
                    "capabilities": {},
                    "clientInfo": {"name": "python-client", "version": "1.0"}
                },
                "id": 1
            }
        )
        session_id = response.headers.get("mcp-session-id")
        
        # Call tool
        response = await client.post(
            "https://stylist.polly.wang/mcp",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json",
                "Accept": "application/json",
                "mcp-session-id": session_id
            },
            json={
                "jsonrpc": "2.0",
                "method": "tools/call",
                "params": {
                    "name": "stylist_recommend",
                    "arguments": {"query": "推荐3套约会穿搭"}
                },
                "id": 2
            }
        )
        print(response.json())

HTTP模式端点

身份验证方法：

• 标题（推荐）： X-API-Key: YOUR_KEY
• 查询参数： ?apiKey=YOUR_KEY
• 持有者代币： Authorization: Bearer YOUR_KEY

项目结构

Stylist-MCP-Server/
├── src/
│   ├── config.py          # Configuration (env vars)
│   ├── garment_db.py      # ChromaDB wrapper
│   ├── stylist_tool.py    # Recommendation logic (single_item + full_outfit)
│   └── mcp_server.py      # MCP server (stdio + Streamable HTTP)
├── scripts/
│   ├── build_chromadb.py  # Index builder
│   ├── build_from_jsonl.py # Build from attributes JSONL
│   └── test_mcp.py        # Comprehensive test suite
├── config/
│   ├── claude_desktop.json           # Local stdio config
│   ├── claude_desktop_remote.example.json  # Remote HTTP config
│   ├── cursor_mcp.example.json       # Cursor config
│   └── python_client_example.py      # Python client example
├── data/
│   ├── garment_attributes.jsonl      # Garment metadata
│   └── chroma_db/                    # Vector database
├── requirements.txt
├── setup.sh
├── .env.example
└── README.md

测试

# Quick test (skip LLM reasoning)
python scripts/test_mcp.py --quick

# Full test with LLM reasoning
python scripts/test_mcp.py

# Verbose output
python scripts/test_mcp.py --verbose

# Local only (no remote server tests)
python scripts/test_mcp.py --local-only

# Custom LLM endpoint
LLM_API_ENDPOINT=http://localhost:23335/api/anthropic/v1/messages python scripts/test_mcp.py

测试覆盖范围：

• 📦 数据库：基本搜索、过滤器、多类别
• 👕 单品：T恤、连衣裙、中文查询
• 👔 全套服装：基本、正式、中式、男士（无连衣裙）
• 🧠 LLM推理：评分、理由、造型师建议
• 🌐 远程：运行状况、工具、MCP端点、图像

部署

使用Nginx（推荐）

1. 在内部端口上运行MCP服务器：

   python src/mcp_server.py --http --port 8888

1. 使用SSL配置Nginx反向代理：

   server {
       listen 443 ssl;
       server_name stylist.polly.wang;
       
       ssl_certificate /etc/letsencrypt/live/stylist.polly.wang/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/stylist.polly.wang/privkey.pem;
       
       location / {
           proxy_pass http://127.0.0.1:8888;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_buffering off;
           proxy_read_timeout 86400;
       }
   }

1. 设置环境变量：

   MCP_EXTERNAL_HOST=stylist.polly.wang
   MCP_USE_SSL=true
   MCP_API_KEY=your-secure-api-key

演出

• Haiku模型：每次整套服装查询约19秒（建议速度）
• Sonnet模型：每套服装查询约48秒（更高质量）
• 快速模式 （无推理）：每个查询约2秒

许可证

麻省理工学院