docs/draft.md

Proposal: Building an MCP Server for Codenames.game

Model Context Protocol (MCP) is a standardized way for AI models to interact with external tools and resources. It defines a common language for requesting actions and receiving information, enabling seamless integration between models and the systems they need to control or query. This proposal outlines how MCP can be used to build an interface for the Codenames.game web application.

1. Define MSP Tools & Resources

• Resources:
  • getBoardState: Returns the 5×5 grid of words, each card's current status (hidden/revealed/color).
  • getTeamTurn: Indicates which team's turn it is.
  • getClueLog: Fetches the history of clues and guesses.
• Tools (Invokable Actions):
  • giveClue(word: string, count: number): Sends a clue as the spymaster.
  • makeGuess(word: string): Tags/reveals a card by its word.
  • endTurn(): Signals the end of the current team's guessing phase.

Definition format follows JSON‑RPC 2.0 methods and params.

---

2. Playwright Integration: Interfacing with the Web Page

Since codenames.game lacks a public API, we will use Playwright to automate browser interactions and bridge the MCP server with the live game interface:

1. MCP Server Controls Playwright:

   • The MCP server launches and manages Chromium browser instances using the Playwright library.
   • For each game session, the server directs Playwright to navigate to the specific game room URL.

2. Executing Actions (MCP Tools):

   • When the MCP server receives a tool call like giveClue, makeGuess, or endTurn, it translates this into a sequence of Playwright commands.
   • These commands target specific DOM elements (buttons, input fields, word cards) identified using selectors (potentially derived from initial Playwright recordings in test-assets). For example, makeGuess('apple') would trigger Playwright commands to find the card element containing "apple" and simulate a click.

3. Retrieving State (MCP Resources):

   • To handle resource requests like getBoardState, getTeamTurn, or getClueLog, the MCP server instructs Playwright to execute JavaScript within the page context or use Playwright's locator functions.
   • Playwright scrapes the necessary information from the DOM (e.g., reading the words on the cards, checking card classes for revealed status, identifying the active team indicator, parsing the clue history log).
   • The scraped data is returned to the MCP server, formatted, and sent back to the MCP client.

4. Headless Operation:

   • Playwright typically runs browsers in headless mode, making it suitable for unattended agents and server-side execution without a visible UI.
   • This allows multiple game instances to run concurrently, each controlled by a separate Playwright browser context managed by the MCP server.

---

3. Authentication & Authorization

• Room URL as "Secret Key": Each private game URL (e.g. codenames.game/abcd1234) acts as the credential, passed to Playwright during navigation.
• MCP Auth Layer: Standard MCP authentication mechanisms can be used if needed, supplementing the room URL approach.
• Role Enforcement: The MCP server can infer the player's role (spymaster vs. guesser) based on the UI state observed via Playwright and enforce which tools (giveClue, makeGuess) are callable accordingly.

---

4. Server Architecture & Deployment

• Node.js + modelcontextprotocol SDK + Playwright:
  • Leverage the official TypeScript MCP SDK for server logic and MCP communication.
  • Integrate the Playwright library (playwright) for browser automation.
• Dockerized Service:
  • One container runs the MCP server application.
  • Playwright dependencies (including browser binaries) must be included in the container image.
• Scaling:
  • Stateless MCP server behind a load-balancer; room-URL→session mapping stored in Redis.
  • Manage a pool of Playwright browser instances/contexts, potentially scaling worker processes based on load.

---

5. Testing & Monitoring

• End‑to‑End Tests: Utilize Playwright itself to write tests simulating full game flows (clue → guess cycles), verifying that MCP server actions correctly manipulate the game UI and that state retrieval accurately reflects the browser state. The existing recordings in test-assets can serve as a basis for these tests.
• Logging & Metrics: Track Playwright action timings, MCP call latencies, browser errors, and scraping success rates.
• Error Handling & Synchronization:
  • Implement robust error handling for Playwright actions (e.g., element not found, navigation timeouts).
  • If discrepancies arise, MCP clients can call getBoardState to force a full state re-scrape via Playwright, ensuring synchronization.

---

Outcome: This MCP server design uses Playwright to treat the Codenames web UI as a "toolkit" accessible via standard MCP methods, enabling any LLM or AI agent to play, spectate, or assist in a Codenames game seamlessly by automating browser interactions.