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