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:

Locate the style guides in src/index.ts (search for styleGuides)
Modify the content for each category (general, color_theory, body_types, etc.)
Add new categories by extending the styleGuides object
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.