undo-mcp

Instructions

Implementation Reference

• src/index.ts:88-103 (handler)

  MCP tool handler for 'checkpoint': validates input (requires files array), invokes ChangeTracker.createCheckpoint, and returns formatted success response with captured files list.

  case "checkpoint": {
    const files = args?.files as string[];
    const description = (args?.description as string) || "Manual checkpoint";
    if (!files || files.length === 0) {
      throw new Error("Files array is required");
    }
    await changeTracker.createCheckpoint(files, description);
    return {
      content: [
        {
          type: "text",
          text: `✅ Checkpoint created: "${description}"\nFiles captured: ${files.length}\n${files.map(f => `  - ${f}`).join('\n')}`,
        },
      ],
    };
  }

• src/index.ts:25-44 (schema)

  JSON Schema definition for the 'checkpoint' tool input, specifying required 'files' array and optional 'description'.

  {
    name: "checkpoint",
    description: "MANDATORY: ALWAYS call this function FIRST before making ANY file modifications, deletions, or creations. This creates a checkpoint to enable undo functionality. This must be called before every single file operation - no exceptions. Never modify files without calling checkpoint first.",
    inputSchema: {
      type: "object",
      properties: {
        files: {
          type: "array",
          items: { type: "string" },
          description: "Array of file paths that will be modified, created, or deleted",
        },
        description: {
          type: "string",
          description: "Concise, action-focused description of the next specific change to be made",
          default: "Manual checkpoint",
        },
      },
      required: ["files"],
    },
  },

• src/index.ts:79-81 (registration)

  Registers the 'checkpoint' tool (via TOOLS array) for MCP ListToolsRequestSchema, making it discoverable by clients.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS,
  }));

• src/changeTracker.ts:14-43 (helper)

  Implements checkpoint logic: iterates files, captures contents of existing ones, tracks potential new files, creates UndoCheckpoint object, and pushes to undoStack.

  async createCheckpoint(files: string[], description: string = "Manual checkpoint"): Promise<void> {
    const fileContents = new Map<string, string>();
    const createdFiles = new Set<string>();
  
    console.error(`[DEBUG] Creating checkpoint: ${description}`);
    console.error(`[DEBUG] Files to checkpoint: ${files.join(', ')}`);
  
    for (const filepath of files) {
      if (!existsSync(filepath)) {
        console.error(`[DEBUG] File will be created: ${filepath}`);
        createdFiles.add(filepath);
      } else {
        const content = readFileSync(filepath, "utf-8");
        fileContents.set(filepath, content);
        console.error(`[DEBUG] Captured content for ${filepath}: ${content.length} characters`);
      }
    }
  
    const checkpoint: UndoCheckpoint = {
      files: fileContents,
      createdFiles,
      timestamp: new Date(),
      description,
    };
  
    this.undoStack.push(checkpoint);
    console.error(`[DEBUG] Checkpoint created. Stack size: ${this.undoStack.length}`);
    console.error(`[DEBUG] Files to be created: ${Array.from(createdFiles).join(', ') || 'none'}`);
    console.error(`[DEBUG] Existing files captured: ${fileContents.size}`);
  }