FindMine Shopping Stylist

FindMine 购物造型师

一个模型上下文协议（MCP）服务，可将 FindMine 强大的产品造型和搭配推荐功能集成到 Claude 及其他兼容 MCP 的应用程序中。

概述

此 MCP 服务连接 FindMine 的造型 API，并通过模型上下文协议向大语言模型提供其功能。用户可以：

• 浏览产品和穿搭信息
• 获取针对特定产品的穿搭推荐
• 查找外观相似的产品
• 获取造型指导和时尚建议

功能

资源

• 产品：详细的产品信息，使用 product:/// URI 方案
• 造型：完整的穿搭推荐，使用 look:/// URI 方案

工具

• get_style_guide：获取详细的时尚建议和造型指南
• get_complete_the_look：获取针对某件产品的穿搭推荐
• get_visually_similar：查找外观相似的产品
• track_interaction：记录购物者的互动（仅当 FINDMINE_ENABLE_TRACKING=true 时）
• update_item_details：更新商品库存和促销状态（仅当 FINDMINE_ENABLE_ITEM_UPDATES=true 时）

每个工具都声明了标题、行为注释和输出架构，并返回结构化结果。

提示词

• outfit_completion：获取完整穿搭的造型建议
• styling_guide：获取全面的时尚造型指南
• findmine_help：了解如何使用 FindMine 的工具和资源

安装

选项 1：从 npm 安装

# Install and run directly (recommended)
npx findmine-mcp

# Or install globally
npm install -g findmine-mcp
findmine-mcp

选项 2：使用 Docker 运行

docker run -e FINDMINE_APP_ID=your_app_id findmine/mcp-server:latest

选项 3：克隆并从源代码构建

# Clone the repository
git clone https://github.com/findmine/findmine-mcp.git
cd findmine-mcp

# Install dependencies
npm install

# Build the server
npm run build

# For development with auto-rebuild
npm run watch

配置

环境变量

变量	说明	默认值
FINDMINE_API_URL	FindMine API 基础 URL	https://api.findmine.com
FINDMINE_APP_ID	你的 FindMine 应用程序 ID	DEMO_APP_ID
FINDMINE_API_VERSION	要使用的 API 版本	v3
FINDMINE_DEFAULT_REGION	默认地区代码	us
FINDMINE_DEFAULT_LANGUAGE	默认语言代码	en
FINDMINE_CACHE_ENABLED	启用响应缓存	true
FINDMINE_CACHE_TTL_MS	缓存生存时间（毫秒）	3600000 (1 小时)
FINDMINE_ENABLE_TRACKING	注册 track_interaction 工具	false
FINDMINE_ENABLE_ITEM_UPDATES	注册 update_item_details 工具	false
FINDMINE_DEBUG	将调试输出记录到 stderr	false

在 Claude Desktop 中使用

安装不会更改任何 Claude Desktop 设置。请自行将服务添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\），并指向你的构建版本：

{
  "mcpServers": {
    "findmine": {
      "command": "node",
      "args": ["/absolute/path/to/findmine-mcp/build/index.js"],
      "env": { "FINDMINE_APP_ID": "your_app_id" }
    }
  }
}

开发

可用脚本

# Build and watch
npm run build              # Build the project
npm run watch             # Watch for changes and rebuild
npm run typecheck         # Run TypeScript type checking

# Testing
npm test                  # Run tests in watch mode
npm run test:run          # Run tests once
npm run test:coverage     # Run tests with coverage report

# Code quality
npm run lint              # Run ESLint
npm run lint:fix          # Run ESLint with auto-fix
npm run format            # Format code with Prettier
npm run format:check      # Check code formatting

# Development tools
npm run inspector         # Run MCP inspector (http://localhost:5173)

测试

此项目使用 Vitest 进行测试。测试位于 tests/unit/ 和 tests/integration/；集成测试套件会使用 MCP SDK v2 客户端在进程内运行服务，并覆盖两种受支持的协议修订版本。

# Run tests in watch mode
npm test

# Run tests once (useful for CI)
npm run test:run

# Generate coverage report
npm run test:coverage

代码质量

提交代码前：

# Run all checks
npm run typecheck && npm run lint && npm run format:check && npm run test:run

项目使用：

• ESLint 进行代码检查，并支持 TypeScript
• Prettier 进行代码格式化
• Vitest 进行测试
• GitHub Actions 用于 CI/CD

自定义造型指南

你可以自定义造型指南，以符合品牌特有的造型理念和时尚指导。自定义造型指南的方法：

1. 在 src/content/style-guides.ts 中找到造型指南
2. 修改各个类别（general、color_theory、body_types 等）的内容
3. 在 STYLE_GUIDE_CATEGORIES 中添加类别名称，并在 styleGuides 对象中添加相应内容，以新增类别（工具和提示词架构会自动获取新类别）
4. 自定义特定场合和季节的建议

添加自定义造型指南类别的示例：

// In src/content/style-guides.ts (after adding 'your_brand_style' to STYLE_GUIDE_CATEGORIES)
export const styleGuides: Record<StyleGuideCategory, string> = {
  // Existing categories...

  // Add your custom category
  your_brand_style: `# Your Brand Style Guide

## Brand Aesthetic
- Key elements of your brand's visual identity
- Core style principles
- Signature looks and combinations

## Your Brand's Styling Do's
- Brand-specific styling recommendations
- Preferred color combinations
- Signature styling techniques

## Your Brand's Styling Don'ts
- Combinations to avoid
- Styling approaches that don't align with brand identity
- Common styling mistakes to avoid
`
};

如需全面自定义，你可以修改 src/tools/get-style-guide.ts 中的 get_style_guide 工具。

项目结构

src/
├── index.ts              # stdio bin (serveStdio)
├── server.ts             # createFindMineDeps() + createFindMineServer(deps, { extend })
├── config.ts             # Environment configuration
├── api/                  # FindMine API client
├── tools/                # Tool registrations, Zod input/output schemas (schemas.ts)
├── resources/            # product:/// and look:/// resource templates and URI helpers
├── prompts/              # Prompts with Zod argument schemas
├── content/              # Style guide content
├── services/             # Business logic layer (caching, resource store)
├── types/                # TypeScript type definitions
└── utils/                # Cache, formatters, logger, resource mapping
tests/
├── unit/
├── integration/
└── fakes/

技术详情

此服务基于以下技术构建：

• MCP TypeScript SDK v2（@modelcontextprotocol/server），通过 stdio 提供协议修订版本 2025-11-25 和 2026-07-28
• 工具标题、注释（只读、破坏性、幂等、开放世界提示）以及包含结构化结果的输出架构
• 所有工具输入和输出均采用 Zod 4 架构
• 模块化架构，职责分离
• Vitest 单元测试和进程内集成测试

API 示例

获取风格指南

{
  "name": "get_style_guide",
  "arguments": {
    "category": "color_theory",
    "occasion": "wedding"
  }
}

获取完整搭配

{
  "name": "get_complete_the_look",
  "arguments": {
    "product_id": "P12345",
    "product_color_id": "C789"
  }
}

获取视觉相似产品

{
  "name": "get_visually_similar",
  "arguments": {
    "product_id": "P12345",
    "product_color_id": "C789",
    "limit": 5
  }
}

发布

发布到 npm

# Login to npm
npm login

# Publish the package
npm publish

# Update the version for future releases
npm version patch

发布到 Docker Hub

# Build the Docker image
docker build -t findmine/mcp-server:latest .

# Login to Docker Hub
docker login

# Push the image
docker push findmine/mcp-server:latest

许可证

此项目采用 MIT 许可证。