@portel/photon 1.5.1 → 1.6.1

package/dist/auto-ui/streamable-http-transport.js

@@ -17,7 +17,7 @@
  * @see https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
  */
 import { randomUUID } from 'crypto';
-import { readdir, stat } from 'fs/promises';
+import { readdir, stat, readFile, writeFile } from 'fs/promises';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { PHOTON_VERSION } from '../version.js';
@@ -92,21 +92,19 @@ function configParamToJsonSchema(param) {
     return schema;
 }
 /**
- * Generate configurationSchema for all unconfigured photons
+ * Generate configurationSchema for all photons with constructor params
  * Uses JSON Schema format for rich UI generation
+ * Includes both unconfigured and configured photons (for reconfiguration)
  */
 function generateConfigurationSchema(photons) {
     const schema = {};
     for (const photon of photons) {
-        // Only include unconfigured photons with params
-        if (photon.configured)
-            continue;
-        const unconfigured = photon;
-        if (!unconfigured.requiredParams || unconfigured.requiredParams.length === 0)
+        const params = photon.requiredParams;
+        if (!params || params.length === 0)
             continue;
         const properties = {};
         const required = [];
-        for (const param of unconfigured.requiredParams) {
+        for (const param of params) {
             properties[param.name] = configParamToJsonSchema(param);
             // Mark as required if not optional and no default
             if (!param.isOptional && !param.hasDefault) {
@@ -117,8 +115,11 @@ function generateConfigurationSchema(photons) {
             type: 'object',
             properties,
             required: required.length > 0 ? required : undefined,
-            'x-error-message': unconfigured.errorMessage,
-            'x-internal': unconfigured.internal,
+            'x-error-message': !photon.configured
+                ? photon.errorMessage
+                : undefined,
+            'x-internal': photon.internal,
+            'x-configured': photon.configured || undefined,
         };
     }
     return schema;
@@ -244,6 +245,41 @@ const handlers = {
                 });
             }
         }
+        // Add external MCP tools (from mcpServers in config.json)
+        if (ctx.externalMCPs) {
+            for (const mcp of ctx.externalMCPs) {
+                if (!mcp.connected || !mcp.methods)
+                    continue;
+                for (const method of mcp.methods) {
+                    tools.push({
+                        name: `${mcp.name}/${method.name}`,
+                        description: method.description || `Execute ${method.name}`,
+                        inputSchema: method.params || { type: 'object', properties: {} },
+                        'x-external-mcp': true, // Marker for frontend to identify external MCPs
+                        'x-external-mcp-id': mcp.id,
+                        'x-photon-icon': mcp.icon || '🔌',
+                        'x-photon-description': mcp.description,
+                        'x-photon-prompt-count': mcp.promptCount ?? 0,
+                        'x-photon-resource-count': mcp.resourceCount ?? 0,
+                        'x-has-mcp-app': mcp.hasApp ?? false, // MCP Apps Extension detected
+                        'x-mcp-app-uri': mcp.appResourceUri, // MCP App resource URI (default/first)
+                        'x-mcp-app-uris': mcp.appResourceUris || [], // All MCP App resource URIs
+                        ...buildToolMetadataExtensions(method),
+                        // MCP Apps standard: _meta.ui for linked UI resources and visibility
+                        ...(method.linkedUi || method.visibility
+                            ? {
+                                _meta: {
+                                    ui: {
+                                        ...(method.linkedUi ? { resourceUri: method.linkedUi } : {}),
+                                        ...(method.visibility ? { visibility: method.visibility } : {}),
+                                    },
+                                },
+                            }
+                            : {}),
+                    });
+                }
+            }
+        }
         // Add beam system tools (internal — hidden from sidebar)
         tools.push({
             name: 'beam/configure',
@@ -350,6 +386,70 @@ const handlers = {
                 required: ['photon', 'metadata'],
             },
         });
+        tools.push({
+            name: 'beam/reconnect-mcp',
+            'x-photon-internal': true,
+            description: 'Reconnect a disconnected external MCP server',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'Name of the external MCP to reconnect',
+                    },
+                },
+                required: ['name'],
+            },
+        });
+        tools.push({
+            name: 'beam/studio-read',
+            'x-photon-internal': true,
+            description: 'Read a photon source file for editing in Studio',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'Name of the photon to read',
+                    },
+                },
+                required: ['name'],
+            },
+        });
+        tools.push({
+            name: 'beam/studio-write',
+            'x-photon-internal': true,
+            description: 'Write photon source and trigger hot-reload',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'Name of the photon to write',
+                    },
+                    source: {
+                        type: 'string',
+                        description: 'The new source code',
+                    },
+                },
+                required: ['name', 'source'],
+            },
+        });
+        tools.push({
+            name: 'beam/studio-parse',
+            'x-photon-internal': true,
+            description: 'Parse photon source and return extracted schema',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    source: {
+                        type: 'string',
+                        description: 'Source code to parse',
+                    },
+                },
+                required: ['source'],
+            },
+        });
         // Filter out app-only tools for external (non-Beam) MCP clients
         const visibleTools = session.isBeam
             ? tools
@@ -380,10 +480,22 @@ const handlers = {
         if (name === 'beam/update-metadata') {
             return handleBeamUpdateMetadata(req, ctx, args || {});
         }
+        if (name === 'beam/reconnect-mcp') {
+            return handleBeamReconnectMCP(req, ctx, args || {});
+        }
         if (name === 'beam/photon-help') {
             return handleBeamPhotonHelp(req, ctx, args || {});
         }
-        // Parse tool name: photon-name/method-name
+        if (name === 'beam/studio-read') {
+            return handleBeamStudioRead(req, ctx, args || {});
+        }
+        if (name === 'beam/studio-write') {
+            return handleBeamStudioWrite(req, ctx, args || {});
+        }
+        if (name === 'beam/studio-parse') {
+            return handleBeamStudioParse(req, args || {});
+        }
+        // Parse tool name: server-name/method-name
         const slashIndex = name.indexOf('/');
         if (slashIndex === -1) {
             return {
@@ -395,8 +507,65 @@ const handlers = {
                 },
             };
         }
-        const photonName = name.slice(0, slashIndex);
+        const serverName = name.slice(0, slashIndex);
         const methodName = name.slice(slashIndex + 1);
+        // Check if this is an external MCP tool call
+        // Prefer SDK client for full CallToolResult support (structuredContent)
+        if (ctx.externalMCPSDKClients?.has(serverName)) {
+            const sdkClient = ctx.externalMCPSDKClients.get(serverName);
+            try {
+                // SDK client.callTool returns full CallToolResult with structuredContent
+                const result = await sdkClient.callTool({ name: methodName, arguments: args || {} });
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: result.content,
+                        structuredContent: result.structuredContent,
+                        isError: result.isError ?? false,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [{ type: 'text', text: `Error: ${message}` }],
+                        isError: true,
+                    },
+                };
+            }
+        }
+        // Fallback to wrapper client (no structuredContent support)
+        if (ctx.externalMCPClients?.has(serverName)) {
+            const client = ctx.externalMCPClients.get(serverName);
+            try {
+                const result = await client.call(methodName, args || {});
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        isError: false,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [{ type: 'text', text: `Error: ${message}` }],
+                        isError: true,
+                    },
+                };
+            }
+        }
+        // Handle as photon tool call
+        const photonName = serverName;
         // Find photon info for UI metadata
         const photonInfo = ctx.photons.find((p) => p.name === photonName);
         const methodInfo = photonInfo?.configured
@@ -409,6 +578,23 @@ const handlers = {
         }
         const mcp = ctx.photonMCPs.get(photonName);
         if (!mcp?.instance) {
+            // Check if it's a disconnected external MCP
+            const externalMCP = ctx.externalMCPs?.find((m) => m.name === photonName);
+            if (externalMCP) {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `External MCP "${photonName}" is not connected${externalMCP.errorMessage ? `: ${externalMCP.errorMessage}` : ''}`,
+                            },
+                        ],
+                        isError: true,
+                    },
+                };
+            }
             return {
                 jsonrpc: '2.0',
                 id: req.id,
@@ -573,23 +759,37 @@ const handlers = {
             // Handle async generators (when not using loader)
             if (result && typeof result[Symbol.asyncIterator] === 'function') {
                 const chunks = [];
-                for await (const chunk of result) {
-                    if (chunk.emit === 'result') {
-                        chunks.push(chunk.data);
+                let returnValue = undefined;
+                // Manually iterate to capture both yielded values AND the return value
+                // Note: for-await-of doesn't capture return values, only yielded values
+                const iterator = result[Symbol.asyncIterator]();
+                while (true) {
+                    const { value, done } = await iterator.next();
+                    if (done) {
+                        // Generator returned - capture the return value
+                        returnValue = value;
+                        break;
+                    }
+                    // Process yielded values
+                    if (value?.emit === 'result') {
+                        chunks.push(value.data);
                     }
-                    else if (chunk.emit === 'board-update' && ctx.broadcast) {
+                    else if (value?.emit === 'board-update' && ctx.broadcast) {
                         // Forward board-update from generator
                         ctx.broadcast({
                             type: 'board-update',
                             photon: photonName,
-                            board: chunk.board,
+                            board: value.board,
                         });
                     }
-                    else if (chunk.emit !== 'progress') {
-                        chunks.push(chunk);
+                    else if (value?.emit !== 'progress') {
+                        chunks.push(value);
                     }
                 }
-                const finalResult = chunks.length === 1 ? chunks[0] : chunks;
+                // Use return value if no chunks were yielded, otherwise use chunks
+                const finalResult = chunks.length > 0
+                    ? (chunks.length === 1 ? chunks[0] : chunks)
+                    : returnValue;
                 const genResponse = {
                     jsonrpc: '2.0',
                     id: req.id,
@@ -1106,6 +1306,319 @@ async function handleBeamPhotonHelp(req, ctx, args) {
         };
     }
 }
+/**
+ * Handle beam/reconnect-mcp tool - reconnect a disconnected external MCP
+ */
+async function handleBeamReconnectMCP(req, ctx, args) {
+    const { name: mcpName } = args;
+    if (!mcpName) {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: 'Error: MCP name is required' }],
+                isError: true,
+            },
+        };
+    }
+    if (!ctx.reconnectExternalMCP) {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: 'Error: Reconnection not supported in this context' }],
+                isError: true,
+            },
+        };
+    }
+    try {
+        const result = await ctx.reconnectExternalMCP(mcpName);
+        if (result.success) {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                result: {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Successfully reconnected to external MCP "${mcpName}". Tools list will be updated.`,
+                        },
+                    ],
+                    isError: false,
+                },
+            };
+        }
+        else {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                result: {
+                    content: [{ type: 'text', text: `Failed to reconnect to "${mcpName}": ${result.error}` }],
+                    isError: true,
+                },
+            };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: `Error reconnecting to "${mcpName}": ${message}` }],
+                isError: true,
+            },
+        };
+    }
+}
+/**
+ * Handle beam/studio-read — read a photon source file for editing
+ */
+async function handleBeamStudioRead(req, ctx, args) {
+    const { name: photonName } = args;
+    if (!photonName) {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: 'Error: photon name is required' }],
+                isError: true,
+            },
+        };
+    }
+    // Find the photon by name to get its file path
+    const photon = ctx.photons.find((p) => p.name === photonName);
+    if (!photon || !photon.path) {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: `Error: photon "${photonName}" not found or has no path` }],
+                isError: true,
+            },
+        };
+    }
+    try {
+        const source = await readFile(photon.path, 'utf-8');
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: JSON.stringify({ source, path: photon.path }) }],
+                isError: false,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: `Error reading source: ${message}` }],
+                isError: true,
+            },
+        };
+    }
+}
+/**
+ * Handle beam/studio-write — write photon source and trigger hot-reload
+ */
+async function handleBeamStudioWrite(req, ctx, args) {
+    const { name: photonName, source } = args;
+    if (!photonName || typeof source !== 'string') {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: 'Error: photon name and source are required' }],
+                isError: true,
+            },
+        };
+    }
+    const photon = ctx.photons.find((p) => p.name === photonName);
+    if (!photon || !photon.path) {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: `Error: photon "${photonName}" not found or has no path` }],
+                isError: true,
+            },
+        };
+    }
+    try {
+        // Write source to disk
+        await writeFile(photon.path, source, 'utf-8');
+        // Parse the new source for preview
+        let parseResult = null;
+        try {
+            const { SchemaExtractor } = await import('@portel/photon-core');
+            const extractor = new SchemaExtractor();
+            const { tools: schemas } = extractor.extractAllFromSource(source);
+            const classMatch = source.match(/export\s+default\s+class\s+(\w+)/);
+            const descMatch = source.match(/\/\*\*\s*\n\s*\*\s*(.+)/);
+            const versionMatch = source.match(/@version\s+(\S+)/);
+            const runtimeMatch = source.match(/@runtime\s+(\S+)/);
+            const iconMatch = source.match(/@icon\s+(\S+)/);
+            const statefulMatch = source.match(/@stateful\s+true/);
+            const depsMatch = source.match(/@dependencies\s+(.+)/);
+            const tagsMatch = source.match(/@tags\s+(.+)/);
+            parseResult = {
+                className: classMatch?.[1] || 'Unknown',
+                description: descMatch?.[1]?.replace(/\s*\*\/$/, '').trim(),
+                icon: iconMatch?.[1],
+                version: versionMatch?.[1],
+                runtime: runtimeMatch?.[1],
+                stateful: !!statefulMatch,
+                dependencies: depsMatch?.[1]?.split(',').map((d) => d.trim()).filter(Boolean),
+                tags: tagsMatch?.[1]?.split(',').map((t) => t.trim()).filter(Boolean),
+                methods: schemas
+                    .filter((s) => !['onInitialize', 'onShutdown', 'constructor'].includes(s.name))
+                    .map((s) => ({
+                    name: s.name,
+                    description: s.description,
+                    icon: s.icon,
+                    params: s.inputSchema,
+                    autorun: s.autorun,
+                    outputFormat: s.outputFormat,
+                    buttonLabel: s.buttonLabel,
+                    webhook: s.webhook,
+                    scheduled: s.scheduled || s.cron,
+                    locked: s.locked,
+                })),
+            };
+        }
+        catch {
+            // Parse is best-effort — don't fail the write
+        }
+        // Trigger hot-reload if available
+        if (ctx.reloadPhoton) {
+            try {
+                const reloadResult = await ctx.reloadPhoton(photonName);
+                if (reloadResult.success) {
+                    broadcastToBeam('beam/hot-reload', { photon: reloadResult.photon });
+                }
+            }
+            catch {
+                // Reload failure doesn't fail the write
+            }
+        }
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, parseResult }),
+                    },
+                ],
+                isError: false,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }) }],
+                isError: true,
+            },
+        };
+    }
+}
+/**
+ * Handle beam/studio-parse — parse photon source and return schema
+ */
+async function handleBeamStudioParse(req, args) {
+    const { source } = args;
+    if (typeof source !== 'string') {
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: 'Error: source is required' }],
+                isError: true,
+            },
+        };
+    }
+    try {
+        const { SchemaExtractor } = await import('@portel/photon-core');
+        const extractor = new SchemaExtractor();
+        const { tools: schemas } = extractor.extractAllFromSource(source);
+        const classMatch = source.match(/export\s+default\s+class\s+(\w+)/);
+        const descMatch = source.match(/\/\*\*\s*\n\s*\*\s*(.+)/);
+        const versionMatch = source.match(/@version\s+(\S+)/);
+        const runtimeMatch = source.match(/@runtime\s+(\S+)/);
+        const iconMatch = source.match(/@icon\s+(\S+)/);
+        const statefulMatch = source.match(/@stateful\s+true/);
+        const depsMatch = source.match(/@dependencies\s+(.+)/);
+        const tagsMatch = source.match(/@tags\s+(.+)/);
+        const errors = [];
+        const warnings = [];
+        if (!classMatch)
+            errors.push('No default export class found');
+        if (!descMatch)
+            warnings.push('Missing class description (first line in JSDoc)');
+        const result = {
+            className: classMatch?.[1] || 'Unknown',
+            description: descMatch?.[1]?.replace(/\s*\*\/$/, '').trim(),
+            icon: iconMatch?.[1],
+            version: versionMatch?.[1],
+            runtime: runtimeMatch?.[1],
+            stateful: !!statefulMatch,
+            dependencies: depsMatch?.[1]?.split(',').map((d) => d.trim()).filter(Boolean),
+            tags: tagsMatch?.[1]?.split(',').map((t) => t.trim()).filter(Boolean),
+            methods: schemas
+                .filter((s) => !['onInitialize', 'onShutdown', 'constructor'].includes(s.name))
+                .map((s) => ({
+                name: s.name,
+                description: s.description,
+                icon: s.icon,
+                params: s.inputSchema,
+                autorun: s.autorun,
+                outputFormat: s.outputFormat,
+                buttonLabel: s.buttonLabel,
+                webhook: s.webhook,
+                scheduled: s.scheduled || s.cron,
+                locked: s.locked,
+            })),
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                isError: false,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            className: 'Unknown',
+                            methods: [],
+                            errors: [`Parse error: ${message}`],
+                        }),
+                    },
+                ],
+                isError: false,
+            },
+        };
+    }
+}
 /**
  * Handle MCP Streamable HTTP requests
  */
@@ -1188,6 +1701,10 @@ export async function handleStreamableHTTP(req, res, options) {
         const context = {
             photons: options.photons,
             photonMCPs: options.photonMCPs,
+            externalMCPs: options.externalMCPs,
+            externalMCPClients: options.externalMCPClients,
+            externalMCPSDKClients: options.externalMCPSDKClients,
+            reconnectExternalMCP: options.reconnectExternalMCP,
             loadUIAsset: options.loadUIAsset,
             configurePhoton: options.configurePhoton,
             reloadPhoton: options.reloadPhoton,
@@ -1311,4 +1828,48 @@ export function sendToSession(sessionId, method, params) {
     session.sseResponse.write(`data: ${JSON.stringify(notification)}\n\n`);
     return true;
 }
+/**
+ * Request elicitation from the frontend for an external MCP.
+ * This is used when external MCP servers send elicitation/create requests.
+ *
+ * @param mcpName - Name of the external MCP requesting elicitation
+ * @param request - The elicitation request params from the MCP server
+ * @returns Promise resolving to the user's response
+ */
+export function requestExternalElicitation(mcpName, request) {
+    const elicitationId = randomUUID();
+    return new Promise((resolve, reject) => {
+        // Store pending elicitation
+        pendingElicitations.set(elicitationId, {
+            resolve: (value) => {
+                resolve({ action: 'accept', content: value });
+            },
+            reject: (error) => {
+                if (error.message.includes('cancelled')) {
+                    resolve({ action: 'cancel' });
+                }
+                else {
+                    resolve({ action: 'decline' });
+                }
+            },
+            sessionId: '', // External MCP elicitations aren't tied to a specific session
+        });
+        // Broadcast elicitation request to all Beam clients
+        broadcastToBeam('beam/elicitation', {
+            elicitationId,
+            mcpName,
+            message: request.message,
+            mode: request.mode,
+            schema: request.requestedSchema,
+            url: request.url,
+        });
+        // Timeout after 5 minutes
+        setTimeout(() => {
+            if (pendingElicitations.has(elicitationId)) {
+                pendingElicitations.delete(elicitationId);
+                resolve({ action: 'cancel' });
+            }
+        }, 300000);
+    });
+}
 //# sourceMappingURL=streamable-http-transport.js.map