Skip to main content
Glama
FindMine Shopping Stylist

FindMine Shopping Stylist

Official
by findmine

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

Related MCP server: Kroger MCP Server

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

  • track_interaction: Record shopper interactions (only when FINDMINE_ENABLE_TRACKING=true)

  • update_item_details: Update item stock and sale status (only when FINDMINE_ENABLE_ITEM_UPDATES=true)

Every tool declares a title, behavior annotations, and an output schema, and returns structured results.

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)

FINDMINE_ENABLE_TRACKING

Register the track_interaction tool

false

FINDMINE_ENABLE_ITEM_UPDATES

Register the update_item_details tool

false

FINDMINE_DEBUG

Log debug output to stderr

false

Usage with Claude Desktop

Installation does not change any Claude Desktop settings. Add the server to claude_desktop_config.json yourself (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), pointing at your build:

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

Development

Available Scripts

# 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)

Testing

This project uses Vitest for testing. Tests live in tests/unit/ and tests/integration/; the integration suite drives the server in-process with the MCP SDK v2 client on both supported protocol revisions.

# Run tests in watch mode
npm test

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

# Generate coverage report
npm run test:coverage

Code Quality

Before committing code:

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

The project uses:

  • ESLint for linting with TypeScript support

  • Prettier for code formatting

  • Vitest for testing

  • GitHub Actions for CI/CD

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/content/style-guides.ts

  2. Modify the content for each category (general, color_theory, body_types, etc.)

  3. Add new categories by adding the name to STYLE_GUIDE_CATEGORIES and its content to the styleGuides object (the tool and prompt schemas pick up the new category automatically)

  4. Customize occasion-specific and seasonal advice

Example of adding a custom style guide category:

// 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
`
};

For complete customization, you can modify the get_style_guide tool in src/tools/get-style-guide.ts.

Project Structure

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/

Technical Details

This server is built with:

  • MCP TypeScript SDK v2 (@modelcontextprotocol/server), serving protocol revisions 2025-11-25 and 2026-07-28 over stdio

  • Tool titles, annotations (read-only, destructive, idempotent, open-world hints) and output schemas with structured results

  • Zod 4 schemas for all tool inputs and outputs

  • Modular architecture with separated concerns

  • Vitest unit tests and in-process integration tests

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.

Available Tools

3 tools
get_complete_the_lookC

Get outfit recommendations for a product

Inputs: product_id (required), api_version, customer_gender, customer_id, +5 more.

get_style_guideB

Get styling advice and tips for creating effective fashion recommendations

Inputs: category, fashion_season, occasion.

get_visually_similarC

Get visually similar products

Inputs: product_id (required), api_version, customer_gender, customer_id, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 3 tools

    Disambiguation4/5

    The three tools have distinct purposes: get_complete_the_look focuses on outfit recommendations, get_style_guide provides styling advice and tips, and get_visually_similar finds visually similar products. While get_complete_the_look and get_visually_similar both involve product recommendations, their descriptions clarify that one is for outfits and the other for visual similarity, minimizing overlap. However, the boundary between get_complete_the_look and get_style_guide could be slightly ambiguous as both relate to fashion recommendations, but the descriptions help differentiate them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with 'get_' as the prefix, followed by descriptive phrases (complete_the_look, style_guide, visually_similar). This uniformity makes the tools predictable and easy to understand, with no deviations in naming conventions or styles.

    Tool Count3/5

    With only 3 tools, the server feels thin for a shopping stylist domain, which might involve more operations like searching products, filtering by categories, or managing user preferences. While the tools cover key aspects (recommendations, advice, similarity), the limited count could restrict functionality and lead to gaps in handling complex styling tasks.

    Completeness2/5

    The tool surface is significantly incomplete for a shopping stylist. It lacks essential operations such as searching for products, retrieving product details, filtering by attributes (e.g., color, size), or handling user interactions (e.g., saving preferences, history). The existing tools focus only on recommendations and advice, leaving major gaps that could cause agent failures in real-world styling scenarios.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      A FastMCP server that provides AI assistants like Claude with seamless access to Kroger's grocery shopping functionality through the Model Context Protocol, enabling store finding, product searching, and cart management.
      31
      74 PyPI
      84
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      The Vistoya MCP server gives AI agents direct access to a curated, multi-brand fashion catalog. Agents can search by structured filters, discover products through natural language, find similar items, and retrieve full product details — all over a single Streamable HTTP connection.
      10 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the Universal Commerce Protocol (UCP) Discovery and Catalog capabilities, letting you search and compare products across UCP merchants directly from Claude.
      4
      MIT