FindMine Shopping Stylist

# 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 ```bash # Install and run directly (recommended) npx findmine-mcp # Or install globally npm install -g findmine-mcp findmine-mcp ``` ### Option 2: Run with Docker ```bash docker run -e FINDMINE_APP_ID=your_app_id findmine/mcp-server:latest ``` ### Option 3: Clone and build from source ```bash # 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:** ```bash cat ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` **Windows:** ``` type %APPDATA%\Claude\claude_desktop_config.json ``` ## Development ### Available Scripts ```bash # 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 are located in `__tests__/` directories alongside source files. ```bash # 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: ```bash # 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 ### Development Mode Run the server with sample data: ```bash 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/content/style-guides.ts` 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: ```typescript // In src/content/style-guides.ts export 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/handlers/tools.ts`. ### Project Structure ``` src/ ├── index.ts # MCP server bootstrap and initialization ├── config.ts # Environment configuration ├── api/ # FindMine API client │ └── findmine-client.ts ├── handlers/ # MCP protocol handlers │ ├── tools.ts # Tool execution handlers │ ├── resources.ts # Resource handlers │ └── prompts.ts # Prompt handlers ├── tools/ # Tool definitions with MCP annotations │ └── index.ts ├── schemas/ # Zod validation schemas │ ├── tool-inputs.ts # Input validation for all tools │ └── index.ts ├── content/ # Static content │ └── style-guides.ts # Style guide content ├── prompts/ # Prompt definitions │ ├── findmine-help.ts │ ├── outfit-completion.ts │ ├── styling-guide.ts │ └── index.ts ├── services/ # Business logic layer │ └── findmine-service.ts ├── types/ # TypeScript type definitions │ ├── findmine-api.ts │ └── mcp.ts └── utils/ # Utility functions and helpers ├── cache.ts ├── formatters.ts ├── logger.ts ├── mock-data.ts └── resource-mapper.ts ``` ### Technical Details This server is built with: - **MCP SDK 1.24.2** with full spec compliance (2025-11-25) - **Tool annotations** for read-only, destructive, and open-world hints - **Zod validation** for all tool inputs - **Modular architecture** with separated concerns - **100% test coverage** on utility functions ## API Examples ### Get Style Guide ```json { "name": "get_style_guide", "arguments": { "category": "color_theory", "occasion": "wedding" } } ``` ### Get Complete the Look ```json { "name": "get_complete_the_look", "arguments": { "product_id": "P12345", "product_color_id": "C789" } } ``` ### Get Visually Similar Products ```json { "name": "get_visually_similar", "arguments": { "product_id": "P12345", "product_color_id": "C789", "limit": 5 } } ``` ## Publishing ### Publishing to npm ```bash # Login to npm npm login # Publish the package npm publish # Update the version for future releases npm version patch ``` ### Publishing to Docker Hub ```bash # 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.