Algolia MCP

🚀 ポケモンバトルAI戦略支援ツール

このアプリケーションは、Algolia検索と自然言語処理を活用した、インテリジェントなポケモンバトル戦略支援ツールです。会話型AIを通じて、戦略的な推奨事項、属性相性分析、競技向けの洞察を提供します。

🚀 クイックスタート

このアプリケーションを始める前に、いくつかの前提条件を満たす必要があります。

前提条件

• Node.js 18+
• npmパッケージマネージャー

インストール

# リポジトリをクローンする
git clone [repository-url]
cd pokemon_algolia_mcp

# すべての依存関係をインストールする（フロントエンド、バックエンド、mcp-node）
npm run install:all

# または手動でインストールする
npm install
cd frontend && npm install
cd ../backend && npm install
cd ../mcp-node && npm install

環境設定

1. 環境例ファイルをコピーする：

cp .env.example .env

2. .env ファイルで環境変数を設定する：

# Algolia設定（Algoliaダッシュボードから取得）
ALGOLIA_APP_ID=your_algolia_app_id
ALGOLIA_API_KEY=your_algolia_search_key

# Anthropic APIキー（AI機能に必要）
ANTHROPIC_API_KEY=your_anthropic_api_key_here
# または
CLAUDE_API_KEY=your_claude_api_key_here

# サーバー設定
PORT=3000

アプリケーションの実行

# フロントエンドとバックエンドを同時に起動する
npm run dev

# または個別に起動する
npm run dev:frontend  # フロントエンドのみ（http://localhost:5173）
npm run dev:backend   # バックエンドのみ（http://localhost:3000）

開発コマンド

npm run dev              # フロントエンドとバックエンドを起動する
npm run dev:frontend     # フロントエンドのみを起動する（Vite開発サーバー）
npm run dev:backend      # バックエンドのみを起動する（Expressサーバー）
npm run build            # フロントエンドとバックエンドをビルドする
npm run build:frontend   # フロントエンドのみをビルドする
npm run build:backend    # バックエンドのみをビルドする
npm run test             # リントと型チェックを実行する
npm run clean            # すべてのnode_modulesをクリーンする

プロジェクト構造

このプロジェクトは、3つの主要なパッケージを持つモノレポです：

• frontend/: React + TypeScript + Viteアプリケーション
• backend/: MCP統合のあるExpress.jsサーバー
• mcp-node/: Algolia MCPサーバーの実装

環境構成

このアプリケーションは、Algolia検索構成が必要です。

Algoliaのセットアップ：

1. algolia.com で無料アカウントを作成する
2. 新しいアプリケーションを作成する
3. ダッシュボードからApp IDを取得する
4. 検索専用のAPIキーを生成する（API Keysセクション）
5. ポケモンデータで pokemon インデックスを設定する

必要な環境変数：

• App ID: Algoliaダッシュボードから取得
• 検索専用APIキー: Algoliaダッシュボードで検索専用のキーを生成
• Anthropic APIキー: AI機能に必要（.envで設定）

✨ 主な機能

自然言語によるバトル計画

• 会話型クエリ: 「ギャラドスに対する最適な相手ポケモンは何か？」や「ドラゴンタイプに対応できるチームを組んで」などの複雑な質問をすることができます。
• AIによる推奨事項: チーム構築やバトルシナリオに関する詳細な理由付きの戦略的なアドバイスを得ることができます。
• コンテキスト認識分析: 競技フォーマット、階層、バトルコンテキストを理解します。

高度な検索機能

• マルチインデックス検索: ポケモン、技、特性、競技データを同時に検索します。
• タイプ相性エンジン: 耐性と免疫分析を含む完全なタイプマッチアップ計算を行います。
• 競技情報: 使用統計、階層分析、メタトレンドの洞察を提供します。
• 多面的なフィルタリング: ステータス、タイプ、世代、階層、バトルロールでフィルタリングできます。

インタラクティブなバトル分析

• リアルタイム戦略: 最適な技の提案と交代の推奨事項を取得します。
• マッチアップスコアリング: AIが数値評価でマッチアップの優位性を計算し、説明します。
• チーム相性分析: タイプカバレッジのギャップと戦略的な相性を特定します。
• 相手ポケモン発見: 特定の脅威に対する最適なポケモンを見つけます。

システム機能

• 接続ステータス: 利用可能なインデックスを表示しながら、Algolia接続をリアルタイムで監視します。
• ハイブリッド検索: インスタント検索とAIによる分析をシームレスに切り替えます。
• レスポンシブデザイン: すべての画面サイズに最適化されたグリッドベースの結果レイアウト。
• エラーハンドリング: 包括的なエラー境界とフォールバック状態。
• アニメーションエフェクト: GSAPによるスムーズなトランジションとホバーエフェクト。

🔧 技術詳細

技術スタック

• フロントエンド: React 19 + TypeScript + Vite
• スタイリング: グラスモーフィズムエフェクトのあるTailwind CSS v3
• 検索エンジン: カスタム検索統合のあるAlgolia v5
• 状態管理: 集中型バトルロジックのあるカスタムReactフック
• AI統合: クエリ解釈のための自然言語処理
• アニメーション: スムーズなトランジションとエフェクトのためのGSAP
• アイコン: 一貫したアイコンを提供するLucide React

プロジェクトアーキテクチャ

pokemon_algolia_mcp/
├── frontend/            # React TypeScriptアプリケーション
│   ├── src/
│   │   ├── components/  # UIコンポーネント
│   │   │   ├── HybridSearch.tsx        # メイン検索インターフェース
│   │   │   ├── AlgoliaStatus.tsx       # 接続ステータス表示
│   │   │   ├── SearchResults.tsx       # ポケモングリッド結果
│   │   │   ├── PokemonAnalysis.tsx     # バトル分析
│   │   │   ├── CustomInstantSearchResults.tsx  # カスタム検索結果
│   │   │   ├── SearchResultItem.tsx    # 個々の結果カード
│   │   │   ├── Header.tsx              # アプリヘッダー
│   │   │   └── ErrorBoundary.tsx       # エラーハンドリング
│   │   ├── services/    # ビジネスロジック
│   │   │   ├── algolia-enhanced.ts     # 高度なAlgolia統合
│   │   │   └── naturalLanguageSearchEnhanced.ts  # 強化された自然言語検索
│   │   ├── hooks/       # カスタムReactフック
│   │   │   ├── useAlgoliaSearch.ts     # 検索統合
│   │   │   └── useGSAPAnimations.ts    # アニメーションエフェクト
│   │   ├── types/       # TypeScriptインターフェース
│   │   │   └── pokemon.ts              # データモデル
│   │   ├── utils/       # ユーティリティ関数
│   │   │   └── pokemon.ts              # ポケモンヘルパー関数
│   │   └── data/        # 静的データ
│   │       └── mockPokemon.ts          # デモデータ
│   └── package.json
├── backend/             # Express.jsサーバー
│   ├── src/
│   │   ├── server.ts    # メインサーバーファイル
│   │   ├── mcpClient.ts # MCP統合
│   │   ├── routes/      # APIルート
│   │   └── utils/       # サーバーユーティリティ
│   └── package.json
├── mcp-node/            # Algolia MCPサーバー
│   ├── src/
│   │   ├── app.ts       # MCPサーバーの実装
│   │   ├── tools/       # MCPツール
│   │   └── data/        # Algolia API定義
│   └── package.json
└── package.json         # ルートワークスペース構成

データモデル

このアプリケーションは、包括的なTypeScriptインターフェースを使用しています：

• PokemonData: 完全なステータス、特性、技セット、タイプ相性
• MoveData: 威力、命中率、説明、競技的な有効性
• AbilityData: 効果、競技的な評価、ポケモンとの関連付け
• CompetitiveStatsData: 使用割合、階層分布、チーム相性
• RecommendationData: AIによって生成された理由付きのバトル提案

💻 使用例

自然言語クエリ

"ギャラドスに対する相手ポケモンは何か？"
→ タイプ優位のポケモンを理由付きで返す

"競技に最適な水タイプポケモン"
→ タイプと競技的な有効性でフィルタリングする

"氷光線を覚えることができ、素早さが高いポケモン"
→ 技セットとステータスを照合する

"OU階層の雨チームを組んで"
→ 相性分析を伴うチーム構成を提案する

検索機能

• 相手ポケモン分析: タイプ優位、素早さ階層、防御的なマッチアップを特定します。
• チーム構築: タイプカバレッジ、役割分布、戦略的な相性を分析します。
• 技検索: 特定の技を覚えるポケモンを競技的なコンテキストで見つけます。
• タイプフィルタリング: 単一/デュアルタイプでの高度なフィルタリングとステータス要件。

🏆 競技機能

階層統合

• OU (OverUsed): 標準的な競技階層分析
• UU/RU/NU: 低階層の有効性評価
• Ubers: 伝説/制限フォーマットのサポート
• LC (Little Cup): 進化前の競技分析

バトル情報

• マッチアップスコアリング: バトルの優位性に対する数値評価（0-100）
• 素早さ階層分析: 重要な素早さのベンチマーク比較
• タイプカバレッジ: 完全な攻撃的および防御的なタイプ分析
• メタ認識: 現在の使用トレンドとチームアーキタイプの認識

設定

TypeScriptセットアップ

このプロジェクトは、verbatimModuleSyntax を使用した厳格なTypeScriptを使用しています：

• 型のみのインポート: import type { Pokemon } from '../types/pokemon'
• 値のインポート: import { charizardData } from '../data/pokemon'

Algolia設定

このアプリケーションは、ポケモンデータを持つ事前構成されたAlgoliaインデックスに接続します：

• インデックス名: pokemon
• 検索機能: インスタント検索、ファセット、ハイライト
• データ構造: ポケモンのステータス、タイプ、技、競技情報

トラブルシューティング

一般的な問題

1. 依存関係のインストール

# npm installが失敗した場合、キャッシュをクリアしてみてください
npm cache clean --force
npm run clean
npm run install:all

2. ポートの競合

• フロントエンドはポート5173で実行されます（Viteのデフォルト）
• バックエンドはポート3000で実行されます（またはPORT環境変数）
• ポートが使用可能かどうかを確認するか、package.jsonで変更してください

3. 環境変数

# ルートディレクトリに.envファイルが存在することを確認する
cp .env.example .env
# AI機能のためにAnthropic APIキーを追加する

4. TypeScriptエラー

# 型チェックを実行する
npm run test
# 個々のパッケージを確認する
cd frontend && npm run lint
cd backend && npm run type-check

5. 検索が機能しない

• .envでAlgoliaの資格情報を確認する
• ブラウザコンソールでAPIエラーを確認する
• インスタント検索が失敗した場合はデモモードを試す

開発のヒント

• ブラウザの開発ツールを使用してAlgolia API呼び出しをデバッグする
• ネットワークタブでMCPサーバーの通信を確認する
• 開発モードで詳細なログを有効にする

デザインシステム

ビジュアルテーマ

• ダークグラデーション背景: 青 → 紫 → インディゴの進行
• グラスモーフィズムエフェクト: 透明度のある backdrop-blur-lg
• タイポグラフィ: グラデーションアクセントカラーを持つクリーンな階層
• インタラクティブ要素: ホバー状態でのスムーズなトランジション

レスポンシブデザイン

• モバイルファースト: すべての画面サイズに最適化
• グリッドレイアウト: 適応的な列数（1/2/3/4/5列）
• タッチフレンドリー: 大きなタップターゲットとジェスチャーサポート

開発

コードベースのクリーンアップ（最新）

このプロジェクトは最近、技術的負債を減らすために大規模なクリーンアップを行いました：

削除されたファイル（合計26個）:

• 廃止されたサービス（algolia.ts、naturalLanguageSearch.ts、instantSearchClient.ts）
• 未使用のコンポーネント（SearchInterface、FeatureShowcaseなど13個のファイル）
• 未使用のフック（useBattleStrategy.ts、useNaturalLanguageBattle.ts）
• テスト/ユーティリティファイルとバックアップディレクトリ
• 未使用の依存関係（react-instantsearchパッケージ）

現在のアーキテクチャの利点:

• アクティブな機能のみを持つクリーンで焦点の絞られたコードベース
• バンドルサイズの削減とパフォーマンスの向上
• より良い保守性と開発者体験
• 簡素化されたコンポーネント階層

新機能の追加

1. 新しい検索タイプ: naturalLanguageSearchEnhanced.ts のインターフェースを拡張する
2. 追加データ: types/pokemon.ts のTypeScriptインターフェースを更新する
3. UIコンポーネント: Tailwindスタイリングを使用した既存のパターンに従う
4. 検索ロジック: 適切なエラーハンドリングを伴う algolia-enhanced.ts で実装する

コード品質

• ESLint: ReactとTypeScriptのルールで構成されています。
• 型安全性: 包括的なインターフェースを持つ厳格なTypeScript。
• コンポーネント設計: 明確なプロップインターフェースを持つアトミックコンポーネント。
• 状態管理: ビジネスロジックを分離するためのカスタムフック。

パフォーマンス

最適化機能

• Viteビルドシステム: 高速な開発と最適化された本番ビルド。
• コード分割: 最適なロードのための自動チャンク化。
• 検索最適化: Algoliaの50ms未満の検索パフォーマンス。
• キャッシュ: 繰り返しのクエリに対するインテリジェントな結果キャッシュ。

将来のロードマップ

計画されている機能

• MCPサーバー統合: Claude Desktopのワークフロー自動化
• チームエクスポート: ポケモンショーダウンフォーマットとの互換性
• バトルシミュレーター: リアルタイムのバトルシナリオテスト
• コミュニティ機能: チーム共有と評価システム
• 高度な分析: 勝率予測とメタトラッキング

技術的な強化

• リアルタイムデータ: ライブの競技使用状況の更新
• 機械学習: 強化された推奨アルゴリズム
• パフォーマンス: 高度なキャッシュとCDN統合
• モバイルアプリ: React Nativeのコンパニオンアプリケーション

📄 ライセンス

このプロジェクトはオープンソースで、MITライセンスの下で利用可能です。

貢献

貢献は大歓迎です！詳細については、貢献ガイドラインを参照してください。

ポケモン競技コミュニティのために構築されました