@pinepaper.studio/mcp-server 1.4.2 → 1.5.0

package/dist/browser/puppeteer-controller.d.ts

@@ -15,6 +15,32 @@ export interface BrowserControllerConfig {
     viewportHeight?: number;
     /** Timeout for page operations in ms (default: 30000) */
     timeout?: number;
+    /** Enable agent mode with ?agent=1 URL parameter */
+    agentMode?: boolean;
+}
+export interface AgentConnectOptions {
+    /** Run browser in headless mode (default: true for agent workflows) */
+    headless?: boolean;
+    /** Canvas preset to apply (optional) */
+    canvasPreset?: string;
+    /** Custom viewport width */
+    viewportWidth?: number;
+    /** Custom viewport height */
+    viewportHeight?: number;
+}
+export interface BatchExecuteResult {
+    success: boolean;
+    results: Array<{
+        index: number;
+        success: boolean;
+        result?: unknown;
+        itemId?: string;
+        error?: string;
+    }>;
+    itemIds: string[];
+    executionTime: number;
+    error?: string;
+    screenshot?: string;
 }
 export interface ExecuteResult {
     success: boolean;
@@ -35,17 +61,32 @@ export declare class PinePaperBrowserController {
     private page;
     private config;
     private isConnected;
+    private isAgentMode;
+    private connectingPromise;
     constructor(config?: BrowserControllerConfig);
+    /**
+     * Get URL with agent mode parameter
+     */
+    private getAgentUrl;
+    /**
+     * Check if in agent mode
+     */
+    get agentMode(): boolean;
     /**
      * Check if connected to browser
      */
     get connected(): boolean;
     /**
-     * Get current studio URL
+     * Get current studio URL (always includes agent parameters for MCP server)
      */
     get studioUrl(): string;
     /**
-     * Launch browser and navigate to PinePaper Studio
+     * Get the actual URL being used (same as studioUrl since MCP always uses agent mode)
+     */
+    get actualUrl(): string;
+    /**
+     * Launch browser and navigate to PinePaper Studio.
+     * When agentMode is enabled (default), this automatically uses connectAgent().
      */
     connect(): Promise<void>;
     /**
@@ -81,13 +122,56 @@ export declare class PinePaperBrowserController {
      * Check if PinePaper API is available
      */
     checkPinePaperReady(): Promise<boolean>;
+    /**
+     * Connect in agent mode with optimized settings for automation.
+     * Uses headless mode by default and adds ?agent=1 URL parameter.
+     */
+    connectAgent(options?: AgentConnectOptions): Promise<void>;
+    /**
+     * Wait for PinePaper API to be available
+     */
+    private waitForPinePaper;
+    /**
+     * Execute multiple code blocks as a batch for optimal performance.
+     * Combines all code into a single execution context.
+     */
+    executeBatch(codes: string[], options?: {
+        takeScreenshot?: boolean;
+        atomic?: boolean;
+    }): Promise<BatchExecuteResult>;
+    /**
+     * Execute code with a timeout
+     */
+    executeWithTimeout(code: string, timeoutMs: number, takeScreenshot?: boolean): Promise<ExecuteResult>;
+    /**
+     * Quick reset: Clear canvas without full page refresh
+     */
+    quickReset(options?: {
+        preserveBackground?: boolean;
+    }): Promise<ExecuteResult>;
+    /**
+     * Set canvas size from platform preset
+     */
+    setCanvasPreset(preset: string): Promise<ExecuteResult>;
 }
 /**
- * Get or create the global browser controller instance
+ * Get or create the global browser controller instance.
+ *
+ * IMPORTANT: This is a singleton - only ONE browser controller exists.
+ * If a controller already exists, the config parameter is ignored.
+ * Call resetBrowserController() first if you need to change config.
+ *
+ * NOTE: MCP server ALWAYS uses agent mode with ?agent=1&mode=agent URL parameters.
+ * This uses headless browser by default for optimal performance.
  */
 export declare function getBrowserController(config?: BrowserControllerConfig): PinePaperBrowserController;
 /**
- * Reset the global controller (for testing)
+ * Reset the global controller (for testing or when config needs to change).
+ * This will close any existing browser and clear the singleton.
+ */
+export declare function resetBrowserController(): Promise<void>;
+/**
+ * Synchronous reset for testing (fire and forget)
  */
-export declare function resetBrowserController(): void;
+export declare function resetBrowserControllerSync(): void;
 //# sourceMappingURL=puppeteer-controller.d.ts.map

package/dist/browser/puppeteer-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"puppeteer-controller.d.ts","sourceRoot":"","sources":["../../src/browser/puppeteer-controller.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;GAOG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,GAAE,uBAA4B;IAgBhD;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAwD9B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAcjC;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,UAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IA6C9E;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IA6BnD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAIlD;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BlC;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC;CAiB9C;AAQD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,uBAAuB,GAC/B,0BAA0B,CAK5B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAK7C"}
+{"version":3,"file":"puppeteer-controller.d.ts","sourceRoot":"","sources":["../../src/browser/puppeteer-controller.ts"],"names":[],"mappings":"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"}

package/dist/browser/puppeteer-controller.js

@@ -20,19 +20,48 @@ export class PinePaperBrowserController {
     page = null;
     config;
     isConnected = false;
+    isAgentMode = false;
+    connectingPromise = null;
     constructor(config = {}) {
         // Ensure URL points to /editor where the code console and API are available
         let studioUrl = config.studioUrl || 'https://pinepaper.studio';
+        const originalUrl = studioUrl;
         if (!studioUrl.includes('/editor')) {
             studioUrl = studioUrl.replace(/\/$/, '') + '/editor';
         }
+        // MCP server ALWAYS uses agent mode - add agent parameter to URL
+        // This is critical for proper PinePaper agent integration
+        const url = new URL(studioUrl);
+        url.searchParams.set('agent', '1');
+        url.searchParams.set('mode', 'agent');
+        studioUrl = url.toString();
         this.config = {
             studioUrl,
-            headless: config.headless ?? false, // Default to visible browser
+            headless: config.headless ?? false, // Default to visible browser so user can see PinePaper Studio
             viewportWidth: config.viewportWidth || 1280,
             viewportHeight: config.viewportHeight || 800,
             timeout: config.timeout || 30000,
+            agentMode: true, // MCP server always uses agent mode
         };
+        console.error(`[PinePaper] Controller initialized:`);
+        console.error(`[PinePaper]   Original URL: ${originalUrl}`);
+        console.error(`[PinePaper]   Agent URL: ${studioUrl}`);
+        console.error(`[PinePaper]   Headless: ${this.config.headless}`);
+    }
+    /**
+     * Get URL with agent mode parameter
+     */
+    getAgentUrl(baseUrl) {
+        const url = new URL(baseUrl);
+        url.searchParams.set('agent', '1');
+        url.searchParams.set('mode', 'agent');
+        return url.toString();
+    }
+    /**
+     * Check if in agent mode
+     */
+    get agentMode() {
+        return this.isAgentMode;
     }
     /**
      * Check if connected to browser
@@ -41,20 +70,62 @@ export class PinePaperBrowserController {
         return this.isConnected && this.page !== null;
     }
     /**
-     * Get current studio URL
+     * Get current studio URL (always includes agent parameters for MCP server)
      */
     get studioUrl() {
         return this.config.studioUrl;
     }
     /**
-     * Launch browser and navigate to PinePaper Studio
+     * Get the actual URL being used (same as studioUrl since MCP always uses agent mode)
+     */
+    get actualUrl() {
+        return this.config.studioUrl;
+    }
+    /**
+     * Launch browser and navigate to PinePaper Studio.
+     * When agentMode is enabled (default), this automatically uses connectAgent().
      */
     async connect() {
-        if (this.isConnected) {
-            console.error('[PinePaper] Already connected');
-            return;
+        // Prevent concurrent connection attempts (race condition when multiple tools fire at once)
+        if (this.connectingPromise) {
+            console.error('[PinePaper] Connection already in progress, waiting...');
+            return this.connectingPromise;
+        }
+        console.error(`[PinePaper] connect() called - agentMode=${this.config.agentMode}, headless=${this.config.headless}`);
+        // If agent mode is configured, delegate to connectAgent()
+        if (this.config.agentMode) {
+            console.error('[PinePaper] Delegating to connectAgent()');
+            this.connectingPromise = this.connectAgent({ headless: this.config.headless })
+                .finally(() => { this.connectingPromise = null; });
+            return this.connectingPromise;
+        }
+        console.error('[PinePaper] Using standard connect (non-agent mode)');
+        // Check if already connected and page is still valid
+        if (this.isConnected && this.page) {
+            try {
+                // Verify the page is still responsive
+                await this.page.evaluate(() => true);
+                console.error('[PinePaper] Already connected');
+                return;
+            }
+            catch {
+                // Page is stale, need to reconnect
+                console.error('[PinePaper] Existing connection stale, reconnecting...');
+                this.isConnected = false;
+            }
         }
         try {
+            // Clean up any existing browser instance first to prevent multiple windows
+            if (this.browser) {
+                try {
+                    await this.browser.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+                this.browser = null;
+                this.page = null;
+            }
             // Dynamic import to avoid issues when puppeteer isn't installed
             const puppeteer = await import('puppeteer');
             console.error('[PinePaper] Launching browser...');
@@ -66,7 +137,18 @@ export class PinePaperBrowserController {
                     `--window-size=${this.config.viewportWidth},${this.config.viewportHeight}`,
                 ],
             });
-            this.page = await this.browser.newPage();
+            // Get existing pages first, reuse if available (avoid creating multiple tabs)
+            const pages = await this.browser.pages();
+            if (pages.length > 0) {
+                this.page = pages[0];
+                // Close any extra pages that might have been created
+                for (let i = 1; i < pages.length; i++) {
+                    await pages[i].close();
+                }
+            }
+            else {
+                this.page = await this.browser.newPage();
+            }
             await this.page.setViewport({
                 width: this.config.viewportWidth,
                 height: this.config.viewportHeight,
@@ -107,6 +189,7 @@ export class PinePaperBrowserController {
         this.browser = null;
         this.page = null;
         this.isConnected = false;
+        this.connectingPromise = null;
         console.error('[PinePaper] Disconnected from browser');
     }
     /**
@@ -254,24 +337,342 @@ export class PinePaperBrowserController {
             return false;
         }
     }
+    // =============================================================================
+    // AGENT MODE METHODS
+    // =============================================================================
+    /**
+     * Connect in agent mode with optimized settings for automation.
+     * Uses headless mode by default and adds ?agent=1 URL parameter.
+     */
+    async connectAgent(options = {}) {
+        // Check if already connected and page is still valid
+        if (this.isConnected && this.page) {
+            try {
+                // Verify the page is still responsive
+                await this.page.evaluate(() => true);
+                // If already connected but not in agent mode, navigate to agent URL
+                if (!this.isAgentMode) {
+                    const agentUrl = this.getAgentUrl(this.config.studioUrl);
+                    console.error(`[PinePaper] Switching to agent mode: ${agentUrl}`);
+                    await this.page.goto(agentUrl, {
+                        waitUntil: 'networkidle2',
+                        timeout: this.config.timeout,
+                    });
+                    await this.waitForPinePaper();
+                    this.isAgentMode = true;
+                }
+                console.error('[PinePaper] Already connected in agent mode');
+                return;
+            }
+            catch {
+                // Page is stale, need to reconnect
+                console.error('[PinePaper] Existing connection stale, reconnecting...');
+                this.isConnected = false;
+            }
+        }
+        try {
+            // Clean up any existing browser instance first to prevent multiple windows
+            if (this.browser) {
+                try {
+                    await this.browser.close();
+                }
+                catch {
+                    // Ignore close errors
+                }
+                this.browser = null;
+                this.page = null;
+            }
+            // Dynamic import to avoid issues when puppeteer isn't installed
+            const puppeteer = await import('puppeteer');
+            // Agent mode defaults to visible browser so user can see PinePaper Studio
+            const useHeadless = options.headless ?? this.config.headless;
+            const viewportWidth = options.viewportWidth ?? this.config.viewportWidth;
+            const viewportHeight = options.viewportHeight ?? this.config.viewportHeight;
+            console.error(`[PinePaper] Launching browser in agent mode (headless: ${useHeadless})...`);
+            this.browser = await puppeteer.default.launch({
+                headless: useHeadless,
+                args: [
+                    '--no-sandbox',
+                    '--disable-setuid-sandbox',
+                    `--window-size=${viewportWidth},${viewportHeight}`,
+                    // Additional optimization flags for agent mode
+                    '--disable-gpu',
+                    '--disable-dev-shm-usage',
+                    '--disable-extensions',
+                ],
+            });
+            // Get existing pages first, reuse if available (avoid creating multiple tabs)
+            const pages = await this.browser.pages();
+            // Use the first page (about:blank) and close ALL others
+            if (pages.length > 0) {
+                this.page = pages[0];
+                // Close ALL extra pages
+                for (let i = 1; i < pages.length; i++) {
+                    try {
+                        await pages[i].close();
+                    }
+                    catch {
+                        // Ignore close errors
+                    }
+                }
+            }
+            else {
+                this.page = await this.browser.newPage();
+            }
+            await this.page.setViewport({
+                width: viewportWidth,
+                height: viewportHeight,
+            });
+            // Ensure URL has agent parameters (double-check)
+            const targetUrl = this.config.studioUrl.includes('agent=')
+                ? this.config.studioUrl
+                : this.getAgentUrl(this.config.studioUrl);
+            console.error(`[PinePaper] Navigating to agent URL: ${targetUrl}`);
+            // Navigate the existing page to PinePaper (converts about:blank to PinePaper)
+            await this.page.goto(targetUrl, {
+                waitUntil: 'networkidle2',
+                timeout: this.config.timeout,
+            });
+            // Wait for PinePaper to be ready
+            await this.waitForPinePaper();
+            this.isConnected = true;
+            this.isAgentMode = true;
+            console.error('[PinePaper] Connected to PinePaper Studio in agent mode');
+        }
+        catch (error) {
+            await this.disconnect();
+            throw new Error(`Failed to connect in agent mode: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Wait for PinePaper API to be available
+     */
+    async waitForPinePaper() {
+        if (!this.page)
+            return;
+        console.error('[PinePaper] Waiting for PinePaper Studio to initialize...');
+        await this.page.waitForFunction(() => {
+            return (typeof window.app !== 'undefined' ||
+                typeof window.pinepaper !== 'undefined' ||
+                typeof window.paper !== 'undefined');
+        }, { timeout: this.config.timeout });
+    }
+    /**
+     * Execute multiple code blocks as a batch for optimal performance.
+     * Combines all code into a single execution context.
+     */
+    async executeBatch(codes, options = {}) {
+        const startTime = Date.now();
+        if (!this.page || !this.isConnected) {
+            return {
+                success: false,
+                results: [],
+                itemIds: [],
+                executionTime: 0,
+                error: 'Not connected to PinePaper Studio',
+            };
+        }
+        const atomic = options.atomic ?? true;
+        // Wrap all codes in a single IIFE for batch execution
+        const batchCode = `
+(async function() {
+  const _results = [];
+  const _itemIds = [];
+
+  try {
+${codes.map((code, i) => `
+    // === Operation ${i + 1} ===
+    try {
+      const _result${i} = await (async () => {
+        ${code}
+      })();
+      _results.push({ index: ${i}, success: true, result: _result${i} });
+      if (_result${i} && typeof _result${i} === 'object') {
+        if (_result${i}.itemId) _itemIds.push(_result${i}.itemId);
+        if (_result${i}.registryId) _itemIds.push(_result${i}.registryId);
+      }
+    } catch (e) {
+      _results.push({ index: ${i}, success: false, error: e.message });
+      ${atomic ? 'throw e; // Atomic mode: stop on first error' : '// Continue despite error'}
+    }
+`).join('\n')}
+
+    // Save history once for all operations
+    if (app.historyManager) {
+      app.historyManager.saveState();
+    }
+
+    return { success: true, itemIds: _itemIds, results: _results };
+  } catch (e) {
+    return {
+      success: false,
+      error: e.message,
+      itemIds: _itemIds,
+      results: _results
+    };
+  }
+})();
+    `.trim();
+        try {
+            const result = await this.page.evaluate((codeToRun) => {
+                try {
+                    // eslint-disable-next-line no-eval
+                    const evalResult = eval(codeToRun);
+                    if (evalResult instanceof Promise) {
+                        return evalResult;
+                    }
+                    return evalResult;
+                }
+                catch (e) {
+                    return {
+                        success: false,
+                        error: e instanceof Error ? e.message : 'Batch execution error',
+                        results: [],
+                        itemIds: [],
+                    };
+                }
+            }, batchCode);
+            const executionTime = Date.now() - startTime;
+            // Take screenshot if requested
+            let screenshot;
+            if (options.takeScreenshot && result.success) {
+                screenshot = await this.takeScreenshot();
+            }
+            return {
+                success: result.success ?? false,
+                results: result.results ?? [],
+                itemIds: result.itemIds ?? [],
+                executionTime,
+                error: result.error,
+                screenshot,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                results: [],
+                itemIds: [],
+                executionTime: Date.now() - startTime,
+                error: error instanceof Error ? error.message : 'Unknown batch error',
+            };
+        }
+    }
+    /**
+     * Execute code with a timeout
+     */
+    async executeWithTimeout(code, timeoutMs, takeScreenshot = false) {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('Execution timeout')), timeoutMs);
+        });
+        const executePromise = this.executeCode(code, takeScreenshot);
+        try {
+            return await Promise.race([executePromise, timeoutPromise]);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Timeout error',
+            };
+        }
+    }
+    /**
+     * Quick reset: Clear canvas without full page refresh
+     */
+    async quickReset(options = {}) {
+        const resetCode = `
+(function() {
+  // Clear all items
+  if (app.clearCanvas) {
+    app.clearCanvas();
+  } else {
+    if (app.textItemGroup) app.textItemGroup.removeChildren();
+    if (app.patternGroup) app.patternGroup.removeChildren();
+    if (app.itemRegistry) app.itemRegistry.clear();
+    if (app.relationRegistry) app.relationRegistry.clear();
+  }
+
+  ${!options.preserveBackground ? `
+  // Reset background
+  if (app.setBackgroundColor) {
+    app.setBackgroundColor('#1a1a2e');
+  }
+  ` : ''}
+
+  // Save state
+  if (app.historyManager) {
+    app.historyManager.saveState();
+  }
+
+  return { success: true, reset: true };
+})();
+    `.trim();
+        return this.executeCode(resetCode, false);
+    }
+    /**
+     * Set canvas size from platform preset
+     */
+    async setCanvasPreset(preset) {
+        const code = `
+(function() {
+  if (app.setCanvasSize) {
+    app.setCanvasSize('${preset}');
+    return { success: true, preset: '${preset}' };
+  }
+  return { success: false, error: 'setCanvasSize not available' };
+})();
+    `.trim();
+        return this.executeCode(code, false);
+    }
 }
 // =============================================================================
 // SINGLETON INSTANCE
 // =============================================================================
 let globalController = null;
 /**
- * Get or create the global browser controller instance
+ * Get or create the global browser controller instance.
+ *
+ * IMPORTANT: This is a singleton - only ONE browser controller exists.
+ * If a controller already exists, the config parameter is ignored.
+ * Call resetBrowserController() first if you need to change config.
+ *
+ * NOTE: MCP server ALWAYS uses agent mode with ?agent=1&mode=agent URL parameters.
+ * This uses headless browser by default for optimal performance.
  */
 export function getBrowserController(config) {
     if (!globalController) {
-        globalController = new PinePaperBrowserController(config);
+        // MCP server always uses headless by default
+        const mcpConfig = {
+            ...config,
+            headless: config?.headless ?? true,
+        };
+        globalController = new PinePaperBrowserController(mcpConfig);
+    }
+    else if (config) {
+        // Log that config is being ignored since controller already exists
+        console.error('[PinePaper] Browser controller already exists, config parameter ignored. Call resetBrowserController() to create a new controller with different config.');
     }
     return globalController;
 }
 /**
- * Reset the global controller (for testing)
+ * Reset the global controller (for testing or when config needs to change).
+ * This will close any existing browser and clear the singleton.
+ */
+export async function resetBrowserController() {
+    if (globalController) {
+        try {
+            await globalController.disconnect();
+        }
+        catch {
+            // Ignore disconnect errors during reset
+        }
+        globalController = null;
+        console.error('[PinePaper] Browser controller reset');
+    }
+}
+/**
+ * Synchronous reset for testing (fire and forget)
  */
-export function resetBrowserController() {
+export function resetBrowserControllerSync() {
     if (globalController) {
         globalController.disconnect().catch(() => { });
         globalController = null;