ice-puzzle-mcp

Instructions

Implementation Reference

• src/tools/special-elements.ts:67-112 (handler)

  The MCP tool handler for 'add_warp_pair' that validates inputs, checks for conflicts with start/goal positions, calls draftStore.addWarpPair(), and returns an ASCII visualization of the updated level.

  handler: async (args: { x1: number; y1: number; x2: number; y2: number }) => {
    const error = checkActiveDraft();
    if (error) {
      return { content: [{ type: 'text', text: error }] };
    }
  
    const draft = draftStore.getCurrentDraft()!;
  
    // Validate both positions
    const error1 = checkPositionValid(args.x1, args.y1, draft.gridWidth, draft.gridHeight);
    if (error1) {
      return { content: [{ type: 'text', text: error1 }] };
    }
  
    const error2 = checkPositionValid(args.x2, args.y2, draft.gridWidth, draft.gridHeight);
    if (error2) {
      return { content: [{ type: 'text', text: error2 }] };
    }
  
    // Check not on start/goal
    if ((args.x1 === draft.startPosition.x && args.y1 === draft.startPosition.y) ||
        (args.x2 === draft.startPosition.x && args.y2 === draft.startPosition.y)) {
      return { content: [{ type: 'text', text: 'Cannot place warp on start position' }] };
    }
  
    if ((args.x1 === draft.goalPosition.x && args.y1 === draft.goalPosition.y) ||
        (args.x2 === draft.goalPosition.x && args.y2 === draft.goalPosition.y)) {
      return { content: [{ type: 'text', text: 'Cannot place warp on goal position' }] };
    }
  
    // Check not same position
    if (args.x1 === args.x2 && args.y1 === args.y2) {
      return { content: [{ type: 'text', text: 'Warp positions must be different' }] };
    }
  
    draftStore.addWarpPair(args.x1, args.y1, args.x2, args.y2);
    const warpId = `warp_${Date.now()}`;
    const result = autoSolveAndVisualize();
  
    return {
      content: [{
        type: 'text',
        text: `Added warp pair ${warpId}: (${args.x1},${args.y1}) ↔ (${args.x2},${args.y2})\n\n${result}`
      }]
    };
  }

• src/store/draft-store.ts:595-617 (handler)

  The core implementation method that creates a warp pair. It clears any existing elements at both positions, generates a unique warp ID, creates the WarpPair object, and updates the draft state with history tracking.

  addWarpPair(x1: number, y1: number, x2: number, y2: number): DraftState {
    if (!this.currentDraft) {
      throw new Error('No current draft');
    }
  
    this.pushHistorySnapshot();
    return this.runWithHistorySuspended(() => {
      this.clearPosition(x1, y1);
      this.clearPosition(x2, y2);
  
      const id = `warp_${this.warpCounter++}`;
      const warpPair: WarpPair = {
        id,
        positions: [
          { x: x1, y: y1 },
          { x: x2, y: y2 },
        ],
      };
  
      const warpPairs = [...this.currentDraft!.warpPairs, warpPair];
      return this.updateDraft({ warpPairs }, { trackHistory: false });
    });
  }

• src/tools/special-elements.ts:54-66 (registration)

  The tool registration block that defines the 'add_warp_pair' tool name, description, and input schema with four required numeric parameters (x1, y1, x2, y2).

  {
    name: 'add_warp_pair',
    description: 'Create a warp pair that teleports the player between two positions',
    inputSchema: {
      type: 'object',
      properties: {
        x1: { type: 'number', description: 'X coordinate of first warp' },
        y1: { type: 'number', description: 'Y coordinate of first warp' },
        x2: { type: 'number', description: 'X coordinate of second warp' },
        y2: { type: 'number', description: 'Y coordinate of second warp' }
      },
      required: ['x1', 'y1', 'x2', 'y2']
    },

• src/core/types.ts:47-50 (schema)

  The TypeScript type definition for WarpPair that defines the structure of a warp pair with an ID and array of positions.

  export interface WarpPair {
    id: string;
    positions: Position[];
  }