PokéBattle AI Strategist

An intelligent Pokémon battle strategy assistant powered by Algolia search and natural language processing. This application provides strategic recommendations, type effectiveness analysis, and competitive insights through conversational AI.

Features

Natural Language Battle Planning

• Conversational Queries: Ask complex questions like "What's the best counter to a Charizard with Solar Beam?" or "Build me a team that can handle Dragon-types"
• AI-Powered Recommendations: Get strategic advice with detailed reasoning for team building and battle scenarios
• Context-Aware Analysis: Understands competitive formats, tiers, and battle contexts

Advanced Search Capabilities

• Multi-Index Search: Simultaneously searches across Pokémon, moves, abilities, and competitive data
• Type Effectiveness Engine: Complete type matchup calculations with resistance and immunity analysis
• Competitive Intelligence: Usage statistics, tier analysis, and meta trend insights
• Faceted Filtering: Filter by stats, types, generations, tiers, and battle roles

Interactive Battle Analysis

• Real-time Strategy: Get optimal move suggestions and switch recommendations
• Matchup Scoring: AI calculates and explains matchup advantages with numerical ratings
• Team Synergy Analysis: Identifies type coverage gaps and strategic synergies
• Counter Discovery: Find the best Pokémon to counter specific threats

System Features

• Connection Status: Real-time Algolia connection monitoring with available indices display
• Hybrid Search: Seamless switching between instant search and AI-powered analysis
• Responsive Design: Grid-based results layout optimized for all screen sizes
• Error Handling: Comprehensive error boundaries and fallback states
• Animation Effects: GSAP-powered smooth transitions and hover effects

Architecture

Technology Stack

• Frontend: React 19 + TypeScript + Vite
• Styling: Tailwind CSS v3 with glassmorphism effects
• Search Engine: Algolia v5 with custom search integration
• State Management: Custom React hooks with centralized battle logic
• AI Integration: Natural language processing for query interpretation
• Animations: GSAP for smooth transitions and effects
• Icons: Lucide React for consistent iconography

Project Architecture

pokemon_algolia_mcp/
├── frontend/            # React TypeScript application
│   ├── src/
│   │   ├── components/  # UI components
│   │   │   ├── HybridSearch.tsx        # Main search interface
│   │   │   ├── AlgoliaStatus.tsx       # Connection status display
│   │   │   ├── SearchResults.tsx       # Pokemon grid results
│   │   │   ├── PokemonAnalysis.tsx     # Battle analysis
│   │   │   ├── CustomInstantSearchResults.tsx  # Custom search results
│   │   │   ├── SearchResultItem.tsx    # Individual result card
│   │   │   ├── Header.tsx              # App header
│   │   │   └── ErrorBoundary.tsx       # Error handling
│   │   ├── services/    # Business logic
│   │   │   ├── algolia-enhanced.ts     # Advanced Algolia integration
│   │   │   └── naturalLanguageSearchEnhanced.ts  # Enhanced NLP search
│   │   ├── hooks/       # Custom React hooks
│   │   │   ├── useAlgoliaSearch.ts     # Search integration
│   │   │   └── useGSAPAnimations.ts    # Animation effects
│   │   ├── types/       # TypeScript interfaces
│   │   │   └── pokemon.ts              # Data models
│   │   ├── utils/       # Utility functions
│   │   │   └── pokemon.ts              # Pokemon helper functions
│   │   └── data/        # Static data
│   │       └── mockPokemon.ts          # Demo data
│   └── package.json
├── backend/             # Express.js server
│   ├── src/
│   │   ├── server.ts    # Main server file
│   │   ├── mcpClient.ts # MCP integration
│   │   ├── routes/      # API routes
│   │   └── utils/       # Server utilities
│   └── package.json
├── mcp-node/            # Algolia MCP server
│   ├── src/
│   │   ├── app.ts       # MCP server implementation
│   │   ├── tools/       # MCP tools
│   │   └── data/        # Algolia API definitions
│   └── package.json
└── package.json         # Root workspace configuration

Data Model

The application uses comprehensive TypeScript interfaces covering:

• PokemonData: Complete stats, abilities, movesets, type effectiveness
• MoveData: Power, accuracy, descriptions, competitive viability
• AbilityData: Effects, competitive ratings, Pokémon associations
• CompetitiveStatsData: Usage percentages, tier distributions, team synergies
• RecommendationData: AI-generated battle suggestions with reasoning

Getting Started

Prerequisites

• Node.js 18+
• npm package manager

Installation

# Clone the repository
git clone [repository-url]
cd pokemon_algolia_mcp

# Install all dependencies (frontend, backend, and mcp-node)
npm run install:all

# Or install manually
npm install
cd frontend && npm install
cd ../backend && npm install
cd ../mcp-node && npm install

Environment Setup

1. Copy the environment example file:

cp .env.example .env

2. Configure your environment variables in .env:

# Algolia Configuration (get from Algolia dashboard)
ALGOLIA_APP_ID=your_algolia_app_id
ALGOLIA_API_KEY=your_algolia_search_key

# Anthropic API Key (required for AI features)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
# or
CLAUDE_API_KEY=your_claude_api_key_here

# Server Configuration
PORT=3000

Running the Application

# Start both frontend and backend concurrently
npm run dev

# Or start individually
npm run dev:frontend  # Frontend only (http://localhost:5173)
npm run dev:backend   # Backend only (http://localhost:3000)

Development Commands

npm run dev              # Start both frontend and backend
npm run dev:frontend     # Start frontend only (Vite dev server)
npm run dev:backend      # Start backend only (Express server)
npm run build            # Build both frontend and backend
npm run build:frontend   # Build frontend only
npm run build:backend    # Build backend only
npm run test             # Run linting and type checking
npm run clean            # Clean all node_modules

Project Structure

This is a monorepo with three main packages:

• frontend/: React + TypeScript + Vite application
• backend/: Express.js server with MCP integration
• mcp-node/: Algolia MCP server implementation

Environment Configuration

The application requires Algolia search configuration:

Setting up Algolia:

1. Create a free account at algolia.com
2. Create a new application
3. Get your App ID from the dashboard
4. Generate a search-only API key (API Keys section)
5. Set up a pokemon index with your Pokemon data

Required Environment Variables:

• App ID: Get from your Algolia dashboard
• Search-Only API Key: Generate a search-only key in Algolia dashboard
• Anthropic API Key: Required for AI features (set in .env)

Usage Examples

Natural Language Queries

"What counters Charizard?"
→ Returns type-advantaged Pokémon with reasoning

"Best Water types for competitive play"
→ Filters by type and competitive viability

"Pokemon that can learn Ice Beam and have high speed"
→ Cross-references movesets and stats

"Build a rain team for OU tier"
→ Suggests team compositions with synergy analysis

Search Features

• Counter Analysis: Identifies type advantages, speed tiers, and defensive matchups
• Team Building: Analyzes type coverage, role distribution, and strategic synergies
• Move Search: Finds Pokémon that learn specific moves with competitive context
• Type Filtering: Advanced filtering by single/dual types with stat requirements

🏆 Competitive Features

Tier Integration

• OU (OverUsed): Standard competitive tier analysis
• UU/RU/NU: Lower tier viability assessments
• Ubers: Legendary/restricted format support
• LC (Little Cup): Pre-evolution competitive analysis

Battle Intelligence

• Matchup Scoring: Numerical ratings (0-100) for battle advantages
• Speed Tier Analysis: Critical speed benchmark comparisons
• Type Coverage: Complete offensive and defensive type analysis
• Meta Awareness: Current usage trends and team archetype recognition

Configuration

TypeScript Setup

The project uses strict TypeScript with verbatimModuleSyntax:

• Type-only imports: import type { Pokemon } from '../types/pokemon'
• Value imports: import { charizardData } from '../data/pokemon'

Algolia Configuration

The application connects to a pre-configured Algolia index with Pokemon data:

• Index Name: pokemon
• Search Features: Instant search, faceting, highlighting
• Data Structure: Pokemon stats, types, moves, competitive info

Troubleshooting

Common Issues

1. Dependencies Installation

# If npm install fails, try clearing cache
npm cache clean --force
npm run clean
npm run install:all

2. Port Conflicts

• Frontend runs on port 5173 (Vite default)
• Backend runs on port 3000 (or PORT env variable)
• Check if ports are available or modify in package.json

3. Environment Variables

# Ensure .env file exists in root directory
cp .env.example .env
# Add your Anthropic API key for AI features

4. TypeScript Errors

# Run type checking
npm run test
# Check individual packages
cd frontend && npm run lint
cd backend && npm run type-check

5. Search Not Working

• Verify Algolia credentials in .env
• Check browser console for API errors
• Try demo mode if instant search fails

Development Tips

• Use browser dev tools to debug Algolia API calls
• Check network tab for MCP server communication
• Enable verbose logging in development mode

Design System

Visual Theme

• Dark Gradient Background: Blue → Purple → Indigo progression
• Glassmorphism Effects: backdrop-blur-lg with transparency
• Typography: Clean hierarchy with gradient accent colors
• Interactive Elements: Smooth transitions with hover states

Responsive Design

• Mobile-First: Optimized for all screen sizes
• Grid Layouts: Adaptive column counts (1/2/3/4/5 columns)
• Touch-Friendly: Large tap targets and gesture support

Development

Codebase Cleanup (Latest)

The project recently underwent a major cleanup to reduce technical debt:

Removed Files (26 total):

• Deprecated services (algolia.ts, naturalLanguageSearch.ts, instantSearchClient.ts)
• Unused components (13 files including SearchInterface, FeatureShowcase, etc.)
• Unused hooks (useBattleStrategy.ts, useNaturalLanguageBattle.ts)
• Test/utility files and backup directories
• Unused dependencies (react-instantsearch package)

Current Architecture Benefits:

• Cleaner, focused codebase with only active functionality
• Reduced bundle size and improved performance
• Better maintainability and developer experience
• Streamlined component hierarchy

Adding New Features

1. New Search Types: Extend interfaces in naturalLanguageSearchEnhanced.ts
2. Additional Data: Update TypeScript interfaces in types/pokemon.ts
3. UI Components: Follow existing patterns with Tailwind styling
4. Search Logic: Implement in algolia-enhanced.ts with proper error handling

Code Quality

• ESLint: Configured with React and TypeScript rules
• Type Safety: Strict TypeScript with comprehensive interfaces
• Component Design: Atomic components with clear prop interfaces
• State Management: Custom hooks for business logic separation

Performance

Optimization Features

• Vite Build System: Fast development and optimized production builds
• Code Splitting: Automatic chunking for optimal loading
• Search Optimization: Algolia's sub-50ms search performance
• Caching: Intelligent result caching for repeated queries

Future Roadmap

Planned Features

• MCP Server Integration: Claude Desktop workflow automation
• Team Export: Pokemon Showdown format compatibility
• Battle Simulator: Real-time battle scenario testing
• Community Features: Team sharing and rating system
• Advanced Analytics: Win rate predictions and meta tracking

Technical Enhancements

• Real-time Data: Live competitive usage updates
• Machine Learning: Enhanced recommendation algorithms
• Performance: Advanced caching and CDN integration
• Mobile App: React Native companion application

License

This project is open source and available under the MIT License.

Contributing

Contributions are welcome! Please see our contributing guidelines for more information.

---

Built for the Pokémon competitive community