Algolia MCP

🚀 PokéBattle AI Strategist

An intelligent Pokémon battle strategy assistant integrating Algolia search and natural language processing. It offers strategic advice, type effectiveness analysis, and competitive insights via conversational AI.

🚀 Quick Start

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)

✨ Features

Natural Language Battle Planning

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

Advanced Search Capabilities

• Multi-Index Search: Simultaneously search across Pokémon, moves, abilities, and competitive data.
• Type Effectiveness Engine: Conduct complete type matchup calculations with resistance and immunity analysis.
• Competitive Intelligence: Provide 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: Obtain optimal move suggestions and switch recommendations.
• Matchup Scoring: AI calculates and explains battle advantages with numerical ratings.
• Team Synergy Analysis: Identify type coverage gaps and strategic synergies.
• Counter Discovery: Find the best Pokémon to counter specific threats.

System Features

• Connection Status: Monitor Algolia connection in real-time and display available indices.
• Hybrid Search: Seamlessly switch between instant search and AI-powered analysis.
• Responsive Design: Optimize grid-based results layout for all screen sizes.
• Error Handling: Implement comprehensive error boundaries and fallback states.
• Animation Effects: Use GSAP for smooth transitions and hover effects.

🔧 Technical Details

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 utilizes 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.

💻 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: Identify type advantages, speed tiers, and defensive matchups.
• Team Building: Analyze type coverage, role distribution, and strategic synergies.
• Move Search: Find Pokémon that learn specific moves in a competitive context.
• Type Filtering: Perform 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: Support for legendary/restricted formats.
• 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: Recognition of current usage trends and team archetypes.

📚 Documentation

Configuration

TypeScript Setup

The project employs 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: Progression from blue to purple to indigo.
• 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: Compatibility with Pokemon Showdown format.
• 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.

💡 Usage Tip

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

Built for the Pokémon competitive community