Content
# 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.
