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 许可证。

👥 贡献

欢迎贡献代码！请查看我们的贡献指南以获取更多信息。

为宝可梦竞技社区而打造