turn-based-game-mcp: Instructions file for GitHub Copilot

Next.js API Routes

Purpose

Patterns for creating API routes in the web package. Covers request handling, game integration, error handling, and security.

File Structure and Naming

• Use Next.js 13+ App Router conventions (route.ts)
• Group related routes by game type: /api/games/[game-type]/
• Use dynamic routes for game instances: /api/games/[game-type]/[id]/
• Include MCP-specific sanitized endpoints: /api/games/[game-type]/mcp/

HTTP Method Handlers

Export named functions for each HTTP method:

import { NextRequest, NextResponse } from 'next/server'

export async function GET() {
  // Handle GET requests
}

export async function POST(request: NextRequest) {
  // Handle POST requests with body
}

export async function DELETE(request: NextRequest) {
  // Handle DELETE requests
}

Request/Response Patterns

Request Handling

• Always use try-catch blocks for error handling
• Parse request bodies with await request.json()
• Extract URL parameters from dynamic routes: { params }: { params: Promise<{ id: string }> }
• Validate required fields and return 400 for missing data

Response Patterns

• Use NextResponse.json() for all responses
• Include appropriate HTTP status codes:
  • 200: Success
  • 400: Bad request (validation errors, invalid moves)
  • 404: Resource not found
  • 500: Server errors
• Return consistent error shapes: { error: 'Error message' }

Game Integration Patterns

Game State Management

• Create game instances at module level: const ticTacToeGame = new TicTacToeGame()
• Use shared game storage functions from @turn-based-mcp/shared
• Always validate moves using game logic before applying
• Update game history with player moves and timestamps

Move Processing Flow

// 1. Validate game exists
const gameSession = await getGameFromStorage(gameId)
if (!gameSession) {
  return NextResponse.json({ error: 'Game not found' }, { status: 404 })
}

// 2. Validate move
if (!gameInstance.validateMove(gameSession.gameState, move, playerId)) {
  return NextResponse.json({ error: 'Invalid move' }, { status: 400 })
}

// 3. Apply move and update state
let updatedGameState = gameInstance.applyMove(gameSession.gameState, move, playerId)

// 4. Add to history
const playerMove = { playerId, move, timestamp: new Date() }
gameSession.history.push(playerMove)

// 5. Check for game end
const gameResult = gameInstance.checkGameEnd(updatedGameState)
if (gameResult) {
  updatedGameState = { ...updatedGameState, status: 'finished', winner: gameResult.winner }
}

// 6. Save and return
gameSession.gameState = updatedGameState
await saveGameToStorage(gameId, gameSession)
return NextResponse.json(gameSession)