Algolia MCP

🚀 寶可夢對戰AI策略師

寶可夢對戰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

項目結構

這是一個包含三個主要包的單倉庫項目：

• frontend/：基於 React + TypeScript + Vite 的應用程序
• backend/：集成了 MCP 的 Express.js 服務器
• mcp-node/：Algolia MCP 服務器的實現

環境配置

該應用需要進行 Algolia 搜索配置：

設置 Algolia：

1. 在 algolia.com 創建一個免費賬戶
2. 創建一個新應用
3. 從控制檯獲取你的應用 ID
4. 生成一個僅用於搜索的 API 密鑰（在 API Keys 部分）
5. 使用你的寶可夢數據設置一個 pokemon 索引

所需環境變量：

• 應用 ID：從你的 Algolia 控制檯獲取
• 僅搜索 API 密鑰：在 Algolia 控制檯生成一個僅搜索密鑰
• Anthropic API 密鑰：AI 功能所需（在 .env 中設置）

✨ 主要特性

自然語言對戰規劃

• 對話式查詢：可以提出複雜問題，如“什麼寶可夢能最好地對抗會陽光烈焰的噴火龍？”或“幫我組建一支能應對龍屬性寶可夢的隊伍”
• AI 驅動的建議：獲得帶有詳細推理的戰略建議，用於隊伍組建和對戰場景
• 上下文感知分析：理解競技格式、分級和對戰上下文

高級搜索功能

• 多索引搜索：同時搜索寶可夢、技能、特性和競技數據
• 屬性相剋引擎：完成屬性匹配計算，包括抗性和免疫分析
• 競技情報：使用率統計、分級分析和環境趨勢洞察
• 分面過濾：按種族值、屬性、世代、分級和對戰角色進行過濾

交互式對戰分析

• 即時策略：獲得最佳技能建議和換寶可夢建議
• 對戰評分：AI 計算並解釋對戰優勢，給出數值評分
• 隊伍協同分析：識別屬性覆蓋缺口和戰略協同
• 反制發現：找到最佳的寶可夢來反制特定威脅

系統特性

• 連接狀態：即時監控 Algolia 連接，並顯示可用索引
• 混合搜索：在即時搜索和 AI 驅動分析之間無縫切換
• 響應式設計：基於網格的結果佈局，針對所有屏幕尺寸進行優化
• 錯誤處理：全面的錯誤邊界和回退狀態
• 動畫效果：由 GSAP 驅動的平滑過渡和懸停效果

🔧 技術細節

技術棧

• 前端：React 19 + TypeScript + Vite
• 樣式：Tailwind CSS v3，帶有玻璃擬態效果
• 搜索引擎：Algolia v5，自定義搜索集成
• 狀態管理：自定義 React hooks，集中對戰邏輯
• 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 hooks
│   │   │   ├── 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 接口，涵蓋：

• 寶可夢數據：完整的種族值、特性、技能集、屬性相剋
• 技能數據：威力、命中率、描述、競技可行性
• 特性數據：效果、競技評分、與寶可夢的關聯
• 競技統計數據：使用率百分比、分級分佈、隊伍協同
• 推薦數據：AI 生成的對戰建議及推理

💻 使用示例

自然語言查詢

"什麼寶可夢能對抗噴火龍？"
→ 返回具有屬性優勢的寶可夢，並給出推理

"適合競技對戰的最佳水系寶可夢"
→ 按屬性和競技可行性進行過濾

"能學會冰光束且速度快的寶可夢"
→ 交叉參考技能集和種族值

"為OU分級組建一支雨天隊"
→ 給出隊伍組成建議，並進行協同分析

搜索功能

• 反制分析：識別屬性優勢、速度分級和防禦匹配
• 隊伍組建：分析屬性覆蓋、角色分佈和戰略協同
• 技能搜索：找到能學會特定技能的寶可夢，並考慮競技背景
• 屬性過濾：根據單一/雙屬性進行高級過濾，並設置種族值要求

🏆 競技特性

分級集成

• OU（常用）：標準競技分級分析
• UU/RU/NU：較低分級的可行性評估
• Ubers：傳說/受限格式支持
• LC（小型杯）：進化前寶可夢的競技分析

對戰情報

• 對戰評分：對戰優勢的數值評分（0 - 100）
• 速度分級分析：關鍵速度基準比較
• 屬性覆蓋：完整的進攻和防禦屬性分析
• 環境感知：當前使用率趨勢和隊伍原型識別

📚 詳細文檔

TypeScript 設置

項目使用嚴格的 TypeScript 和 verbatimModuleSyntax：

• 僅類型導入：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）
• 未使用的組件（13 個文件，包括 SearchInterface、FeatureShowcase 等）
• 未使用的鉤子（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 低於 50 毫秒的搜索性能
• 緩存：智能結果緩存，用於重複查詢

🚧 未來路線圖

計劃功能

• MCP 服務器集成：Claude 桌面工作流自動化
• 隊伍導出：寶可夢對戰平臺格式兼容
• 對戰模擬器：即時對戰場景測試
• 社區功能：隊伍分享和評分系統
• 高級分析：勝率預測和環境跟蹤

技術增強

• 即時數據：即時競技使用率更新
• 機器學習：增強推薦算法
• 性能：高級緩存和 CDN 集成
• 移動應用：React Native 配套應用

📄 許可證

本項目是開源的，採用 MIT 許可證。

👥 貢獻

歡迎貢獻代碼！請查看我們的貢獻指南以獲取更多信息。

---

為寶可夢競技社區而打造