Spaces:
Build error
Build error
| # **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. | |
| --- |