ice-puzzle-mcp

Instructions

Implementation Reference

• src/tools/solver-tools.ts:305-402 (handler)

  Complete implementation of the analyze_difficulty tool including registration, input schema, and handler. The handler analyzes difficulty by checking solvability, move count, mechanics used, direction balance, quadrants visited, dead ends, and calculates estimated difficulty rating (tutorial/easy/medium/hard/expert).

  {
    name: 'analyze_difficulty',
    description: 'Analyze the difficulty and characteristics of the current level',
    inputSchema: {
      type: 'object',
      properties: {}
    },
    handler: async () => {
      const error = checkActiveDraft();
      if (error) {
        return { content: [{ type: 'text', text: error }] };
      }
  
      const draft = draftStore.getCurrentDraft()!;
      const puzzleData = draftStore.exportPuzzleData();
      if (!puzzleData) {
        return { content: [{ type: 'text', text: 'Failed to export puzzle data' }] };
      }
  
      // Solve to get the solution
      const solverResult = solve(puzzleData);
  
      let output = `Difficulty Analysis\n${'='.repeat(50)}\n\n`;
  
      // Solvability
      output += `Solvable: ${solverResult.solvable ? '✓ Yes' : '❌ No'}\n`;
      if (!solverResult.solvable) {
        output += `\nCannot analyze unsolvable level.\n`;
        return { content: [{ type: 'text', text: output }] };
      }
  
      const moves = solverResult.moves!;
      const solution = solverResult.solution!;
  
      // Move count
      output += `Move count: ${moves}\n\n`;
  
      // Mechanics used
      const mechanics = detectMechanics(draft);
      output += `Mechanics used (${mechanics.length}):\n`;
      mechanics.forEach(m => output += `  • ${m}\n`);
      output += `\n`;
  
      // Direction balance
      const directionBalance: Record<Direction, number> = {
        up: 0,
        down: 0,
        left: 0,
        right: 0
      };
      solution.forEach(dir => {
        directionBalance[dir]++;
      });
  
      output += `Direction balance:\n`;
      output += `  Up:    ${directionBalance.up} (${Math.round(directionBalance.up / moves * 100)}%)\n`;
      output += `  Down:  ${directionBalance.down} (${Math.round(directionBalance.down / moves * 100)}%)\n`;
      output += `  Left:  ${directionBalance.left} (${Math.round(directionBalance.left / moves * 100)}%)\n`;
      output += `  Right: ${directionBalance.right} (${Math.round(directionBalance.right / moves * 100)}%)\n`;
      output += `\n`;
  
      // Quadrants visited
      const quadrants = new Set<number>();
      let pos = { ...draft.startPosition };
      quadrants.add(getQuadrant(pos.x, pos.y, draft.gridWidth, draft.gridHeight));
  
      for (const dir of solution) {
        const result = slideWithHazards(pos, dir, puzzleData, [], [], false);
        pos = result.position;
        quadrants.add(getQuadrant(pos.x, pos.y, draft.gridWidth, draft.gridHeight));
      }
  
      output += `Quadrants visited: ${Array.from(quadrants).sort().join(', ')} (${quadrants.size}/4)\n`;
      output += `\n`;
  
      // Dead ends
      const deadEndCount = countDeadEnds(draft, puzzleData);
      output += `Dead ends (3+ blocked directions): ${deadEndCount}\n`;
      output += `\n`;
  
      // Estimated difficulty
      let difficulty: 'tutorial' | 'easy' | 'medium' | 'hard' | 'expert';
      if (moves <= 6) difficulty = 'tutorial';
      else if (moves <= 12) difficulty = 'easy';
      else if (moves <= 17) difficulty = 'medium';
      else if (moves <= 24) difficulty = 'hard';
      else difficulty = 'expert';
  
      // Adjust based on mechanics
      if (mechanics.length >= 3 && difficulty === 'easy') difficulty = 'medium';
      if (mechanics.length >= 4 && difficulty === 'medium') difficulty = 'hard';
  
      output += `Estimated difficulty: ${difficulty.toUpperCase()}\n`;
      output += `  (tutorial: 2-6 moves, easy: 6-12, medium: 10-17, hard: 14-24, expert: 18+)\n`;
  
      return { content: [{ type: 'text', text: output }] };
    }
  }

• src/tools/solver-tools.ts:308-311 (schema)

  Input schema definition for analyze_difficulty tool - empty object since it requires no parameters.

  inputSchema: {
    type: 'object',
    properties: {}
  },

• src/tools/solver-tools.ts:312-401 (handler)

  Core handler logic for analyze_difficulty: runs solver to get optimal solution, calculates metrics (moves, mechanics, directions, quadrants, dead ends), and estimates difficulty level based on move count and mechanics complexity.

  handler: async () => {
    const error = checkActiveDraft();
    if (error) {
      return { content: [{ type: 'text', text: error }] };
    }
  
    const draft = draftStore.getCurrentDraft()!;
    const puzzleData = draftStore.exportPuzzleData();
    if (!puzzleData) {
      return { content: [{ type: 'text', text: 'Failed to export puzzle data' }] };
    }
  
    // Solve to get the solution
    const solverResult = solve(puzzleData);
  
    let output = `Difficulty Analysis\n${'='.repeat(50)}\n\n`;
  
    // Solvability
    output += `Solvable: ${solverResult.solvable ? '✓ Yes' : '❌ No'}\n`;
    if (!solverResult.solvable) {
      output += `\nCannot analyze unsolvable level.\n`;
      return { content: [{ type: 'text', text: output }] };
    }
  
    const moves = solverResult.moves!;
    const solution = solverResult.solution!;
  
    // Move count
    output += `Move count: ${moves}\n\n`;
  
    // Mechanics used
    const mechanics = detectMechanics(draft);
    output += `Mechanics used (${mechanics.length}):\n`;
    mechanics.forEach(m => output += `  • ${m}\n`);
    output += `\n`;
  
    // Direction balance
    const directionBalance: Record<Direction, number> = {
      up: 0,
      down: 0,
      left: 0,
      right: 0
    };
    solution.forEach(dir => {
      directionBalance[dir]++;
    });
  
    output += `Direction balance:\n`;
    output += `  Up:    ${directionBalance.up} (${Math.round(directionBalance.up / moves * 100)}%)\n`;
    output += `  Down:  ${directionBalance.down} (${Math.round(directionBalance.down / moves * 100)}%)\n`;
    output += `  Left:  ${directionBalance.left} (${Math.round(directionBalance.left / moves * 100)}%)\n`;
    output += `  Right: ${directionBalance.right} (${Math.round(directionBalance.right / moves * 100)}%)\n`;
    output += `\n`;
  
    // Quadrants visited
    const quadrants = new Set<number>();
    let pos = { ...draft.startPosition };
    quadrants.add(getQuadrant(pos.x, pos.y, draft.gridWidth, draft.gridHeight));
  
    for (const dir of solution) {
      const result = slideWithHazards(pos, dir, puzzleData, [], [], false);
      pos = result.position;
      quadrants.add(getQuadrant(pos.x, pos.y, draft.gridWidth, draft.gridHeight));
    }
  
    output += `Quadrants visited: ${Array.from(quadrants).sort().join(', ')} (${quadrants.size}/4)\n`;
    output += `\n`;
  
    // Dead ends
    const deadEndCount = countDeadEnds(draft, puzzleData);
    output += `Dead ends (3+ blocked directions): ${deadEndCount}\n`;
    output += `\n`;
  
    // Estimated difficulty
    let difficulty: 'tutorial' | 'easy' | 'medium' | 'hard' | 'expert';
    if (moves <= 6) difficulty = 'tutorial';
    else if (moves <= 12) difficulty = 'easy';
    else if (moves <= 17) difficulty = 'medium';
    else if (moves <= 24) difficulty = 'hard';
    else difficulty = 'expert';
  
    // Adjust based on mechanics
    if (mechanics.length >= 3 && difficulty === 'easy') difficulty = 'medium';
    if (mechanics.length >= 4 && difficulty === 'medium') difficulty = 'hard';
  
    output += `Estimated difficulty: ${difficulty.toUpperCase()}\n`;
    output += `  (tutorial: 2-6 moves, easy: 6-12, medium: 10-17, hard: 14-24, expert: 18+)\n`;
  
    return { content: [{ type: 'text', text: output }] };
  }

• src/tools/solver-tools.ts:22-47 (helper)

  Helper function detectMechanics() - scans the draft for level mechanics including lava, hot_coals, thin_ice, pushable_rocks, warps, and pressure_plate_barrier combinations.

  function detectMechanics(draft: any): string[] {
    const mechanics: string[] = [];
  
    // Check obstacles
    const hasLava = draft.obstacles.some((o: any) => o.type === 'lava');
    const hasHotCoals = draft.obstacles.some((o: any) => o.type === 'hot_coals' || o.type === 'spike');
  
    if (hasLava) mechanics.push('lava');
    if (hasHotCoals) mechanics.push('hot_coals');
  
    // Check special elements
    if (draft.thinIceTiles && draft.thinIceTiles.length > 0) {
      mechanics.push('thin_ice');
    }
    if (draft.pushableRocks && draft.pushableRocks.length > 0) {
      mechanics.push('pushable_rocks');
    }
    if (draft.warpPairs && draft.warpPairs.length > 0) {
      mechanics.push('warps');
    }
    if (draft.pressurePlate && draft.barrier) {
      mechanics.push('pressure_plate_barrier');
    }
  
    return mechanics;
  }

• src/tools/solver-tools.ts:59-91 (helper)

  Helper function countDeadEnds() - counts tiles with 3+ blocked directions to identify dead ends in the puzzle layout.

  function countDeadEnds(draft: any, puzzleData: any): number {
    let deadEndCount = 0;
  
    for (let y = 0; y < draft.gridHeight; y++) {
      for (let x = 0; x < draft.gridWidth; x++) {
        const pos = { x, y };
  
        // Skip if there's an obstacle here
        const hasObstacle = puzzleData.obstacles.some((o: any) => o.x === x && o.y === y);
        if (hasObstacle) continue;
  
        // Count how many directions lead to walls or hazards
        let blockedDirections = 0;
  
        for (const dir of ALL_DIRECTIONS) {
          const result = slideWithHazards(pos, dir, puzzleData, [], [], false);
  
          // Consider blocked if we didn't move or hit something deadly immediately
          if ((result.position.x === x && result.position.y === y) ||
              result.hitLava ||
              (result.hitBarrier && !result.crossedPressurePlate)) {
            blockedDirections++;
          }
        }
  
        if (blockedDirections >= 3) {
          deadEndCount++;
        }
      }
    }
  
    return deadEndCount;
  }