@portel/photon 1.5.1 → 1.6.1

package/dist/server.js

@@ -125,6 +125,12 @@ export class PhotonServer {
             // Before initialization or no capabilities - assume legacy Photon
             return 'photon';
         }
+        // Check for MCP Apps extension (io.modelcontextprotocol/ui)
+        // Claude Desktop and other MCP Apps clients use this format
+        const extensions = capabilities.extensions;
+        if (extensions?.['io.modelcontextprotocol/ui']) {
+            return 'sep-1865';
+        }
         // Check for SEP-1865 UI capability
         // SEP-1865 clients advertise: { experimental: { ui: {} } } or { ui: {} }
         const experimental = capabilities.experimental;
@@ -179,13 +185,22 @@ export class PhotonServer {
         }
     }
     /**
-     * Get UI mimeType based on detected format
+     * Get UI mimeType based on detected format and client capabilities
      *
      * @param server - Optional server instance (for SSE sessions)
      */
     getUIMimeType(server) {
+        const targetServer = server || this.server;
+        const capabilities = targetServer.getClientCapabilities();
+        // Check for MCP Apps extension with declared mimeTypes
+        // Claude Desktop uses: { extensions: { "io.modelcontextprotocol/ui": { mimeTypes: ["text/html;profile=mcp-app"] } } }
+        const extensions = capabilities?.extensions;
+        const mcpUI = extensions?.['io.modelcontextprotocol/ui'];
+        if (mcpUI?.mimeTypes?.[0]) {
+            return mcpUI.mimeTypes[0];
+        }
         const format = this.getUIFormat(server);
-        return format === 'sep-1865' ? 'text/html+mcp' : 'text/html';
+        return format === 'sep-1865' ? 'text/html;profile=mcp-app' : 'text/html';
     }
     /**
      * Check if client supports elicitation
@@ -210,7 +225,12 @@ export class PhotonServer {
      */
     createMCPInputProvider(server) {
         const targetServer = server || this.server;
+        const capabilities = targetServer.getClientCapabilities();
         const supportsElicitation = this.clientSupportsElicitation(server);
+        this.log('debug', 'Creating MCP input provider', {
+            supportsElicitation,
+            capabilities: JSON.stringify(capabilities),
+        });
         return async (ask) => {
             // If client doesn't support elicitation, fall back to logging the ask
             // (MCP servers can't use readline - they communicate via protocol)
@@ -1107,19 +1127,31 @@ export class PhotonServer {
     }
     /**
      * Handle incoming channel messages and forward as MCP notifications
+     * This enables cross-client real-time updates (e.g., Beam updates show in Claude Desktop)
+     *
+     * Uses standard MCP Apps notification with embedded _photon data:
+     * - Claude Desktop forwards standard notifications (ui/notifications/host-context-changed)
+     * - Photon bridge extracts _photon field and routes to event listeners
+     * - This ensures cross-client sync works without requiring custom protocol support
      */
     async handleChannelMessage(message) {
         if (!message || typeof message !== 'object')
             return;
         const msg = message;
-        // Format message for display
-        const displayMessage = msg.event
-            ? `[${msg.event}] ${JSON.stringify(msg.data || {})}`
-            : JSON.stringify(msg);
-        // Forward as MCP status notification to all connected clients
+        // Use STANDARD notification with embedded photon data
+        // Claude Desktop will forward this (it's a standard notification)
+        // Our bridge extracts _photon and routes to the appropriate event handler
         const payload = {
-            method: 'notifications/status',
-            params: { type: 'info', message: displayMessage },
+            method: 'ui/notifications/host-context-changed',
+            params: {
+                // _photon field carries our custom event data
+                _photon: {
+                    photon: this.daemonName,
+                    channel: msg.channel,
+                    event: msg.event,
+                    data: msg.data,
+                },
+            },
         };
         try {
             await this.server.notification(payload);
@@ -1727,10 +1759,346 @@ export class PhotonServer {
         if (!ui || !ui.resolvedPath) {
             throw new Error(`UI asset not found: ${uri}`);
         }
-        const content = await fs.readFile(ui.resolvedPath, 'utf-8');
+        let content = await fs.readFile(ui.resolvedPath, 'utf-8');
+        // Inject MCP Apps bridge script for Claude Desktop compatibility
+        const bridgeScript = this.generateMcpAppsBridge();
+        content = content.replace('<head>', `<head>\n${bridgeScript}`);
         return {
-            contents: [{ uri, mimeType: ui.mimeType || 'text/html+mcp', text: content }],
+            contents: [{ uri, mimeType: ui.mimeType || 'text/html;profile=mcp-app', text: content }],
+        };
+    }
+    /**
+     * Generate minimal MCP Apps bridge script for Claude Desktop compatibility
+     * This handles the ui/initialize handshake and tool result delivery
+     */
+    generateMcpAppsBridge() {
+        const photonName = this.mcp?.name || 'photon-app';
+        const injectedPhotons = this.mcp?.injectedPhotons || [];
+        return `<script>
+(function() {
+  'use strict';
+  var pendingCalls = {};
+  var callIdCounter = 0;
+  var toolResult = null;
+  var resultListeners = [];
+  var emitListeners = [];
+  var themeListeners = [];
+  var eventListeners = {};  // For specific event subscriptions (e.g., 'taskMove')
+  var photonEventListeners = {};  // Namespaced by photon name for injected photons
+  var currentTheme = 'dark';
+  var injectedPhotons = ${JSON.stringify(injectedPhotons)};
+
+  function generateCallId() {
+    return 'call_' + (++callIdCounter) + '_' + Math.random().toString(36).slice(2);
+  }
+
+  function postToHost(msg) {
+    window.parent.postMessage(msg, '*');
+  }
+
+  // Listen for messages from host
+  window.addEventListener('message', function(e) {
+    var m = e.data;
+    if (!m || typeof m !== 'object') return;
+
+    // Handle JSON-RPC messages
+    if (m.jsonrpc === '2.0') {
+      // Response to our request (has id, no method)
+      if (m.id && !m.method && pendingCalls[m.id]) {
+        var pending = pendingCalls[m.id];
+        delete pendingCalls[m.id];
+        if (m.error) {
+          pending.reject(new Error(m.error.message));
+        } else {
+          // Extract clean data from MCP result format
+          var result = m.result;
+          var cleanData = result;
+          if (result && result.structuredContent) {
+            cleanData = result.structuredContent;
+          } else if (result && result.content && Array.isArray(result.content)) {
+            var textItem = result.content.find(function(i) { return i.type === 'text'; });
+            if (textItem && textItem.text) {
+              try { cleanData = JSON.parse(textItem.text); } catch(e) { cleanData = textItem.text; }
+            }
+          }
+          pending.resolve(cleanData);
+        }
+        return;
+      }
+
+      // Tool result notification
+      if (m.method === 'ui/notifications/tool-result') {
+        var result = m.params;
+        // Extract data from MCP result format
+        if (result.structuredContent) {
+          toolResult = result.structuredContent;
+        } else if (result.content && Array.isArray(result.content)) {
+          var textItem = result.content.find(function(i) { return i.type === 'text'; });
+          if (textItem && textItem.text) {
+            try { toolResult = JSON.parse(textItem.text); } catch(e) { toolResult = textItem.text; }
+          }
+        } else {
+          toolResult = result;
+        }
+        // Set __PHOTON_DATA__ for UIs that read it at init
+        window.__PHOTON_DATA__ = toolResult;
+        // Dispatch event for UIs to re-initialize with new data
+        window.dispatchEvent(new CustomEvent('photon:data-ready', { detail: toolResult }));
+        resultListeners.forEach(function(cb) { cb(toolResult); });
+      }
+
+      // Host context changed (theme + embedded photon events)
+      if (m.method === 'ui/notifications/host-context-changed') {
+        // Standard theme handling
+        if (m.params && m.params.theme) {
+          currentTheme = m.params.theme;
+          document.documentElement.classList.remove('light', 'dark');
+          document.documentElement.classList.add(m.params.theme);
+          document.documentElement.setAttribute('data-theme', m.params.theme);
+          themeListeners.forEach(function(cb) { cb(currentTheme); });
+        }
+
+        // Extract embedded photon event data
+        // This enables real-time sync via standard MCP protocol
+        if (m.params && m.params._photon) {
+          var photonData = m.params._photon;
+          // Route to generic emit listeners
+          emitListeners.forEach(function(cb) { cb(photonData); });
+
+          var eventName = photonData.event;
+          var sourcePhoton = photonData.data && photonData.data._source;
+
+          // Route to photon-specific listeners if _source is specified (injected photon events)
+          if (sourcePhoton && photonEventListeners[sourcePhoton] && photonEventListeners[sourcePhoton][eventName]) {
+            photonEventListeners[sourcePhoton][eventName].forEach(function(cb) {
+              cb(photonData.data);
+            });
+          }
+
+          // Also route to global event listeners (main photon events, or fallback)
+          if (eventName && eventListeners[eventName]) {
+            eventListeners[eventName].forEach(function(cb) {
+              cb(photonData.data);
+            });
+          }
+        }
+      }
+    }
+  });
+
+  // Mark that we're in MCP Apps context (not Beam)
+  window.__MCP_APPS_CONTEXT__ = true;
+
+  // Expose photon bridge API
+  window.photon = {
+    get toolOutput() { return toolResult; },
+    onResult: function(cb) {
+      resultListeners.push(cb);
+      if (toolResult) cb(toolResult);
+      return function() {
+        var i = resultListeners.indexOf(cb);
+        if (i >= 0) resultListeners.splice(i, 1);
+      };
+    },
+    callTool: function(name, args) {
+      var callId = generateCallId();
+      return new Promise(function(resolve, reject) {
+        pendingCalls[callId] = { resolve: resolve, reject: reject };
+        postToHost({
+          jsonrpc: '2.0',
+          id: callId,
+          method: 'tools/call',
+          params: { name: name, arguments: args || {} }
+        });
+        setTimeout(function() {
+          if (pendingCalls[callId]) {
+            delete pendingCalls[callId];
+            reject(new Error('Tool call timeout'));
+          }
+        }, 30000);
+      });
+    },
+    invoke: function(name, args) { return window.photon.callTool(name, args); },
+    onEmit: function(cb) {
+      emitListeners.push(cb);
+      return function() {
+        var i = emitListeners.indexOf(cb);
+        if (i >= 0) emitListeners.splice(i, 1);
+      };
+    },
+    onThemeChange: function(cb) {
+      themeListeners.push(cb);
+      // Call immediately with current theme
+      cb(currentTheme);
+      return function() {
+        var i = themeListeners.indexOf(cb);
+        if (i >= 0) themeListeners.splice(i, 1);
+      };
+    },
+    get theme() { return currentTheme; },
+
+    // Generic event subscription for real-time sync
+    // Usage: photon.on('taskMove', function(data) { ... })
+    on: function(eventName, cb) {
+      if (!eventListeners[eventName]) eventListeners[eventName] = [];
+      eventListeners[eventName].push(cb);
+      return function() {
+        var i = eventListeners[eventName].indexOf(cb);
+        if (i >= 0) eventListeners[eventName].splice(i, 1);
+      };
+    },
+
+    // Photon-specific event subscription (for injected photon events)
+    // Usage: photon.onPhoton('notifications', 'alertCreated', function(data) { ... })
+    onPhoton: function(photonName, eventName, cb) {
+      if (!photonEventListeners[photonName]) photonEventListeners[photonName] = {};
+      if (!photonEventListeners[photonName][eventName]) photonEventListeners[photonName][eventName] = [];
+      photonEventListeners[photonName][eventName].push(cb);
+      return function() {
+        var i = photonEventListeners[photonName][eventName].indexOf(cb);
+        if (i >= 0) photonEventListeners[photonName][eventName].splice(i, 1);
+      };
+    }
+  };
+
+  // Create direct window object: window.{photonName}
+  // This provides a clean class-like API that mirrors server methods:
+  //   Server: this.emit('taskMove', data)
+  //   Client: kanban.onTaskMove(cb) - subscribe to events
+  //   Client: kanban.taskMove(args) - call server method
+  var photonName = '${photonName}';
+  window[photonName] = new Proxy({}, {
+    get: function(target, prop) {
+      if (typeof prop !== 'string') return undefined;
+
+      // onEventName -> subscribe to 'eventName' event
+      // e.g., onTaskMove -> subscribe to 'taskMove'
+      if (prop.startsWith('on') && prop.length > 2) {
+        var eventName = prop.charAt(2).toLowerCase() + prop.slice(3);
+        return function(cb) {
+          return window.photon.on(eventName, cb);
         };
+      }
+
+      // methodName -> call server tool
+      // e.g., taskMove(args) -> photon.callTool('taskMove', args)
+      return function(args) {
+        return window.photon.callTool(prop, args);
+      };
+    }
+  });
+
+  // Create proxies for injected photons (for event subscriptions)
+  // e.g., notifications.onAlertCreated(cb) subscribes to 'alertCreated' from 'notifications' photon
+  injectedPhotons.forEach(function(injectedName) {
+    window[injectedName] = new Proxy({}, {
+      get: function(target, prop) {
+        if (typeof prop !== 'string') return undefined;
+
+        // onEventName -> subscribe to photon-specific event
+        if (prop.startsWith('on') && prop.length > 2) {
+          var eventName = prop.charAt(2).toLowerCase() + prop.slice(3);
+          return function(cb) {
+            return window.photon.onPhoton(injectedName, eventName, cb);
+          };
+        }
+
+        // Method calls on injected photons are not supported from client
+        // (injected photon methods are only available server-side)
+        return undefined;
+      }
+    });
+  });
+
+  // Size notification helper
+  function sendSizeChanged() {
+    var body = document.body;
+    var root = document.documentElement;
+
+    // Calculate actual content dimensions
+    var width = Math.max(
+      body.scrollWidth,
+      body.offsetWidth,
+      root.clientWidth,
+      root.scrollWidth,
+      root.offsetWidth
+    );
+    var height = Math.max(
+      body.scrollHeight,
+      body.offsetHeight,
+      root.clientHeight,
+      root.scrollHeight,
+      root.offsetHeight
+    );
+
+    // Check for scrollable containers with overflow:hidden that hide true content size
+    var containers = document.querySelectorAll('.board, [style*="overflow"]');
+    containers.forEach(function(el) {
+      if (el.scrollWidth > width) width = el.scrollWidth;
+      if (el.scrollHeight > height) height = el.scrollHeight;
+    });
+
+    // For kanban-style boards, calculate from column count
+    var columns = document.querySelectorAll('.column');
+    if (columns.length > 0) {
+      var columnWidth = 220; // min-width + gap
+      var boardPadding = 48;
+      var neededWidth = (columns.length * columnWidth) + boardPadding;
+      if (neededWidth > width) width = neededWidth;
+    }
+
+    // Reasonable minimums, maximums, and padding
+    width = Math.max(width, 600) + 32;
+    // Force minimum height for kanban-style boards
+    // header(120) + column headers(50) + 3-4 cards(450) = 620
+    if (columns.length > 0) {
+      height = Math.max(height, 620);
+    } else {
+      height = Math.max(height, 400);
+    }
+
+    postToHost({
+      jsonrpc: '2.0',
+      method: 'ui/notifications/size-changed',
+      params: { width: width, height: height }
+    });
+  }
+
+  // MCP Apps handshake: send ui/initialize and wait for response
+  var initId = generateCallId();
+  pendingCalls[initId] = {
+    resolve: function(result) {
+      // Apply theme from host context
+      if (result.hostContext && result.hostContext.theme) {
+        document.documentElement.classList.add(result.hostContext.theme);
+        document.documentElement.setAttribute('data-theme', result.hostContext.theme);
+      }
+      // Complete handshake
+      postToHost({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} });
+
+      // Set up size notifications after handshake
+      setTimeout(sendSizeChanged, 100);
+      var resizeObserver = new ResizeObserver(function() {
+        sendSizeChanged();
+      });
+      resizeObserver.observe(document.documentElement);
+      resizeObserver.observe(document.body);
+    },
+    reject: function(err) { console.error('MCP Apps init failed:', err); }
+  };
+
+  postToHost({
+    jsonrpc: '2.0',
+    id: initId,
+    method: 'ui/initialize',
+    params: {
+      appInfo: { name: '${photonName}', version: '1.0.0' },
+      appCapabilities: {},
+      protocolVersion: '2026-01-26'
+    }
+  });
+})();
+</script>`;
     }
     /**
      * Handle legacy photon:// asset read
@@ -1743,7 +2111,7 @@ export class PhotonServer {
             const ui = this.mcp.assets.ui.find((u) => u.id === assetId);
             if (ui) {
                 resolvedPath = ui.resolvedPath;
-                mimeType = ui.mimeType || 'text/html';
+                mimeType = ui.mimeType || 'text/html;profile=mcp-app';
             }
         }
         else if (assetType === 'prompts') {
@@ -1761,7 +2129,12 @@ export class PhotonServer {
             }
         }
         if (resolvedPath) {
-            const content = await fs.readFile(resolvedPath, 'utf-8');
+            let content = await fs.readFile(resolvedPath, 'utf-8');
+            // Inject MCP Apps bridge for UI assets
+            if (assetType === 'ui') {
+                const bridgeScript = this.generateMcpAppsBridge();
+                content = content.replace('<head>', `<head>\n${bridgeScript}`);
+            }
             return {
                 contents: [{ uri, mimeType, text: content }],
             };