FindMine Shopping Stylist

A Model Context Protocol (MCP) server that integrates FindMine's powerful product styling and outfitting recommendations with Claude and other MCP-compatible applications.

Overview

This MCP server connects to FindMine's styling API and exposes its functionality to Large Language Models through the Model Context Protocol. It allows users to:

• Browse product and outfit information
• Get outfit recommendations for specific products
• Find visually similar products
• Access style guidance and fashion advice

Features

Resources

• Products: Detailed product information with product:/// URI scheme
• Looks: Complete outfit recommendations with look:/// URI scheme

Tools

• get_style_guide: Access detailed fashion advice and styling guidelines
• get_complete_the_look: Get outfit recommendations for a product
• get_visually_similar: Find visually similar products

Prompts

• outfit_completion: Get styling advice for complete outfits
• styling_guide: Access comprehensive fashion styling guidelines
• findmine_help: Learn how to use FindMine's tools and resources

Installation

Option 1: Install from npm

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

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

Option 2: Run with Docker

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

Option 3: Clone and build from source

# 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

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | FINDMINE_API_URL | FindMine API base URL | https://api.findmine.com | | FINDMINE_APP_ID | Your FindMine application ID | DEMO_APP_ID | | FINDMINE_API_VERSION | API version to use | v3 | | FINDMINE_DEFAULT_REGION | Default region code | us | | FINDMINE_DEFAULT_LANGUAGE | Default language code | en | | FINDMINE_CACHE_ENABLED | Enable response caching | true | | FINDMINE_CACHE_TTL_MS | Cache time-to-live in ms | 3600000 (1 hour) | | NODE_ENV | Set to "development" for sample data | - |

Usage with Claude Desktop

The server automatically configures Claude Desktop during installation. To verify:

macOS:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

type %APPDATA%\Claude\claude_desktop_config.json

Development

MCP Inspector

The MCP Inspector is a development tool for testing your server:

npm run inspector

This will open a web interface at http://localhost:5173 where you can interact with your server.

Development Mode

Run the server with sample data:

NODE_ENV=development npm run build && node build/index.js

Customizing the Style Guide

The style guide can be customized to match your brand's specific styling philosophies and fashion guidance. To customize the style guide:

1. Locate the style guides in src/index.ts (search for styleGuides)
2. Modify the content for each category (general, color_theory, body_types, etc.)
3. Add new categories by extending the styleGuides object
4. Customize occasion-specific and seasonal advice

Example of adding a custom style guide category:

// In src/index.ts
const styleGuides: Record<string, 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
`
};

For complete customization, you can modify the entire get_style_guide handler in src/index.ts.

Project Structure

• src/index.ts: Main MCP server implementation
• src/api/: FindMine API client
• src/services/: Business logic and service layer
• src/types/: TypeScript type definitions
• src/utils/: Utility functions and helpers

API Examples

Get Style Guide

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

Get Complete the Look

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

Get Visually Similar Products

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

Publishing

Publishing to npm

# Login to npm
npm login

# Publish the package
npm publish

# Update the version for future releases
npm version patch

Publishing to 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

License

This project is licensed under the MIT License.