docs/dev_a_prd.md

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: • Initialize MCP SDK • Define MCP resources & tools (e.g., getBoardState, giveClue) • Handle MCP requests • Call Browser Layer API (ICodenamesBrowser)	server/server.ts, server/schemas.ts, server/tests/
Runner & Packaging	Top-level script & setup contributions: • Implement relevant parts of runner.ts (initialize Server Layer, wire to Browser Layer) • Drive definition of ICodenamesBrowser interface • Configure package.json (name, version, bin, files, scripts) • 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.

---