READMEmain
We couldn't render this README. Read it on GitHub
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
- 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:
- Locate the style guides in
src/content/style-guides.ts - Modify the content for each category (
general,color_theory,body_types, etc.) - Add new categories by adding the name to
STYLE_GUIDE_CATEGORIESand its content to thestyleGuidesobject (the tool and prompt schemas pick up the new category automatically) - 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.
