# 🏆 Pokémon Champion - Team Builder & AI MCP Server

A modern competitive **Pokémon Team Builder** application featuring full EV/IV customization, custom Developer rules, real-time battle statistics powered by the **Champions Battle Data API**, and an official **Model Context Protocol (MCP) Remote Server** to connect your team data directly with **Claude AI**.

![Node.js](https://img.shields.io/badge/Node.js-v18%2B-brightgreen?logo=node.js)
![Express](https://img.shields.io/badge/Express-v4.18-blue?logo=express)
![MCP](https://img.shields.io/badge/MCP--SDK-v2-orange?logo=anthropic)
![License](https://img.shields.io/badge/License-MIT-green)

---

## ✨ Features

- **🎮 Competitive Team Builder**:
  - Build & manage teams of up to 6 Pokémon with interactive slot assignment.
  - Custom EV controls with step buttons (`-1`, `+1`) and intelligent `MAX` budget calculation (max 32 EV per stat, 66 EV total budget limit).
  - Showdown Paste export and import format support.
  - Save Pokémon directly to a personal BOX.

- **🛠️ Developer Control Panel**:
  - Define custom allowed move pools per Pokémon (e.g. Mega Malamar, Mega Raichu Y).
  - Restrict held items with strict non-duplication enforcement per team.

- **📊 Champions Battle Data API Integration**:
  - View real-time competitive Meta Usage Rankings sorted from **#1 to #40** for both **Doubles** and **Singles** formats.
  - Inspect top used moves, held items, natures, EV spreads, and best synergy teammates per Pokémon.

- **🤖 Model Context Protocol (MCP) Remote Server**:
  - Built using Anthropic's official `@modelcontextprotocol/server` (v2 spec `mcp-client-2025-11-20`).
  - Exposes 7 tools for Claude to read teams, query meta stats, enforce dev rules, and automatically save AI-generated teams.

---

## ⚡ Quick Start

### 1. Install Dependencies

```bash
# Main application
npm install

# MCP Server
cd mcp-server
npm install
cd ..
```

### 2. Run Main Web App

```bash
npm start
```
The Web App will run at `http://localhost:3030`.

### 3. Run MCP Server (for Claude AI)

```bash
cd mcp-server
node mcp-server.js
```
The MCP Server will run at `http://localhost:3031/mcp`.

---

## 🤖 Remote MCP Tools for Claude

| Tool Name | Description |
|---|---|
| `get_teams` | Returns all saved teams formatted as Showdown pastes |
| `get_team` | Searches a specific team by name and returns Showdown paste |
| `get_allowed_moves` | Returns allowed/custom moves for a Pokémon from Dev Panel |
| `get_allowed_items` | Returns allowed held items list (with item non-duplication rule) |
| `get_meta_top_pokemon` | Returns top used Pokémon ranked #1, #2... in Doubles/Singles |
| `get_meta_pokemon_details` | Returns top moves, items, natures, EV spreads & teammates |
| `save_team` | Parses a Showdown paste from Claude and saves it directly to `teams.json` |

---

## 🔒 Connecting to your Claude Account

1. Start your local MCP Server (`node mcp-server/mcp-server.js`).
2. Expose the port over HTTPS using Cloudflare Tunnels:
   ```bash
   cloudflared tunnel --url http://localhost:3031
   ```
3. Open your account on **[Claude.ai](https://claude.ai)** or **Claude Desktop**.
4. Go to **Customize** -> **Connectors** -> **Add Custom Connector**.
5. Paste your HTTPS URL (e.g. `https://your-tunnel.trycloudflare.com/mcp`).
6. Enable the connector in your chat conversation and start asking Claude to build & optimize your teams!

---

## 🤝 Attributions & Credits

- Pokémon data provided by **[PokéAPI](https://pokeapi.co)**.
- Battle data provided by **[Pokémon Champions Battle Data](https://championsbattledata.com/)**.

---

## ⚖️ Legal Disclaimer

This fan-made project is not affiliated with, endorsed by, or sponsored by Pokémon, Nintendo, GAME FREAK, Creatures Inc., or The Pokémon Company.

---

## 📄 License

Distributed under the MIT License.