# **PRD – Dev A: Server Layer & Runner/Packaging**

---

## 1 • Goal
As Dev A, your goal is to develop the **Server Layer** of the local Node.js application. This involves creating the MCP server, defining the resources and tools for interacting with the Codenames game, and handling communication with the Browser Layer via a defined interface (`ICodenamesBrowser`). You will also contribute to the top-level `runner.ts` script and the project's packaging configuration (`package.json`, `tsconfig.json`).

---

## 2 • Key Technologies (Focus)
- **Node.js** & **npm**
- **`modelcontextprotocol` SDK** (TypeScript)
- **TypeScript**
- Understanding of `npm link` / `npx` for integration and testing

---

## 3 • Responsibilities & Deliverables

| Module / Layer         | Responsibilities                                                                                               | Deliverables                      |
| :--------------------- | :------------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| **Server Layer**       | Node.js MCP server logic:<br>• Initialize MCP SDK<br>• Define MCP resources & tools (e.g., `getBoardState`, `giveClue`)<br>• Handle MCP requests<br>• Call Browser Layer API (`ICodenamesBrowser`) | `server/server.ts`, `server/schemas.ts`, `server/tests/` |
| **Runner & Packaging** | Top-level script & setup contributions:<br>• Implement relevant parts of `runner.ts` (initialize Server Layer, wire to Browser Layer)<br>• **Drive definition** of `ICodenamesBrowser` interface<br>• Configure `package.json` (`name`, `version`, `bin`, `files`, `scripts`)<br>• Configure `tsconfig.json` | Contributions to: `runner.ts`, `package.json`, `tsconfig.json`, `shared/types.ts` |

---

## 4 • Suggested Folder Structure (Focus)

```
spymaster/
├── server/                # <-- Your primary focus
│   ├── server.ts          # <-- MCP logic
│   ├── schemas.ts         # <-- MCP resource/tool schemas
│   └── tests/             # <-- Your unit tests
├── browser/               # <-- Dev B's area (interact via ICodenamesBrowser)
│   └── ...
├── runner.ts              # <-- Collaborate on setup/wiring
├── shared/                # <-- Define ICodenamesBrowser here
│   └── types.ts
├── package.json           # <-- Configure build, link, run
├── tsconfig.json          # <-- Configure TS compilation
├── README.md
└── docs/
    ├── overall_prd.md
    └── dev_a_prd.md       # <-- This document
```

---

## 5 • Architecture & Execution Flow (Your Role)
1.  **Build:** Ensure `npm run build` (using `tsconfig.json` you configure) compiles `server/` and `runner.ts` correctly into `dist/`.
2.  **Linking:** Use `npm link` to make the package executable.
3.  **Execution:** `npx your-package-name` runs `dist/runner.js`.
4.  **Runner (`dist/runner.js`):**
    - Initializes the **Browser Layer** (handled by Dev B, provides `ICodenamesBrowser` instance).
    - You ensure `runner.ts` initializes your **Server Layer**, passing the `ICodenamesBrowser` instance to it.
    - Your Server Layer starts the MCP server.
5.  **Server Layer:** Your code handles incoming MCP requests, translates them into calls to the `ICodenamesBrowser` interface methods provided by the Browser Layer.

---

## 6 • Development Steps (Your Flow)

| Phase                        | Your Actions (Dev A: Server Layer / Build / Runner)                                                                                              | Key Interaction / Synchronization Point                                                                         |
| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **1. Setup, Config & Contract** | Setup `server/`. Configure `package.json`, `tsconfig.json`. **Drive definition** of `ICodenamesBrowser` interface in `shared/types.ts`.           | **Critical Sync:** Agree with Dev B on `ICodenamesBrowser` interface & `package.json` structure (`bin`, `runner.ts`). |
| **2. Independent Implementation** | Implement Server Layer (`server/`) against a **mock** implementation of `ICodenamesBrowser`. Implement `runner.ts` wiring logic. Unit test `server/` logic using the mock. | **None.** Focus on your layer using the defined interface and mock.                               |
| **3. Build, Link & Smoke Test** | Run `npm run build`. Run `npm link`. Run `npx your-package-name` smoke test. Verify your server starts up correctly (even if browser part fails initially). | **Sync Point:** Verify successful build, link, basic `npx` execution. Inform Dev B.                           |
| **4. Integration Test & Debug** | **Lead** E2E testing using MCP Inspector connected to the `npx`-run process. Debug MCP request/response flow and issues related to interaction with the Browser Layer API. | **Sync Point:** Collaborative E2E testing & debugging using `npx`-launched app. You lead, Dev B supports.      |

---

## 7 • Testing Approach (Your Responsibility)
-   **Unit Tests (`server/tests/`):**
    -   Thoroughly test your `server.ts` and `schemas.ts` logic.
    -   **Crucially, mock the `ICodenamesBrowser` interface.** Your unit tests should *not* depend on the actual Playwright implementation. Verify that your server logic correctly calls the mock interface methods based on MCP requests.
-   **E2E & Primary Validation:**
    -   After `npm run build` and `npm link`, you will primarily drive E2E testing.
    -   Run `npx your-package-name`.
    -   Connect MCP Inspector.
    -   Execute MCP commands (`getBoardState`, `giveClue`, `makeGuess`, etc.).
    -   Verify:
        -   Correct MCP responses are generated by your server.
        -   Expected actions occur in the browser (debugging with Dev B if browser actions fail).
        -   Your server correctly handles the data/responses received from the Browser Layer via the `ICodenamesBrowser` interface.

---

## 8 • Key Risks (Focus)
-   **Interface Mismatch:** Your server code expects one thing from `ICodenamesBrowser`, but the Browser Layer implements it differently.
    -   **Mitigation:** Clear TypeScript interface definition (`shared/types.ts`), early integration testing via `npx` run, frequent communication with Dev B.
-   **Build/Link Issues:** Problems with `tsconfig.json`, `package.json` (`bin`, `files`), or `npm link`.
    -   **Mitigation:** Verify build output (`dist/`), check global links (`npm ls -g --depth=0 --link=true`), ensure `runner.ts` compiles correctly and `package.json` points to it.
-   **MCP Logic Errors:** Incorrectly handling MCP requests or formatting responses.
    -   **Mitigation:** Strong unit tests with mocked browser interface, thorough E2E testing with MCP Inspector.

---

## 9 • Acceptance Criteria (Your Contribution)
-   `npm run build` successfully compiles `server/`, `shared/`, and `runner.ts` into `dist/`.
-   `npm link` successfully links the package defined in `package.json`.
-   `npx your-package-name` starts the `runner.ts` script, which successfully initializes and starts your MCP server.
-   MCP Inspector can connect to your server process.
-   MCP Inspector can invoke all defined MCP tools (`getBoardState`, `getTeamTurn`, `getClueLog`, `giveClue`, `makeGuess`, `endTurn`).
-   Your Server Layer correctly processes these requests, calls the appropriate methods on the (mocked or real) `ICodenamesBrowser` interface, and returns accurate responses based on the interface's return values.

---