README.md

---
title: Coach Deep Blue
emoji: ♟️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: true
tags:
- mcp-in-action-track-consumer
- building-mcp-track-consumer
- mcp
- agent
- chess
- openai
- stockfish
short_description: Omniscient MCP Chess Agent for real-time voice coaching
---

# Coach Deep Blue - MCP Agent

## **Recreating the Legend.**  
**Deep Blue AI** is a fully autonomous, voice-enabled chess agent that connects a Large Language Model (OpenAI) with powerful local tools via the **Model Context Protocol (MCP)** pattern.

> *Unlike standard chatbots that hallucinate chess moves, Deep Blue never guesses. It uses Tools to perceive reality, calculate the optimal path, and verbally coach the player.*

🎥 **[Video Demonstration](https://youtu.be/R6oKPN7p2Ao)**
 
📢 **[Social Media Post](https://x.com/imbryanbradfo/status/1995160739770999032?s=20)**
---

### 🚨🟡🌍 IMPORTANT NOTICE FOR HACKATHON! 🤖♟️🚨

**🏆 Goal:** This project demonstrates the power of **MCP (Model Context Protocol)** in a real-world consumer application. We prove that giving an LLM access to specialized tools (Engine + Database) creates a "Super-Intelligence" capable of reasoning far beyond the model's native training data.

**🙏 Support:** If you enjoy the strategic depth and the robotic persona of Deep Blue, please give this Space a **Like (❤️)**! Your support helps us push the boundaries of Agentic AI in gaming.

---

## 🌐 Project Overview

Deep Blue AI is not just a chess interface; it's an **Intelligent Orchestrator**. It leverages a multi-tool architecture to perform complex strategic analysis in real-time:

*   **🤖 The Agent (Deep Blue):** A Persona-driven LLM that orchestrates the tools, synthesizes data, and communicates with the user via a cold, analytical voice.
*   **🧠 The Engine (Stockfish 16):** Provides ground-truth calculation and tactical evaluation.
*   **📚 The Library (Lichess DB):** Provides theoretical knowledge of over 2 million opening positions.
*   **👁️ The Eye (Tactical Analyzer):** A custom semantic tool that translates board states into human concepts (Pins, Forks, Checks).

---

## 🛠️ MCP Architecture & Tools

Our agent follows the **Model Context Protocol** principles. The LLM does not "play" chess; it queries tools to understand the game state.

### 1. ⚡ Tool: Stockfish 16 Engine (The Calculator)
*   **Purpose:** Pure calculation and optimal move generation.
*   **Implementation:** Running as a local binary within the Docker container via UCI Protocol.
*   **Usage:**
    *   Calculates evaluations in Centipawns (CP).
    *   Detects forced mates sequences.
    *   Generates the "Optimal Path" (PV - Principal Variation).

### 2. 📚 Tool: Lichess Opening Database (The Knowledge)
*   **Purpose:** Contextualizing the game phase.
*   **Data Source:** A local compilation of Lichess master games compressed into TSV files (2M+ opening variations (TSV Lookup))
*   **Usage:**
    *   Identifies the exact opening name (e.g., *"Sicilian Defense: Najdorf Variation"*).
    *   Allows the Agent to switch strategy based on opening theory.

### 3. 🔍 Tool: Tactical Analyzer (The Semantic Layer)
*   **Purpose:** Translating raw board data into semantic concepts the LLM can explain.
*   **Logic:** Custom Python algorithms using `python-chess`.
*   **Usage:**
    *   **Material Scan:** Prevents hallucinations by listing exact remaining pieces.
    *   **Pattern Recognition:** Detects pins, checks, and material imbalances programmatically.

### 4. 🗣️ Tool: OpenAI TTS-1 (The Voice)
*   **Purpose:** Real-time verbal feedback.
*   **Configuration:** Uses the `onyx` model for a deep, robotic, and authoritative tone suitable for a supercomputer persona.
*   **Speed:** Tuned to **1.15x** for dynamic, fluid interaction.

---

## 📦 Data Integration Logic (The "Brain")

When a user makes a move or asks a question via microphone, the system triggers the following **MCP Workflow**:

1.  **Perception:** The board FEN (Forsyth–Edwards Notation) is extracted.
2.  **Tool Execution:**
    *   `tool_engine_analysis(board)` -> Returns Score & Best Move Coordinates.
    *   `tool_get_opening(board)` -> Returns Opening Name.
    *   `analyze_tactics(board)` -> Returns Semantic Threats (e.g., "King is in check").
3.  **Context Construction:** All tool outputs are aggregated into a structured system prompt.
4.  **Reasoning:** The LLM (GPT-4o-mini) processes the telemetry. It is strictly forbidden from inventing moves; it must interpret the tool outputs.
5.  **Response:** The Agent outputs a strategic explanation and an audio file is generated.

---

## ✨ Key Features

### 🛡️ Anti-Hallucination Protocol
Standard LLMs often play illegal moves (e.g., "Bishop to h9"). Deep Blue AI uses a **Coordinate System** (e.g., `e2 -> e4`) validated by the engine. It explicitly lists the material on the board to the LLM at every turn to ensure grounding.

### 🎤 Human Interface (Voice & Chat)
*   **Listen:** Deep Blue speaks every piece of advice.
*   **Speak:** Use the **Microphone** to ask questions like *"Why is my position bad?"* or *"What if I sacrifice my Rook?"*. The Agent will use its tools to verify your idea and answer.

### 💻 Cyberpunk UI
A custom CSS interface designed to mimic a high-tech terminal, featuring:
*   **Tactical Log:** A scrollable history of optimal moves.
*   **Visual Illumination:** Textual highlighting of the recommended move (e.g., `♞ g1 ➔ f3`).
*   **Dynamic Feedback:** Real-time updates on game status (Checkmate celebrations included 🎉).

---

## 🚀 How to Use

1.  **Launch the App:** Wait for the Docker container to build (it installs Stockfish and downloads the DB).
2.  **API Key:**
    *   Enter your **OpenAI API Key** in the right column (or use the system key if provided).
    *   *Note: Your key is used only for this session and is not stored.*
3.  **Play White:** Make your move on the board.
4.  **Listen & Learn:** Deep Blue will analyze your move and dictate the optimal response.
5.  **Interact:** Stuck? Click the **Microphone**, ask a question, and click **"QUERY SYSTEM"**.


---

## 🏆 Hackathon Tracks

We are submitting this project under the following tracks:

*   **🤖 Track 2: MCP in Action (Consumer)**
    *   *Why?* We demonstrate a complete, consumer-facing application where the AI Agent autonomously plans, reasons, and executes tasks using a suite of local MCP tools (Engine, DB, Python Logic).
*   **🔧 Track 1: Building MCP (Consumer)**
    *   *Why?* We built custom tool integrations that bridge raw binary outputs (Stockfish UCI) with semantic LLM understanding, effectively creating "The Chess Toolset" for Agents.
*   **🧠 OpenAI Category Award**
    *   *Why?* Extensive integration of GPT-4o-mini for reasoning and OpenAI TTS-1 for real-time voice interaction.

---

## 🧑‍💻 Credits

*   **Author:** BryanBradfo
*   **Tech Stack:** Hugging Face Spaces (Docker), Gradio, Python-Chess, Stockfish, OpenAI.
*   **Special Thanks:** To the Gradio team for the `gradio_chessboard` component and the Lichess community for the open database.

---

*Note: This project runs in a Docker environment to ensure access to the Stockfish binary and system-level audio dependencies.*