Spaces:
Sleeping
Sleeping
| 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.* |