Pokemon Chat - Mobile Demo

A real-time, mobile-friendly Pokemon chat assistant that allows users to ask questions and get instant responses about Pokemon with images and detailed information.

🚀 Quick Deploy to Azure

This app includes Docker support for seamless deployment to Azure App Service with native dependencies (face-recognition, dlib):

📦 Complete Deployment Guide →

Quick Setup:

Create Azure Container Registry (ACR)
Create Azure App Service (Linux Container)
Configure GitHub Secrets
Push to main - Auto-deploys via GitHub Actions!

Why Docker?

✅ Handles native dependencies (dlib, cmake, build-essential)
✅ Reliable face-recognition feature deployment
✅ Consistent builds across all environments
✅ One-command deployment

Features

🎮 Real-time Chat Interface - Interactive chat with instant responses
📱 Mobile-Optimized - Responsive design tailored for mobile devices
🖼️ Pokemon Images - Official artwork and sprites
📊 Detailed Information - Stats, types, abilities, and descriptions
💬 Natural Language - Ask questions in plain English
🎤 Voice Conversation - Talk to the assistant using voice commands
👤 Face Recognition - Real-time user identification during voice conversations (NEW!)
🃏 Trading Card Game - Search and view Pokemon TCG cards with images (NEW!)
💡 Card Context Awareness - The assistant keeps track of the MCP card you have open and injects that card’s summary into every conversation so follow-ups can reference it directly
🛠️ Tool Management - Enable/disable features via settings modal (NEW!)
⚡ Fast Lookup - Powered by PokeAPI for comprehensive Pokemon data
🎨 Beautiful UI - Modern, colorful design inspired by Pokemon

Screenshots

The app features a clean, mobile-first design with:

Gradient header with Pokemon branding
Smooth chat bubbles for user and assistant messages
Interactive Pokemon cards with images
Type badges with official Pokemon colors
Detailed stat displays with progress bars
TCG card grid with clickable card previews

Technologies Used

Backend: Python Flask
Frontend: HTML5, CSS3, Vanilla JavaScript
APIs:
- PokeAPI for Pokemon game data
- Pokemon TCG API for trading card data
Face Recognition: face_recognition library (based on dlib)
Voice: Web Speech API (Speech Recognition + Synthesis)
Styling: Custom CSS with mobile-first responsive design
Architecture: RESTful API with JSON responses

PokeAPI Fair Use & Caching

Every client-side Pokemon lookup now goes through the Flask proxy blueprint mounted at /api/pokemon. The proxy forwards to PokeAPI, writes the response through CacheService, and serves subsequent requests from disk so we comply with PokeAPI’s “locally cache resources whenever you request them” rule.
Available proxy routes (all support ?refresh=1 to bypass the cache and pull fresh data):
- GET /api/pokemon/<name_or_id> – core Pokemon payloads used by the grid, detail view, and evolution previews.
- GET /api/pokemon/species/<name_or_id> – species metadata (entries, egg groups, evolution chain pointer).
- GET /api/pokemon/evolution-chain/<chain_id> – deep evolution data.
- GET /api/pokemon/type/<type_name> – damage relations for weakness calculations.
The cache directory (/cache) keeps descriptive filenames; expiration defaults to 7 days but can be tuned in cache/cache_config.json or via the existing cache settings routes.
Force-refresh actions in the UI invalidate both the chat tool cache (get_pokemon) and the new proxy caches by issuing refresh=1 requests, so the next render picks up live data without manual file edits.
Override the upstream host with the POKEMON_API_URL environment variable if you need to point at a mirror during development; the proxy uses that value for every outbound request.

Installation

Prerequisites

Python 3.8 or higher
pip (Python package manager)
For face-recognition feature: cmake, build-essential (Linux) or Xcode Command Line Tools (macOS)

Setup

Option 1: Docker (Recommended - includes all native dependencies)

# Clone the repository
git clone https://github.com/7effrey89/Pokedex.git
cd Pokedex

# Build the Docker image
docker build -t pokedex-app .

# Run the container
docker run -p 8000:8000 --env-file .env pokedex-app

# Access at http://localhost:8000

Option 2: Local Python Installation

Clone the repository

git clone https://github.com/7effrey89/Pokedex.git
cd Pokedex

Install system dependencies (for face-recognition)

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y build-essential cmake libopenblas-dev liblapack-dev

macOS:

xcode-select --install
brew install cmake

Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies
```
pip install -r requirements.txt
```
Note: On Windows, installing dlib (required by face-recognition) can be challenging. Consider using Docker or WSL2 for easier setup.

Set up environment variables (optional)

cp .env.example .env
# Edit .env if you want to add Azure OpenAI integration in the future

Run the application
```
python app.py
```
Open in browser
- Navigate to http://localhost:5000
- For mobile testing, use your local IP address (e.g., http://192.168.1.100:5000)

Deploying to Azure App Service

You can host the entire experience on Azure Web Apps so the realtime chat, MCP tools, and camera scanner are available from anywhere.

Docker + ACR Deployment (Recommended for Native Dependencies)

For reliable deployment with native dependencies like face-recognition (dlib, cmake), use Docker with Azure Container Registry:

📦 See docs/AZURE_DEPLOYMENT.md for comprehensive step-by-step instructions

Why Docker?

✅ Handles native dependencies (dlib, cmake, build-essential)
✅ Consistent builds across environments
✅ Full control over system packages
✅ Reliable and reproducible deployments
✅ Built-in health checks for container readiness

Step-by-Step Setup

1. Create Azure Container Registry (ACR)

az login
RESOURCE_GROUP=pokedex-rg
LOCATION=eastus
ACR_NAME=pokedexacr  # Must be globally unique, alphanumeric only

# Create resource group
az group create --name $RESOURCE_GROUP --location $LOCATION

# Create ACR (Basic tier is sufficient for small projects)
az acr create \
  --resource-group $RESOURCE_GROUP \
  --name $ACR_NAME \
  --sku Basic \
  --admin-enabled true

# Get ACR credentials (for GitHub Actions)
az acr credential show --name $ACR_NAME --resource-group $RESOURCE_GROUP

2. Create Azure App Service (Linux Container)

ℹ️ WebSocket Support: For realtime voice features, use Standard (S1) or higher plans.

APP_NAME=pokedex-chat  # Must be globally unique

# Create App Service Plan (Linux)
az appservice plan create \
  --name $APP_NAME-plan \
  --resource-group $RESOURCE_GROUP \
  --sku S1 \
  --is-linux

# Create Web App with container configuration
az webapp create \
  --resource-group $RESOURCE_GROUP \
  --plan $APP_NAME-plan \
  --name $APP_NAME \
  --deployment-container-image-name $ACR_NAME.azurecr.io/pokedex-app:latest

3. Enable Managed Identity and Assign AcrPull Role

This allows the Web App to pull images from ACR without storing credentials:

# Enable system-assigned managed identity
az webapp identity assign \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME

# Get the principal ID of the managed identity
PRINCIPAL_ID=$(az webapp identity show \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --query principalId \
  --output tsv)

# Get ACR resource ID
ACR_ID=$(az acr show \
  --name $ACR_NAME \
  --resource-group $RESOURCE_GROUP \
  --query id \
  --output tsv)

# Assign AcrPull role to the Web App's managed identity
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role AcrPull \
  --scope $ACR_ID

4. Configure App Settings

Set required environment variables for proper container startup:

az webapp config appsettings set \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --settings \
    WEBSITES_PORT=80 \
    WEBSITE_HEALTHCHECK_MAXPINGFAILURES=3 \
    WEBSITES_CONTAINER_START_TIME_LIMIT=230 \
    FLASK_ENV=production \
    FLASK_DEBUG=False \
    AZURE_OPENAI_ENDPOINT="https://<YourResource>.openai.azure.com/" \
    AZURE_OPENAI_API_KEY="<key>" \
    AZURE_OPENAI_DEPLOYMENT="gpt-4" \
    AZURE_OPENAI_REALTIME_DEPLOYMENT="gpt-4o-realtime-preview" \
    AZURE_OPENAI_REALTIME_API_VERSION="2024-10-01-preview" \
    POKEMON_API_URL="https://pokeapi.co/api/v2" \
    POKEMON_TCG_API_KEY="<key>" \
    USE_NATIVE_MCP=false

5. Configure Health Check Path

Enable Azure's health check monitoring:

az webapp config set \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --generic-configurations '{"healthCheckPath": "/api/health"}'

6. Configure Deployment Center for ACR

Connect the Web App to pull images from ACR using Managed Identity:

# Configure container settings to use ACR with managed identity
az webapp config container set \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --docker-custom-image-name $ACR_NAME.azurecr.io/pokedex-app:latest \
  --docker-registry-server-url https://$ACR_NAME.azurecr.io

# Enable continuous deployment (webhook)
az webapp deployment container config \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --enable-cd true

7. (Optional) Enable Always On

Keeps the app loaded and reduces cold start times (requires Basic tier or higher):

az webapp config set \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --always-on true

8. Restart Web App After Configuration

After assigning roles and configuring settings, restart the app:

az webapp restart \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME

CI/CD with GitHub Actions

The repository includes .github/workflows/build-and-deploy-acr.yml for automated builds and deployments.

Configure GitHub Secrets:

In your GitHub repository, go to Settings → Secrets and variables → Actions and add:

ACR_LOGIN_SERVER → Your ACR login server (e.g., pokedexacr.azurecr.io)
ACR_USERNAME → ACR admin username (from step 1)
ACR_PASSWORD → ACR admin password (from step 1)
AZURE_WEBAPP_NAME → Your Web App name (e.g., pokedex-chat)
AZURE_WEBAPP_PUBLISH_PROFILE → Download from Azure Portal: App Service → Deployment → Get publish profile

Image Tagging Strategy:

The workflow automatically tags images with:

latest - Always points to the latest main branch build
main-<git-sha> - Specific commit SHA for rollback capability
main - Branch name tag

Push to main branch to trigger automatic build and deployment.

Viewing Logs and Diagnostics

Stream Live Logs:

# Application logs
az webapp log tail \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME

# Container logs
az webapp log tail \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --container-name $APP_NAME

Enable Diagnostic Logging (Azure Portal):

Navigate to your App Service
Go to Monitoring → App Service logs
Enable:
- Application Logging (Filesystem) - Logs application output
- Web server logging - Logs HTTP requests
- Detailed error messages - Detailed error pages
Click Save

View in Log Stream:

Azure Portal → Monitoring → Log stream for real-time logs

Troubleshooting Startup Probe Failures

If your container fails to start or the health check fails intermittently:

1. Check Health Endpoint Locally:

# Test the Docker image locally first
docker build -t pokedex-test .
docker run -p 8080:80 -e PORT=80 pokedex-test

# In another terminal, test the health endpoint
curl http://localhost:8080/api/health

2. Increase Start Time Limit:

# Give the container more time to start (default is 230 seconds)
az webapp config appsettings set \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --settings WEBSITES_CONTAINER_START_TIME_LIMIT=300

3. Check Container Logs:

# View container startup logs
az webapp log download \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --log-file logs.zip

unzip logs.zip
cat */docker.log

4. Verify Environment Variables:

# List all app settings
az webapp config appsettings list \
  --resource-group $RESOURCE_GROUP \
  --name $APP_NAME \
  --output table

5. Check Docker HEALTHCHECK Status:

The Dockerfile includes a built-in health check that probes /api/health every 30 seconds. If the endpoint fails 3 times, the container is marked unhealthy.

# Inspect running container locally
docker ps
docker inspect <container-id> | grep -A 10 "Health"

6. Common Issues:

Wrong Port Binding: Ensure WEBSITES_PORT=80 matches the port in Dockerfile EXPOSE and gunicorn --bind
Missing Dependencies: Check that requirements.txt includes all necessary packages
Slow Startup: Native dependencies (face-recognition, dlib) take time to install. Use Docker for faster, pre-built images.
Health Check Path: Verify /api/health endpoint is accessible and returns HTTP 200
Managed Identity Permissions: After assigning AcrPull role, restart the Web App for changes to take effect

7. Force Restart After Role Assignment:

# Stop the app
az webapp stop --resource-group $RESOURCE_GROUP --name $APP_NAME

# Wait a few seconds
sleep 5

# Start the app
az webapp start --resource-group $RESOURCE_GROUP --name $APP_NAME

Manual Azure CLI Deployment (Alternative)

If you prefer manual deployment or don't need face recognition features:

Prerequisites

Azure CLI
An Azure subscription with permission to create App Service resources
Python 3.11 locally (matches the runtime we deploy)

1. Prepare environment variables

Create or update a .env file with the secrets you want in production (Azure OpenAI keys, PokeAPI overrides, POKEMON_TCG_API_KEY, etc.). These values will be mirrored into App Service settings.

2. Log in and create Azure resources

ℹ️ Realtime voice relies on WebSockets. Azure only enables WebSockets on Standard (S1) App Service plans and above, so choose at least S1 for the deployment plan.

az login
RESOURCE_GROUP=pokedex-rg
LOCATION=swedencentral
APP_NAME=pokedex-chat

az group create --name $RESOURCE_GROUP --location $LOCATION
az appservice plan create \
   --name $APP_NAME-plan \
   --resource-group $RESOURCE_GROUP \
   --sku S1 \
   --is-linux
az webapp create \
   --resource-group $RESOURCE_GROUP \
   --plan $APP_NAME-plan \
   --name $APP_NAME \
   --runtime "PYTHON|3.11"

3. Push configuration to App Service

Mirror your .env contents (plus production-only values) into App Service settings:

az webapp config appsettings set \
   --resource-group $RESOURCE_GROUP \
   --name $APP_NAME \
   --settings \
      FLASK_ENV=production \
      FLASK_DEBUG=False \
      PORT=5000 \
      AZURE_OPENAI_ENDPOINT="https://<YourResource>.openai.azure.com/" \
      AZURE_OPENAI_API_KEY="<key>" \
      AZURE_OPENAI_DEPLOYMENT="gpt-5.1-chat" \
      AZURE_OPENAI_REALTIME_DEPLOYMENT="gpt-realtime" \
      AZURE_OPENAI_REALTIME_API_VERSION="2024-10-01-preview" \
      POKEMON_API_URL="https://pokeapi.co/api/v2" \
      POKEMON_TCG_API_KEY="<key>" \
      TCG_PAGE_SIZE=250 \
      APP_API_PASSWORD="PasswordExample" \
      USE_NATIVE_MCP=false \
      SCM_DO_BUILD_DURING_DEPLOYMENT=true

Add any Azure OpenAI or MCP endpoints the same way. App settings become environment variables available to Flask when it starts.

4. Package and deploy the code

Create a clean build (exclude caches and local venvs) and push it with Zip Deploy:

Linux / macOS

zip -r pokedex.zip app.py src static templates \
         requirements.txt realtime_chat.py azure_openai_chat.py \
         tools_config.json data tcg-cache

Windows (PowerShell)

Remove-Item pokedex.zip -ErrorAction SilentlyContinue
Compress-Archive -Path app.py,src,static,templates,data,tcg-cache, `
  azure_openai_chat.py,realtime_chat.py,requirements.txt,tools_config.json `
  -DestinationPath pokedex.zip
Get-Item pokedex.zip

After the archive exists locally, push it with Zip Deploy:

az webapp deploy \
   --resource-group "$RESOURCE_GROUP" \
   --name "$APP_NAME" \
   --src-path pokedex.zip \
   --type zip

az webapp deploy --resource-group $env:RESOURCE_GROUP --name $env:APP_NAME --src-path "$PWD\pokedex.zip" --type zip

Azure's Oryx build system will automatically detect requirements.txt, create a virtual environment, and install all dependencies. Gunicorn starts automatically to serve the Flask application. Tail logs if you want to verify startup:

az webapp log tail --resource-group $RESOURCE_GROUP --name $APP_NAME

Option B — Deploy with GitHub Actions (CI/CD)

The repository includes .github/workflows/deploy-azure-webapp.yml, which automatically packages and deploys the app to Azure App Service. The workflow includes requirements.txt in the deployment, and Azure's Oryx build system handles dependency installation. To enable it:

Download your publish profile from the Azure Portal (App Service → Deployment → Get publish profile).
Create the following GitHub Action repository secrets in Settings → Secrets and variables → Actions:
- AZURE_WEBAPP_NAME → the App Service name (e.g., pokedex-chat) - must match the name of the web app.
- AZURE_WEBAPP_PUBLISH_PROFILE → paste the full contents of the downloaded publish profile XML.
Push to the main branch (default trigger) or run the workflow manually from the Actions tab using the Run workflow button. The optional environment input lets you tag runs as production, staging, etc.
Monitor the run logs to confirm the archive step and the azure/webapps-deploy@v3 action succeed. When it finishes, the new build is live in App Service and Oryx has automatically installed all dependencies from requirements.txt.

Tip: if deployment fails because of missing secrets or configuration, fix the issue and simply re-run the workflow from the failed run's page.

For more detailed information about the deployment process, see docs/AZURE_DEPLOYMENT.md.

GitHub Actions Error: "Failed to get app runtime OS"

If your GitHub Actions workflow fails with Error: Deployment Failed, Error: Failed to get app runtime OS, the target Azure Web App is likely blocking publish-profile based authentication. By default, App Service disables the legacy basic-auth endpoints when the Download publish profile policy is turned off, which prevents the azure/webapps-deploy action from authenticating.

To fix this:

Open the Azure Portal and navigate to your Web App.
Go to Settings → Configuration → General settings.
Scroll to the Authentication / Authorization section.
Set both SCM Basic Auth Publishing and FTP Basic Auth Publishing to Enabled.
Save the configuration and re-run the GitHub Actions workflow.

Re-enabling those toggles restores the Kudu/FTP endpoints that the publish profile depends on, allowing the action to retrieve the runtime OS metadata and complete the deployment.

Ask about any Pokemon using natural language:

"Tell me about Pikachu"
"Show me Charizard"
"What is Mewtwo"
"Find Bulbasaur"
Just type a Pokemon name: "Eevee"

Trading Card Game Queries (NEW! 🃏)

Search for Pokemon Trading Card Game cards:

"Show me Pikachu cards"
"Find Charizard TCG cards"
"Search trading cards for Mewtwo"
Click on any card to see full details including:
- High-resolution card image
- Attacks and abilities
- HP and retreat cost
- Format legality (Standard, Expanded, Unlimited)
- Rarity and artist information

Tool Management (NEW! 🛠️)

Click the Tools button in the header to manage available features:

PokeAPI 🎮 - Pokemon game data (stats, types, abilities)
Pokemon TCG 🃏 - Trading card search and display
Face Identification 👤 - Real-time user identification (NEW!)

Enable or disable tools based on your needs!

Voice Conversation (NEW! 🎤)

Talk to the assistant using your voice:

Click the "Voice" button in the top-right corner of the header
Allow microphone access when prompted
Speak your query (e.g., "Tell me about Pikachu")
The assistant will:
- Display your spoken message
- Fetch Pokemon information
- Show Pokemon cards with images
- Speak the response back to you!

Supported browsers: Chrome, Edge, Safari (iOS/macOS)

For detailed setup and Azure OpenAI integration, see VOICE_SETUP.md

Face Recognition (NEW! 👤)

Automatically identify users during voice conversations:

Setup

Create profile pictures directory (already created during installation)
```
mkdir -p profiles_pic
```
Add profile pictures
- Place photos in the profiles_pic directory
- Filename (without extension) becomes the person's name
- Examples: John.jpg, Alice.png, Bob.jpeg
- Supported formats: .jpg, .jpeg, .png, .gif, .bmp
Enable Face Identification
- Click the Tools button in the header
- Toggle Face Identification to ON
- Click Save Changes

How It Works

When you start speaking during a voice conversation:
- The app captures an image from your camera
- Compares it against photos in profiles_pic
- Identifies who you are based on face matching
Greeting behavior:
- First time detected: Greets you by name (e.g., "Hello, John! Nice to see you.")
- Same person continues: No greeting (avoids repetition)
- New person starts speaking: Greets the new person
Privacy & Security:
- Photos are stored locally in profiles_pic (not committed to git)
- Camera access only triggered during voice conversations when feature is enabled
- Face comparison happens on your server, not sent to external services

Tips for Best Results

Use clear, well-lit photos with a single face
Front-facing photos work best
Multiple photos per person (different angles) can improve recognition
Keep filenames simple (e.g., John.jpg not John_Smith_Photo_2023.jpg)

Troubleshooting

No greeting appears:

Check that Face Identification is enabled in Tools
Verify profile pictures exist in profiles_pic directory
Check browser console for error messages
Ensure camera permissions are granted

Wrong person identified:

Add more/better quality photos for accurate matching
Ensure good lighting when using voice feature
Remove similar-looking photos that might cause confusion

Face not recognized:

Face might not be in profiles_pic - add a photo with your name
Photo quality might be poor - use a clear, front-facing photo
Camera angle might be bad - position yourself facing the camera

Quick Actions

Use the quick action buttons for common tasks:

❓ Help - Get information about what the bot can do
🎲 Random - Get suggestions for Pokemon to explore
⭐ Popular - See a list of popular Pokemon

Viewing Details

Click on any Pokemon image in the chat to see a detailed card
The card includes:
- High-resolution artwork
- Full description
- Type information
- Height and weight
- Abilities
- Base stats with visual indicators

API Endpoints

Chat Endpoints

POST /api/chat - Send a message and get a response

{
  "message": "Tell me about Pikachu",
  "user_id": "optional_user_id"
}

POST /api/chat/stream - Stream responses (Server-Sent Events)

Pokemon Endpoints

GET /api/pokemon/<name_or_id> - Get Pokemon data by name or ID
GET /api/history/<user_id> - Get conversation history for a user
GET /api/health - Health check endpoint

Project Structure

Pokedex/
├── app.py                 # Flask application and routes
├── pokemon_tools.py       # Pokemon API integration
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variables template
├── .gitignore            # Git ignore rules
├── README.md             # This file
├── templates/
│   └── index.html        # Main HTML template
└── static/
    ├── css/
    │   └── style.css     # Responsive styles
    └── js/
        └── app.js        # Frontend JavaScript

Future Enhancements

Planned Features

Azure OpenAI Integration - Add real-time audio responses using Azure AI
MCP Server Integration - Connect to Pokemon Trading Card Game data
Battle Simulator - Compare Pokemon stats
Team Builder - Create and save Pokemon teams
Progressive Web App (PWA) - Offline support and installable app
User Accounts - Save conversation history and favorites
Multi-language Support - Pokemon data in different languages
Voice Input - Ask questions using voice commands

Azure OpenAI Setup (Future)

To enable real-time audio responses:

Set up Azure OpenAI service

Add credentials to .env:

AZURE_OPENAI_ENDPOINT=your_endpoint
AZURE_OPENAI_API_KEY=your_key
AZURE_OPENAI_DEPLOYMENT=your_deployment

The app is designed to integrate with:

MCP Server Setup

The app uses MCP (Model Context Protocol) servers to fetch Pokemon data. There are two modes:

Option 1: Client-Side Tool Handling (Default)

Set USE_NATIVE_MCP=false in .env. The Flask app handles tool calls via stdio transport. No additional setup needed - MCP servers are spawned automatically.

Option 2: Native MCP (HTTP/SSE Mode)

For native MCP support where the Realtime API calls MCP servers directly:

Configure .env:

USE_NATIVE_MCP=true
POKE_MCP_SERVER_URL=http://localhost:3001
PTCG_MCP_SERVER_URL=http://localhost:3002

Build MCP servers (first time only):

# Poke MCP
cd poke-mcp
npm install
npm run build

# PTCG MCP
cd ../ptcg-mcp
npm install
npm run build

Start MCP servers in HTTP mode (open separate terminals):

# Terminal 1 - Poke MCP (port 3001)
cd poke-mcp
node dist/index.js --http --port=3001

# Terminal 2 - PTCG MCP (port 3002)
cd ptcg-mcp
node dist/index.js --http --port=3002

Start Flask app (third terminal):
```
python app.py
```

Note: Native MCP requires the Realtime API to have network access to the MCP server URLs. For local development, both servers must be running before using voice features.

Mobile Testing

Testing on Mobile Devices

Ensure devices are on the same network
Find your computer's IP address
- Windows: ipconfig
- Mac/Linux: ifconfig or ip addr
Access from mobile
- Navigate to http://YOUR_IP:5000 on your mobile device
Add to Home Screen (iOS/Android)
- Tap the share/menu button
- Select "Add to Home Screen"
- Opens like a native app!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

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

Acknowledgments

PokeAPI - The comprehensive Pokemon data API
Pokemon is a trademark of Nintendo/Game Freak/Creatures Inc.
This is a fan project and is not officially affiliated with Pokemon

Support

If you encounter any issues or have questions:

Check the Issues page
Create a new issue with details about your problem
Include your Python version and any error messages

Troubleshooting for github Action

if release pipeline gives following error:

Run azure/webapps-deploy@v3 (node:9551) [DEP0040] DeprecationWarning: The punycode module is deprecated. Please use a userland alternative instead. (Use node --trace-deprecation ... to show where the warning was created) (node:9551) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead. (node:9551) [DEP0169] DeprecationWarning: url.parse() behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for url.parse() vulnerabilities. Error: Deployment Failed, Error: Failed to get app runtime OS

This is likely caused by an expired or invalid AZURE_WEBAPP_PUBLISH_PROFILE secret. Common causes:

Expired publish profile — Azure rotates these. Re-download it from the Azure Portal. Missing/wrong AZURE_WEBAPP_NAME secret. To fix:

Go to Azure Portal → your Web App → Deployment Center → Manage publish profile → Download publish profile Copy the entire XML content Go to your GitHub repo → Settings → Secrets and variables → Actions Update AZURE_WEBAPP_PUBLISH_PROFILE with the new XML Also verify AZURE_WEBAPP_NAME matches your Azure Web App's exact name Alternatively, you can switch to using azure/login@v2 with a service principal (OIDC), which is more robust than publish profile

Credits

Developed as a mobile-friendly Pokemon chat demonstration with future integration capabilities for Azure OpenAI and MCP servers.

Name		Name	Last commit message	Last commit date
Latest commit History 186 Commits
.github		.github
cache		cache
data		data
docs		docs
poke-mcp		poke-mcp
pokeapi-cache		pokeapi-cache
profiles_pic		profiles_pic
ptcg-mcp		ptcg-mcp
scripts		scripts
src		src
static		static
tcg-cache		tcg-cache
templates		templates
test-scripts		test-scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
app.py		app.py
azure_openai_chat.py		azure_openai_chat.py
realtime_chat.py		realtime_chat.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Pokemon Chat - Mobile Demo

🚀 Quick Deploy to Azure

Features

Screenshots

Technologies Used

PokeAPI Fair Use & Caching

Installation

Prerequisites

Setup

Deploying to Azure App Service

Docker + ACR Deployment (Recommended for Native Dependencies)

Step-by-Step Setup

CI/CD with GitHub Actions

Viewing Logs and Diagnostics

Troubleshooting Startup Probe Failures

Manual Azure CLI Deployment (Alternative)

Prerequisites

1. Prepare environment variables

2. Log in and create Azure resources

3. Push configuration to App Service

4. Package and deploy the code

Option B — Deploy with GitHub Actions (CI/CD)

GitHub Actions Error: "Failed to get app runtime OS"

Trading Card Game Queries (NEW! 🃏)

Tool Management (NEW! 🛠️)

Voice Conversation (NEW! 🎤)

Face Recognition (NEW! 👤)

Setup

How It Works

Tips for Best Results

Troubleshooting

Quick Actions

Viewing Details

API Endpoints

Chat Endpoints

Pokemon Endpoints

Project Structure

Future Enhancements

Planned Features

Azure OpenAI Setup (Future)

MCP Server Setup

Option 1: Client-Side Tool Handling (Default)

Option 2: Native MCP (HTTP/SSE Mode)

Mobile Testing

Testing on Mobile Devices

Contributing

License

Acknowledgments

Support

Troubleshooting for github Action

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages