FindMine Shopping Stylist

FindMine ショッピングスタイリスト

FindMine の強力な商品スタイリングおよびコーディネートのおすすめ機能を、Claude やその他の MCP 対応アプリケーションと連携させる Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーは FindMine のスタイリング API に接続し、Model Context Protocol を通じてその機能を大規模言語モデルに公開します。これにより、ユーザーは次のことができます。

• 商品やコーディネートの情報を閲覧する
• 特定の商品に対するコーディネートをおすすめしてもらう
• 見た目が似ている商品を見つける
• スタイリングの指針やファッションのアドバイスを利用する

機能

リソース

• 商品：product:/// URI スキームを使った詳しい商品情報
• ルック：look:/// URI スキームを使ったコーディネート全体のおすすめ

ツール

• get_style_guide：詳しいファッションアドバイスやスタイリングガイドラインを利用する
• get_complete_the_look：商品に合わせたコーディネートをおすすめしてもらう
• get_visually_similar：見た目が似ている商品を見つける
• track_interaction：購入者のインタラクションを記録する（FINDMINE_ENABLE_TRACKING=true の場合のみ）
• update_item_details：商品の在庫状況やセール状況を更新する（FINDMINE_ENABLE_ITEM_UPDATES=true の場合のみ）

各ツールはタイトル、動作アノテーション、出力スキーマを宣言し、構造化された結果を返します。

プロンプト

• outfit_completion：コーディネート全体のスタイリングアドバイスを得る
• styling_guide：包括的なファッションスタイリングガイドラインを利用する
• findmine_help：FindMine のツールやリソースの使い方を確認する

インストール

オプション 1：npm からインストール

# Install and run directly (recommended)
npx findmine-mcp

# Or install globally
npm install -g findmine-mcp
findmine-mcp

オプション 2：Docker で実行

docker run -e FINDMINE_APP_ID=your_app_id findmine/mcp-server:latest

オプション 3：ソースからクローンしてビルド

# 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

設定

環境変数

変数	説明	デフォルト
FINDMINE_API_URL	FindMine API のベース URL	https://api.findmine.com
FINDMINE_APP_ID	FindMine アプリケーション ID	DEMO_APP_ID
FINDMINE_API_VERSION	使用する API バージョン	v3
FINDMINE_DEFAULT_REGION	デフォルトの地域コード	us
FINDMINE_DEFAULT_LANGUAGE	デフォルトの言語コード	en
FINDMINE_CACHE_ENABLED	レスポンスのキャッシュを有効にする	true
FINDMINE_CACHE_TTL_MS	キャッシュの有効期間（ミリ秒）	3600000 (1 hour)
FINDMINE_ENABLE_TRACKING	track_interaction ツールを登録する	false
FINDMINE_ENABLE_ITEM_UPDATES	update_item_details ツールを登録する	false
FINDMINE_DEBUG	デバッグ出力を stderr に記録する	false

Claude Desktop での使用

インストールによって Claude Desktop の設定が変更されることはありません。サーバーのビルド先を指定して、claude_desktop_config.json（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）にご自身でサーバーを追加してください。

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

開発

使用可能なスクリプト

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

テスト

このプロジェクトでは、テストに Vitest を使用しています。テストは tests/unit/ と tests/integration/ にあり、統合テストスイートでは、サポートされている両方のプロトコル改訂版を対象に、MCP SDK v2 クライアントを使ってサーバーをプロセス内で実行します。

# Run tests in watch mode
npm test

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

# Generate coverage report
npm run test:coverage

コード品質

コードをコミットする前に、次を実行してください。

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

このプロジェクトでは、次を使用しています。

• ESLint：TypeScript に対応したリンティング
• Prettier：コードのフォーマット
• Vitest：テスト
• GitHub Actions：CI/CD

スタイルガイドのカスタマイズ

スタイルガイドは、ブランド独自のスタイリング方針やファッションに関する指針に合わせてカスタマイズできます。カスタマイズするには、次の手順に従ってください。

1. src/content/style-guides.ts にあるスタイルガイドを確認します
2. 各カテゴリ（general、color_theory、body_types など）の内容を変更します
3. STYLE_GUIDE_CATEGORIES に名前を追加し、その内容を styleGuides オブジェクトに追加して、新しいカテゴリを作成します（ツールとプロンプトのスキーマには、新しいカテゴリが自動的に反映されます）
4. シーン別や季節別のアドバイスをカスタマイズします

カスタムのスタイルガイドカテゴリを追加する例：

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

完全にカスタマイズするには、src/tools/get-style-guide.ts の get_style_guide ツールを変更してください。

プロジェクト構成

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/

技術的な詳細

このサーバーは、以下の技術で構築されています。

• MCP TypeScript SDK v2（@modelcontextprotocol/server）を使用し、stdio 経由でプロトコルリビジョン 2025-11-25 および 2026-07-28 を提供します
• ツールのタイトルと注釈（読み取り専用、破壊的、べき等、オープンワールドのヒント）、および構造化された結果を含む出力スキーマ
• すべてのツールの入力と出力に Zod 4 スキーマ
• 関心事を分離したモジュラーアーキテクチャ
• Vitest による単体テストとプロセス内統合テスト

API の例

スタイルガイドを取得

{
  "name": "get_style_guide",
  "arguments": {
    "category": "color_theory",
    "occasion": "wedding"
  }
}

コーディネートを完成させる

{
  "name": "get_complete_the_look",
  "arguments": {
    "product_id": "P12345",
    "product_color_id": "C789"
  }
}

見た目が似ている商品を取得

{
  "name": "get_visually_similar",
  "arguments": {
    "product_id": "P12345",
    "product_color_id": "C789",
    "limit": 5
  }
}

公開

npm への公開

# Login to npm
npm login

# Publish the package
npm publish

# Update the version for future releases
npm version patch

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

ライセンス

このプロジェクトは MIT License の下でライセンスされています。