@portel/photon 1.5.1 → 1.6.1

package/dist/auto-ui/beam.js

@@ -6,6 +6,7 @@
  * Version: 2.0.0 (SSE Architecture)
  */
 import * as http from 'http';
+import * as net from 'net';
 import * as fs from 'fs/promises';
 import { existsSync, lstatSync, realpathSync, watch } from 'fs';
 import * as path from 'path';
@@ -34,10 +35,378 @@ import { TemplateManager } from '../template-manager.js';
 import { subscribeChannel, pingDaemon } from '../daemon/client.js';
 import { SchemaExtractor, } from '@portel/photon-core';
 import { generateOpenAPISpec } from './openapi-generator.js';
-import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, sendToSession, } from './streamable-http-transport.js';
+import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, sendToSession, requestExternalElicitation, } from './streamable-http-transport.js';
+import { SDKMCPClientFactory } from '../mcp-client.js';
 import { getBundledPhotonPath, BEAM_BUNDLED_PHOTONS } from '../shared-utils.js';
+// SDK imports for direct resource access (transport wrapper doesn't expose these yet)
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 // Config file path
 const CONFIG_FILE = path.join(os.homedir(), '.photon', 'config.json');
+// ════════════════════════════════════════════════════════════════════════════════
+// EXTERNAL MCP STATE (module-level for MCP transport access)
+// ════════════════════════════════════════════════════════════════════════════════
+/** External MCP servers loaded from config */
+const externalMCPs = [];
+/** Active MCP client instances for external MCPs */
+const externalMCPClients = new Map();
+/** Direct SDK clients for resource access (listResources, readResource) */
+const externalMCPSDKClients = new Map();
+/**
+ * Generate a unique ID for an external MCP based on its name
+ */
+function generateExternalMCPId(name) {
+    return createHash('sha256').update(`external:${name}`).digest('hex').slice(0, 12);
+}
+/**
+ * Convert a tool name to a display label
+ */
+function prettifyToolName(name) {
+    return name
+        .split(/[-_]/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Create an HTTP transport for a URL-based MCP.
+ * Tries Streamable HTTP first; falls back to legacy SSE.
+ */
+async function connectHTTPClient(url, mcpName) {
+    const sdkClient = new Client({ name: 'beam-mcp-client', version: '1.0.0' }, {
+        capabilities: {
+            elicitation: {}, // Declare elicitation support
+            experimental: {
+                ui: {}, // Request SEP-1865 format for MCP Apps
+            },
+        },
+    });
+    // Set up elicitation handler
+    sdkClient.setRequestHandler(ElicitRequestSchema, async (request) => {
+        const params = request.params;
+        const result = await requestExternalElicitation(mcpName, {
+            mode: params.mode,
+            message: params.message,
+            requestedSchema: params.requestedSchema,
+            url: params.url,
+        });
+        return result;
+    });
+    try {
+        const transport = new StreamableHTTPClientTransport(new URL(url));
+        const connectPromise = sdkClient.connect(transport);
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
+        await Promise.race([connectPromise, timeoutPromise]);
+        logger.debug(`Connected to ${url} via Streamable HTTP`);
+        return sdkClient;
+    }
+    catch (streamableError) {
+        logger.debug(`Streamable HTTP failed for ${url}, trying legacy SSE: ${streamableError}`);
+    }
+    // Fallback: legacy SSE transport
+    const sseClient = new Client({ name: 'beam-mcp-client', version: '1.0.0' }, {
+        capabilities: {
+            elicitation: {}, // Declare elicitation support
+            experimental: {
+                ui: {}, // Request SEP-1865 format for MCP Apps
+            },
+        },
+    });
+    // Set up elicitation handler for SSE client too
+    sseClient.setRequestHandler(ElicitRequestSchema, async (request) => {
+        const params = request.params;
+        const result = await requestExternalElicitation(mcpName, {
+            mode: params.mode,
+            message: params.message,
+            requestedSchema: params.requestedSchema,
+            url: params.url,
+        });
+        return result;
+    });
+    const sseTransport = new SSEClientTransport(new URL(url));
+    const connectPromise = sseClient.connect(sseTransport);
+    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
+    await Promise.race([connectPromise, timeoutPromise]);
+    logger.debug(`Connected to ${url} via legacy SSE`);
+    return sseClient;
+}
+/**
+ * Load external MCPs from config.json mcpServers section
+ *
+ * @param config - The PhotonConfig with mcpServers section
+ * @returns Array of ExternalMCPInfo objects (populated with connected status)
+ */
+async function loadExternalMCPs(config) {
+    const mcpServers = config.mcpServers || {};
+    const results = [];
+    for (const [name, serverConfig] of Object.entries(mcpServers)) {
+        const mcpId = generateExternalMCPId(name);
+        // Create the MCP info with initial disconnected state
+        const mcpInfo = {
+            type: 'external-mcp',
+            id: mcpId,
+            name,
+            connected: false,
+            methods: [],
+            label: prettifyToolName(name),
+            icon: '🔌',
+            config: serverConfig,
+        };
+        try {
+            let methods = [];
+            if (serverConfig.url) {
+                // HTTP transport — SDK client only (no wrapper needed)
+                // Tries Streamable HTTP first, falls back to legacy SSE
+                const sdkClient = await connectHTTPClient(serverConfig.url, name);
+                externalMCPSDKClients.set(name, sdkClient);
+                // List tools with full metadata using SDK client
+                const toolsResult = await sdkClient.listTools();
+                const tools = toolsResult.tools || [];
+                // Convert tools to MethodInfo[] with full _meta support
+                methods = tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description || '',
+                    params: tool.inputSchema || { type: 'object', properties: {} },
+                    returns: { type: 'object' },
+                    icon: tool['x-icon'],
+                    linkedUi: tool._meta?.ui?.resourceUri,
+                    visibility: tool._meta?.ui?.visibility,
+                }));
+                // Fetch resources to detect MCP Apps
+                try {
+                    const resourcesResult = await sdkClient.listResources();
+                    const resources = resourcesResult.resources || [];
+                    const appResources = resources.filter((r) => r.uri?.startsWith('ui://') ||
+                        r.mimeType === 'application/vnd.mcp.ui+html');
+                    // Count only non-UI resources (UI resources are internal implementation detail)
+                    mcpInfo.resourceCount = resources.length - appResources.length;
+                    if (appResources.length > 0) {
+                        mcpInfo.hasApp = true;
+                        mcpInfo.appResourceUri = appResources[0].uri;
+                        mcpInfo.appResourceUris = appResources.map((r) => r.uri);
+                        const uriList = mcpInfo.appResourceUris.join(', ');
+                        logger.info(`🎨 MCP App detected: ${name} (${uriList})`);
+                    }
+                }
+                catch (resourceError) {
+                    logger.debug(`Resources not supported by ${name}`);
+                }
+                mcpInfo.connected = true;
+                mcpInfo.methods = methods;
+            }
+            else if (serverConfig.command) {
+                // Stdio transport — create wrapper client as fallback, SDK client as primary
+                const mcpConfig = {
+                    mcpServers: {
+                        [name]: serverConfig,
+                    },
+                };
+                const factory = new SDKMCPClientFactory(mcpConfig, false);
+                const client = factory.create(name);
+                externalMCPClients.set(name, client);
+                try {
+                    const sdkTransport = new StdioClientTransport({
+                        command: serverConfig.command,
+                        args: serverConfig.args,
+                        cwd: serverConfig.cwd,
+                        env: serverConfig.env,
+                        stderr: 'ignore', // Suppress stderr to avoid ugly tracebacks on shutdown
+                    });
+                    const sdkClient = new Client({ name: 'beam-mcp-client', version: '1.0.0' }, {
+                        capabilities: {
+                            elicitation: {}, // Declare elicitation support
+                            experimental: {
+                                ui: {}, // Request SEP-1865 format for MCP Apps
+                            },
+                        },
+                    });
+                    // Set up elicitation handler BEFORE connecting
+                    // This handles elicitation/create requests from the server
+                    sdkClient.setRequestHandler(ElicitRequestSchema, async (request) => {
+                        const params = request.params;
+                        const result = await requestExternalElicitation(name, {
+                            mode: params.mode,
+                            message: params.message,
+                            requestedSchema: params.requestedSchema,
+                            url: params.url,
+                        });
+                        return result;
+                    });
+                    const connectPromise = sdkClient.connect(sdkTransport);
+                    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
+                    await Promise.race([connectPromise, timeoutPromise]);
+                    externalMCPSDKClients.set(name, sdkClient);
+                    // List tools with full metadata using SDK client
+                    const toolsResult = await sdkClient.listTools();
+                    const tools = toolsResult.tools || [];
+                    // Convert tools to MethodInfo[] with full _meta support
+                    methods = tools.map((tool) => ({
+                        name: tool.name,
+                        description: tool.description || '',
+                        params: tool.inputSchema || { type: 'object', properties: {} },
+                        returns: { type: 'object' },
+                        icon: tool['x-icon'],
+                        // Preserve MCP App linkage from tool metadata
+                        linkedUi: tool._meta?.ui?.resourceUri,
+                        visibility: tool._meta?.ui?.visibility,
+                    }));
+                    // Fetch resources to detect MCP Apps
+                    try {
+                        const resourcesResult = await sdkClient.listResources();
+                        const resources = resourcesResult.resources || [];
+                        // Check for MCP App resources (ui:// scheme or application/vnd.mcp.ui+html mime)
+                        const appResources = resources.filter((r) => r.uri?.startsWith('ui://') ||
+                            r.mimeType === 'application/vnd.mcp.ui+html');
+                        // Count only non-UI resources (UI resources are internal implementation detail)
+                        mcpInfo.resourceCount = resources.length - appResources.length;
+                        if (appResources.length > 0) {
+                            mcpInfo.hasApp = true;
+                            mcpInfo.appResourceUri = appResources[0].uri; // Default to first
+                            mcpInfo.appResourceUris = appResources.map((r) => r.uri);
+                            const uriList = mcpInfo.appResourceUris.join(', ');
+                            logger.info(`🎨 MCP App detected: ${name} (${uriList})`);
+                        }
+                    }
+                    catch (resourceError) {
+                        // Resources not supported - that's fine
+                        logger.debug(`Resources not supported by ${name}`);
+                    }
+                    // Set connected state after successful SDK client setup
+                    mcpInfo.connected = true;
+                    mcpInfo.methods = methods;
+                }
+                catch (sdkError) {
+                    // SDK client failed - fall back to wrapper client
+                    logger.debug(`SDK client failed for ${name}, using wrapper: ${sdkError}`);
+                    // Try wrapper client as fallback
+                    const tools = await client.list();
+                    methods = (tools || []).map((tool) => ({
+                        name: tool.name,
+                        description: tool.description || '',
+                        params: tool.inputSchema || { type: 'object', properties: {} },
+                        returns: { type: 'object' },
+                        icon: tool['x-icon'],
+                    }));
+                    mcpInfo.connected = true;
+                    mcpInfo.methods = methods;
+                }
+            }
+            else {
+                // No command or URL — create wrapper client (legacy fallback)
+                const mcpConfig = {
+                    mcpServers: {
+                        [name]: serverConfig,
+                    },
+                };
+                const factory = new SDKMCPClientFactory(mcpConfig, false);
+                const client = factory.create(name);
+                externalMCPClients.set(name, client);
+                const tools = await client.list();
+                methods = (tools || []).map((tool) => ({
+                    name: tool.name,
+                    description: tool.description || '',
+                    params: tool.inputSchema || { type: 'object', properties: {} },
+                    returns: { type: 'object' },
+                    icon: tool['x-icon'],
+                }));
+                mcpInfo.connected = true;
+                mcpInfo.methods = methods;
+            }
+            logger.info(`🔌 Connected to external MCP: ${name} (${methods.length} tools)`);
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            mcpInfo.errorMessage = errorMsg.slice(0, 200);
+            logger.warn(`⚠️ Failed to connect to external MCP: ${name} - ${errorMsg}`);
+        }
+        results.push(mcpInfo);
+    }
+    return results;
+}
+/**
+ * Reconnect a failed external MCP
+ *
+ * @param name - The MCP name to reconnect
+ * @returns Success status and error message if failed
+ */
+async function reconnectExternalMCP(name) {
+    const mcpIndex = externalMCPs.findIndex((m) => m.name === name);
+    if (mcpIndex === -1) {
+        return { success: false, error: `External MCP not found: ${name}` };
+    }
+    const mcp = externalMCPs[mcpIndex];
+    try {
+        let methods = [];
+        if (mcp.config.url) {
+            // HTTP transport — tries Streamable HTTP, falls back to legacy SSE
+            const sdkClient = await connectHTTPClient(mcp.config.url, name);
+            externalMCPSDKClients.set(name, sdkClient);
+            const toolsResult = await sdkClient.listTools();
+            const tools = toolsResult.tools || [];
+            methods = tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description || '',
+                params: tool.inputSchema || { type: 'object', properties: {} },
+                returns: { type: 'object' },
+                icon: tool['x-icon'],
+                linkedUi: tool._meta?.ui?.resourceUri,
+                visibility: tool._meta?.ui?.visibility,
+            }));
+            // Fetch resources to detect MCP Apps
+            try {
+                const resourcesResult = await sdkClient.listResources();
+                const resources = resourcesResult.resources || [];
+                const appResources = resources.filter((r) => r.uri?.startsWith('ui://') ||
+                    r.mimeType === 'application/vnd.mcp.ui+html');
+                // Count only non-UI resources (UI resources are internal implementation detail)
+                mcp.resourceCount = resources.length - appResources.length;
+                if (appResources.length > 0) {
+                    mcp.hasApp = true;
+                    mcp.appResourceUri = appResources[0].uri;
+                    mcp.appResourceUris = appResources.map((r) => r.uri);
+                }
+            }
+            catch {
+                // Resources not supported
+            }
+        }
+        else {
+            // Stdio / wrapper transport
+            const mcpConfig = {
+                mcpServers: {
+                    [name]: mcp.config,
+                },
+            };
+            const factory = new SDKMCPClientFactory(mcpConfig, false);
+            const client = factory.create(name);
+            const connectPromise = client.list();
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
+            const tools = (await Promise.race([connectPromise, timeoutPromise]));
+            methods = (tools || []).map((tool) => ({
+                name: tool.name,
+                description: tool.description || '',
+                params: tool.inputSchema || { type: 'object', properties: {} },
+                returns: { type: 'object' },
+                icon: tool['x-icon'],
+            }));
+            externalMCPClients.set(name, client);
+        }
+        // Update MCP info
+        mcp.connected = true;
+        mcp.methods = methods;
+        mcp.errorMessage = undefined;
+        logger.info(`🔌 Reconnected to external MCP: ${name} (${methods.length} tools)`);
+        return { success: true };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        mcp.errorMessage = errorMsg.slice(0, 200);
+        logger.warn(`⚠️ Failed to reconnect to external MCP: ${name} - ${errorMsg}`);
+        return { success: false, error: errorMsg };
+    }
+}
 /**
  * Migrate old flat config to new nested structure
  */
@@ -80,6 +449,31 @@ async function saveConfig(config) {
 /**
  * Extract class-level metadata (description, icon) from JSDoc comments
  */
+/**
+ * Convert a kebab-case name to a display label
+ * e.g. "filesystem" → "Filesystem", "git-box" → "Git Box"
+ */
+function prettifyName(name) {
+    return name
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * After loading a photon, backfill env vars for constructor params that used
+ * their TypeScript defaults (env var not set). This ensures the env var always
+ * reflects the effective value so other consumers (e.g. /api/browse) can read it.
+ */
+function backfillEnvDefaults(instance, params) {
+    for (const param of params) {
+        if (!process.env[param.envVar] && param.hasDefault) {
+            const value = instance[param.name];
+            if (value !== undefined && value !== null) {
+                process.env[param.envVar] = String(value);
+            }
+        }
+    }
+}
 function extractClassMetadataFromSource(content) {
     try {
         // Find class-level JSDoc (immediately before class, or first JSDoc in file)
@@ -109,6 +503,11 @@ function extractClassMetadataFromSource(content) {
         if (authorMatch) {
             metadata.author = authorMatch[1].trim();
         }
+        // Extract @label (custom display name)
+        const labelMatch = docContent.match(/@label\s+([^\n@]+)/);
+        if (labelMatch) {
+            metadata.label = labelMatch[1].trim();
+        }
         // Extract @description or first line of doc (not starting with @)
         const descMatch = docContent.match(/@description\s+([^\n@]+)/);
         if (descMatch) {
@@ -250,9 +649,13 @@ export async function startBeam(rawWorkingDir, port) {
         catch {
             // Can't read source
         }
-        // Extract @internal early — outside try/catch so it's always available
-        if (source && /@internal\b/.test(source)) {
-            isInternal = true;
+        // Extract @internal from class-level JSDoc only (not the entire source,
+        // which would false-positive on method-level @internal tags)
+        if (source) {
+            const earlyMeta = extractClassMetadataFromSource(source);
+            if (earlyMeta.internal) {
+                isInternal = true;
+            }
         }
         try {
             if (source) {
@@ -300,6 +703,7 @@ export async function startBeam(rawWorkingDir, port) {
                 configured: false,
                 internal: isInternal,
                 requiredParams: constructorParams,
+                errorReason: 'missing-config',
                 errorMessage: missingRequired.length > 0
                     ? `Missing required: ${missingRequired.map((p) => p.name).join(', ')}`
                     : 'Has placeholder values that need configuration',
@@ -315,6 +719,7 @@ export async function startBeam(rawWorkingDir, port) {
                 return null;
             }
             photonMCPs.set(name, mcp);
+            backfillEnvDefaults(instance, constructorParams);
             // Extract schema for UI — reuse source read from above
             const schemaSource = source || (await fs.readFile(photonPath, 'utf-8'));
             const { tools: schemas, templates } = extractor.extractAllFromSource(schemaSource);
@@ -339,6 +744,9 @@ export async function startBeam(rawWorkingDir, port) {
                     icon: schema.icon,
                     linkedUi: linkedAsset?.id,
                     ...(schema.isStatic ? { isStatic: true } : {}),
+                    ...(schema.webhook ? { webhook: schema.webhook } : {}),
+                    ...(schema.scheduled || schema.cron ? { scheduled: schema.scheduled || schema.cron } : {}),
+                    ...(schema.locked ? { locked: schema.locked } : {}),
                 };
             });
             // Add templates as methods with isTemplate flag and markdown output format
@@ -402,6 +810,7 @@ export async function startBeam(rawWorkingDir, port) {
                 appEntry: mainMethod,
                 assets: mcp.assets,
                 description: classMetadata.description || mcp.description || `${name} MCP`,
+                label: classMetadata.label || prettifyName(name),
                 icon: classMetadata.icon,
                 internal: isInternal || classMetadata.internal,
                 version: metaVersion,
@@ -409,22 +818,24 @@ export async function startBeam(rawWorkingDir, port) {
                 resourceCount,
                 promptCount,
                 installSource,
+                ...(constructorParams.length > 0 && { requiredParams: constructorParams }),
+                ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
             };
         }
         catch (error) {
             const errorMsg = error instanceof Error ? error.message : String(error);
-            if (constructorParams.length > 0) {
-                return {
-                    id: generatePhotonId(photonPath),
-                    name,
-                    path: photonPath,
-                    configured: false,
-                    internal: isInternal,
-                    requiredParams: constructorParams,
-                    errorMessage: errorMsg.slice(0, 200),
-                };
-            }
-            return null;
+            // Always surface errored photons in the sidebar instead of silently dropping them
+            return {
+                id: generatePhotonId(photonPath),
+                name,
+                path: photonPath,
+                configured: false,
+                label: prettifyName(name),
+                internal: isInternal,
+                requiredParams: constructorParams,
+                errorReason: constructorParams.length > 0 ? 'missing-config' : 'load-error',
+                errorMessage: errorMsg.slice(0, 200),
+            };
         }
     }
     const channelSubscriptions = new Map();
@@ -614,6 +1025,10 @@ export async function startBeam(rawWorkingDir, port) {
             const handled = await handleStreamableHTTP(req, res, {
                 photons, // Pass all photons including unconfigured for configurationSchema
                 photonMCPs,
+                externalMCPs,
+                externalMCPClients,
+                externalMCPSDKClients, // SDK clients for tool calls with structuredContent
+                reconnectExternalMCP,
                 loadUIAsset,
                 configurePhoton: async (photonName, config) => {
                     return configurePhotonViaMCP(photonName, config, photons, photonMCPs, loader, savedConfig);
@@ -708,8 +1123,17 @@ export async function startBeam(rawWorkingDir, port) {
         // File browser API
         if (url.pathname === '/api/browse') {
             res.setHeader('Content-Type', 'application/json');
-            const dirPath = url.searchParams.get('path') || workingDir;
-            const root = url.searchParams.get('root');
+            let root = url.searchParams.get('root');
+            // Resolve photon's workdir as root constraint
+            const photonParam = url.searchParams.get('photon');
+            if (photonParam && !root) {
+                const envPrefix = photonParam.toUpperCase().replace(/-/g, '_');
+                const workdirEnv = process.env[`${envPrefix}_WORKDIR`];
+                if (workdirEnv) {
+                    root = path.resolve(workdirEnv);
+                }
+            }
+            const dirPath = url.searchParams.get('path') || root || workingDir;
             try {
                 const resolved = path.resolve(dirPath);
                 // Validate path is within root (if specified)
@@ -870,6 +1294,55 @@ export async function startBeam(rawWorkingDir, port) {
             }
             return;
         }
+        // Serve MCP App HTML from external MCPs with MCP Apps Extension
+        if (url.pathname === '/api/mcp-app') {
+            const mcpName = url.searchParams.get('mcp');
+            const resourceUri = url.searchParams.get('uri');
+            if (!mcpName || !resourceUri) {
+                res.writeHead(400);
+                res.end(JSON.stringify({ error: 'Missing mcp or uri parameter' }));
+                return;
+            }
+            const sdkClient = externalMCPSDKClients.get(mcpName);
+            if (!sdkClient) {
+                res.writeHead(404);
+                res.end(JSON.stringify({ error: `MCP not found or no SDK client: ${mcpName}` }));
+                return;
+            }
+            try {
+                const resourceResult = await sdkClient.readResource({ uri: resourceUri });
+                const content = resourceResult.contents?.[0];
+                if (!content) {
+                    res.writeHead(404);
+                    res.end(JSON.stringify({ error: `Resource not found: ${resourceUri}` }));
+                    return;
+                }
+                // Content can have either text or blob
+                const contentText = 'text' in content ? content.text : null;
+                const contentBlob = 'blob' in content ? content.blob : null;
+                if (!contentText && !contentBlob) {
+                    res.writeHead(404);
+                    res.end(JSON.stringify({ error: `Resource has no content: ${resourceUri}` }));
+                    return;
+                }
+                res.setHeader('Content-Type', content.mimeType || 'text/html');
+                res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+                res.writeHead(200);
+                if (contentText) {
+                    res.end(contentText);
+                }
+                else if (contentBlob) {
+                    // blob is base64 encoded
+                    res.end(Buffer.from(contentBlob, 'base64'));
+                }
+            }
+            catch (error) {
+                logger.error(`Failed to read MCP App resource: ${error}`);
+                res.writeHead(500);
+                res.end(JSON.stringify({ error: `Failed to read resource: ${error}` }));
+            }
+            return;
+        }
         // Serve @ui template files (class-level custom UI)
         if (url.pathname === '/api/template') {
             const photonName = url.searchParams.get('photon');
@@ -1170,19 +1643,23 @@ export async function startBeam(rawWorkingDir, port) {
             return;
         }
         // Platform Bridge API: Generate platform compatibility script
+        // Uses the unified bridge architecture based on @modelcontextprotocol/ext-apps SDK
         if (url.pathname === '/api/platform-bridge') {
             const theme = (url.searchParams.get('theme') || 'dark');
             const photonName = url.searchParams.get('photon') || '';
             const methodName = url.searchParams.get('method') || '';
-            const { generatePlatformBridgeScript } = await import('./platform-compat.js');
-            const script = generatePlatformBridgeScript({
+            // Look up injected photons for this photon
+            const photon = photons.find((p) => p.name === photonName);
+            const injectedPhotonsList = photon && photon.configured && photon.injectedPhotons;
+            const { generateBridgeScript } = await import('./bridge/index.js');
+            const script = generateBridgeScript({
                 theme,
                 locale: 'en-US',
-                displayMode: 'inline',
                 photon: photonName,
                 method: methodName,
                 hostName: 'beam',
                 hostVersion: '1.5.0',
+                injectedPhotons: injectedPhotonsList || [],
             });
             res.setHeader('Content-Type', 'text/html');
             res.writeHead(200);
@@ -1200,6 +1677,8 @@ export async function startBeam(rawWorkingDir, port) {
                     status: p.configured ? 'loaded' : 'unconfigured',
                     methods: p.configured ? p.methods.length : 0,
                     error: !p.configured ? p.errorMessage : undefined,
+                    internal: p.internal || undefined,
+                    path: p.path || undefined,
                 }));
                 res.writeHead(200);
                 res.end(JSON.stringify({
@@ -1778,15 +2257,16 @@ export async function startBeam(rawWorkingDir, port) {
                 const missingRequired = constructorParams.filter((p) => !p.isOptional && !p.hasDefault && !process.env[p.envVar]);
                 if (missingRequired.length > 0 && constructorParams.length > 0) {
                     // Add as unconfigured photon
-                    const unconfiguredPhoton = {
+                    const targetPhoton = {
                         id: generatePhotonId(photonPath),
                         name: photonName,
                         path: photonPath,
                         configured: false,
                         requiredParams: constructorParams,
+                        errorReason: 'missing-config',
                         errorMessage: `Missing required: ${missingRequired.map((p) => p.name).join(', ')}`,
                     };
-                    photons.push(unconfiguredPhoton);
+                    photons.push(targetPhoton);
                     broadcastPhotonChange();
                     logger.info(`⚙️ ${photonName} added (needs configuration)`);
                     return;
@@ -1843,6 +2323,25 @@ export async function startBeam(rawWorkingDir, port) {
                 const mainMethod = methods.find((m) => m.name === 'main' && m.linkedUi);
                 // Extract class metadata from source
                 const reloadClassMeta = extractClassMetadataFromSource(reloadSource);
+                // Extract constructor params for reconfiguration support
+                let reloadConstructorParams = [];
+                try {
+                    const reloadParams = extractor.extractConstructorParams(reloadSource);
+                    reloadConstructorParams = reloadParams
+                        .filter((p) => p.isPrimitive)
+                        .map((p) => ({
+                        name: p.name,
+                        envVar: toEnvVarName(photonName, p.name),
+                        type: p.type,
+                        isOptional: p.isOptional,
+                        hasDefault: p.hasDefault,
+                        defaultValue: p.defaultValue,
+                    }));
+                }
+                catch {
+                    // Can't extract params
+                }
+                backfillEnvDefaults(mcp.instance, reloadConstructorParams);
                 const reloadedPhoton = {
                     id: generatePhotonId(photonPath),
                     name: photonName,
@@ -1853,7 +2352,9 @@ export async function startBeam(rawWorkingDir, port) {
                     appEntry: mainMethod,
                     description: reloadClassMeta.description,
                     icon: reloadClassMeta.icon,
-                    internal: reloadClassMeta.internal || (/@internal\b/.test(reloadSource) || undefined),
+                    internal: reloadClassMeta.internal,
+                    ...(reloadConstructorParams.length > 0 && { requiredParams: reloadConstructorParams }),
+                    ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
                 };
                 if (isNewPhoton) {
                     photons.push(reloadedPhoton);
@@ -1891,20 +2392,19 @@ export async function startBeam(rawWorkingDir, port) {
                     catch {
                         // Ignore extraction errors
                     }
-                    if (constructorParams.length > 0) {
-                        const unconfiguredPhoton = {
-                            id: generatePhotonId(photonPath),
-                            name: photonName,
-                            path: photonPath,
-                            configured: false,
-                            requiredParams: constructorParams,
-                            errorMessage: errorMsg.slice(0, 200),
-                        };
-                        photons.push(unconfiguredPhoton);
-                        broadcastPhotonChange();
-                        logger.info(`⚙️ ${photonName} added (needs configuration)`);
-                        return;
-                    }
+                    const targetPhoton = {
+                        id: generatePhotonId(photonPath),
+                        name: photonName,
+                        path: photonPath,
+                        configured: false,
+                        requiredParams: constructorParams,
+                        errorReason: constructorParams.length > 0 ? 'missing-config' : 'load-error',
+                        errorMessage: errorMsg.slice(0, 200),
+                    };
+                    photons.push(targetPhoton);
+                    broadcastPhotonChange();
+                    logger.info(`⚙️ ${photonName} added (needs attention: ${targetPhoton.errorReason})`);
+                    return;
                 }
                 logger.error(`Hot reload failed for ${photonName}: ${errorMsg}`);
                 broadcastToBeam('beam/error', {
@@ -1949,6 +2449,39 @@ export async function startBeam(rawWorkingDir, port) {
     // Start server BEFORE loading photons so the UI is immediately reachable
     const maxPortAttempts = 10;
     let currentPort = port;
+    // Check if a port is available by attempting to connect to it
+    // This catches cases where another server binds to 127.0.0.1 but not 0.0.0.0
+    const isPortAvailable = (p) => {
+        return new Promise((resolve) => {
+            const socket = new net.Socket();
+            socket.setTimeout(500);
+            socket.once('connect', () => {
+                socket.destroy();
+                resolve(false); // Port is in use
+            });
+            socket.once('timeout', () => {
+                socket.destroy();
+                resolve(true); // Timeout = port likely free
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                resolve(true); // Connection refused = port is free
+            });
+            socket.connect(p, '127.0.0.1');
+        });
+    };
+    // Find an available port
+    while (currentPort < port + maxPortAttempts) {
+        const available = await isPortAvailable(currentPort);
+        if (available)
+            break;
+        console.error(`⚠️  Port ${currentPort} is in use, trying ${currentPort + 1}...`);
+        currentPort++;
+    }
+    if (currentPort >= port + maxPortAttempts) {
+        console.error(`\n❌ No available port found (tried ${port}-${currentPort - 1}). Exiting.\n`);
+        process.exit(1);
+    }
     await new Promise((resolve) => {
         const tryListen = () => {
             server.once('error', (err) => {
@@ -1988,10 +2521,18 @@ export async function startBeam(rawWorkingDir, port) {
     }
     configuredCount = photons.filter((p) => p.configured).length;
     unconfiguredCount = photons.filter((p) => !p.configured).length;
-    const status = unconfiguredCount > 0
+    // Load external MCPs from config
+    const externalMCPList = await loadExternalMCPs(savedConfig);
+    externalMCPs.push(...externalMCPList);
+    const connectedMCPs = externalMCPList.filter((m) => m.connected).length;
+    const failedMCPs = externalMCPList.length - connectedMCPs;
+    const photonStatus = unconfiguredCount > 0
         ? `${configuredCount} ready, ${unconfiguredCount} need setup`
         : `${configuredCount} photon${configuredCount !== 1 ? 's' : ''} ready`;
-    console.log(`⚡ Photon Beam ready (${status})`);
+    const mcpStatus = externalMCPList.length > 0
+        ? `, ${connectedMCPs}/${externalMCPList.length} MCPs`
+        : '';
+    console.log(`⚡ Photon Beam ready (${photonStatus}${mcpStatus})`);
     // Notify connected clients that photon list is now available
     broadcastPhotonChange();
     // Set up file watchers for symlinked and bundled photon assets (now that photons are loaded)
@@ -2082,35 +2623,145 @@ export async function startBeam(rawWorkingDir, port) {
             // Asset folder doesn't exist or can't be watched - that's okay
         }
     }
+    // ══════════════════════════════════════════════════════════════════════════════
+    // CONFIG.JSON WATCHER — Detect external MCP changes without restart
+    // Watch the parent directory (atomic writes via rename can miss single-file watches)
+    // ══════════════════════════════════════════════════════════════════════════════
+    try {
+        const configDir = path.dirname(CONFIG_FILE);
+        let configDebounce = null;
+        const configWatcher = watch(configDir, (eventType, filename) => {
+            if (filename !== 'config.json')
+                return;
+            if (configDebounce)
+                clearTimeout(configDebounce);
+            configDebounce = setTimeout(async () => {
+                configDebounce = null;
+                let newConfig;
+                try {
+                    const data = await fs.readFile(CONFIG_FILE, 'utf-8');
+                    newConfig = migrateConfig(JSON.parse(data));
+                }
+                catch (err) {
+                    logger.warn(`⚠️ Failed to parse config.json: ${err instanceof Error ? err.message : err}`);
+                    return;
+                }
+                const oldServers = savedConfig.mcpServers || {};
+                const newServers = newConfig.mcpServers || {};
+                const oldKeys = new Set(Object.keys(oldServers));
+                const newKeys = new Set(Object.keys(newServers));
+                const added = [...newKeys].filter((k) => !oldKeys.has(k));
+                const removed = [...oldKeys].filter((k) => !newKeys.has(k));
+                const kept = [...newKeys].filter((k) => oldKeys.has(k));
+                const modified = kept.filter((k) => JSON.stringify(oldServers[k]) !== JSON.stringify(newServers[k]));
+                if (added.length === 0 && removed.length === 0 && modified.length === 0) {
+                    // Also sync photon config changes (env vars etc.)
+                    savedConfig.photons = newConfig.photons || {};
+                    return;
+                }
+                logger.info(`🔧 config.json changed — added: [${added}], removed: [${removed}], modified: [${modified}]`);
+                // Remove MCPs
+                for (const name of removed) {
+                    const idx = externalMCPs.findIndex((m) => m.name === name);
+                    if (idx !== -1)
+                        externalMCPs.splice(idx, 1);
+                    // Clean up clients
+                    try {
+                        const sdkClient = externalMCPSDKClients.get(name);
+                        if (sdkClient) {
+                            await sdkClient.close();
+                            externalMCPSDKClients.delete(name);
+                        }
+                    }
+                    catch { /* ignore */ }
+                    externalMCPClients.delete(name);
+                    logger.info(`🔌 Removed external MCP: ${name}`);
+                }
+                // Add new MCPs
+                if (added.length > 0) {
+                    const addConfig = {
+                        photons: {},
+                        mcpServers: Object.fromEntries(added.map((k) => [k, newServers[k]])),
+                    };
+                    const newMCPs = await loadExternalMCPs(addConfig);
+                    externalMCPs.push(...newMCPs);
+                    for (const m of newMCPs) {
+                        logger.info(`🔌 Added external MCP: ${m.name} (${m.connected ? m.methods.length + ' tools' : 'failed'})`);
+                    }
+                }
+                // Reconnect modified MCPs
+                for (const name of modified) {
+                    const idx = externalMCPs.findIndex((m) => m.name === name);
+                    if (idx !== -1) {
+                        // Clean up old clients
+                        try {
+                            const sdkClient = externalMCPSDKClients.get(name);
+                            if (sdkClient) {
+                                await sdkClient.close();
+                                externalMCPSDKClients.delete(name);
+                            }
+                        }
+                        catch { /* ignore */ }
+                        externalMCPClients.delete(name);
+                        externalMCPs.splice(idx, 1);
+                    }
+                    // Reconnect with new config
+                    const modConfig = {
+                        photons: {},
+                        mcpServers: { [name]: newServers[name] },
+                    };
+                    const reconnected = await loadExternalMCPs(modConfig);
+                    externalMCPs.push(...reconnected);
+                    logger.info(`🔌 Reconnected external MCP: ${name}`);
+                }
+                // Update savedConfig
+                savedConfig.mcpServers = newConfig.mcpServers || {};
+                savedConfig.photons = newConfig.photons || {};
+                broadcastPhotonChange();
+            }, 500);
+        });
+        configWatcher.on('error', (err) => {
+            logger.warn(`Config watcher error: ${err.message}`);
+        });
+        watchers.push(configWatcher);
+        logger.info(`👀 Watching config.json for external MCP changes`);
+    }
+    catch (error) {
+        logger.warn(`Config watching not available: ${error}`);
+    }
 }
 /**
  * Configure a photon via MCP
  */
 async function configurePhotonViaMCP(photonName, config, photons, photonMCPs, loader, savedConfig) {
-    // Find the unconfigured photon
-    const photonIndex = photons.findIndex((p) => p.name === photonName && !p.configured);
+    // Find the photon (configured or unconfigured)
+    const photonIndex = photons.findIndex((p) => p.name === photonName);
     if (photonIndex === -1) {
-        return { success: false, error: `Photon not found or already configured: ${photonName}` };
+        return { success: false, error: `Photon not found: ${photonName}` };
     }
-    const unconfiguredPhoton = photons[photonIndex];
     // Apply config to environment
     for (const [key, value] of Object.entries(config)) {
         process.env[key] = String(value);
     }
-    // Save config to file
-    savedConfig.photons[photonName] = config;
+    // Save config to file (merge with existing config for edit mode)
+    savedConfig.photons[photonName] = { ...(savedConfig.photons[photonName] || {}), ...config };
     await saveConfig(savedConfig);
+    const targetPhoton = photons[photonIndex];
+    const isReconfigure = targetPhoton.configured === true;
     // Try to reload the photon
     try {
-        const mcp = await loader.loadFile(unconfiguredPhoton.path);
+        const mcp = isReconfigure
+            ? await loader.reloadFile(targetPhoton.path)
+            : await loader.loadFile(targetPhoton.path);
         const instance = mcp.instance;
         if (!instance) {
             throw new Error('Failed to create instance');
         }
         photonMCPs.set(photonName, mcp);
+        backfillEnvDefaults(instance, targetPhoton.requiredParams || []);
         // Extract schema for UI
         const extractor = new SchemaExtractor();
-        const configSource = await fs.readFile(unconfiguredPhoton.path, 'utf-8');
+        const configSource = await fs.readFile(targetPhoton.path, 'utf-8');
         const { tools: schemas, templates } = extractor.extractAllFromSource(configSource);
         mcp.schemas = schemas;
         // Get UI assets for linking
@@ -2153,14 +2804,15 @@ async function configurePhotonViaMCP(photonName, config, photons, photonMCPs, lo
         const isApp = !!mainMethod;
         // Replace unconfigured photon with configured one
         const configuredPhoton = {
-            id: generatePhotonId(unconfiguredPhoton.path),
+            id: generatePhotonId(targetPhoton.path),
             name: photonName,
-            path: unconfiguredPhoton.path,
+            path: targetPhoton.path,
             configured: true,
             methods,
             isApp,
             appEntry: mainMethod,
             assets: mcp.assets,
+            ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
         };
         photons[photonIndex] = configuredPhoton;
         logger.info(`✅ ${photonName} configured via MCP`);
@@ -2200,6 +2852,7 @@ async function reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, saved
             throw new Error('Failed to create instance');
         }
         photonMCPs.set(photonName, mcp);
+        backfillEnvDefaults(instance, photon.requiredParams || []);
         // Extract schema for UI
         const extractor = new SchemaExtractor();
         const reloadSrc = await fs.readFile(photonPath, 'utf-8');
@@ -2254,7 +2907,8 @@ async function reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, saved
             appEntry: mainMethod,
             description: reloadClassMeta.description,
             icon: reloadClassMeta.icon,
-            internal: reloadClassMeta.internal || (/@internal\b/.test(reloadSrc) || undefined),
+            internal: reloadClassMeta.internal,
+            ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
         };
         photons[photonIndex] = reloadedPhoton;
         logger.info(`🔄 ${photonName} reloaded via MCP`);
@@ -2378,4 +3032,26 @@ async function generatePhotonHelpMarkdown(photonName, photons) {
     }
     return markdown;
 }
+/**
+ * Gracefully stop Beam server and clean up resources.
+ * Closes all external MCP SDK clients to prevent ugly tracebacks on shutdown.
+ */
+export async function stopBeam() {
+    // Close all SDK clients gracefully
+    const closePromises = [];
+    for (const [, client] of externalMCPSDKClients) {
+        closePromises.push(client.close().catch(() => {
+            // Ignore close errors - process is exiting anyway
+        }));
+    }
+    // Wait for all clients to close (with timeout)
+    if (closePromises.length > 0) {
+        await Promise.race([
+            Promise.all(closePromises),
+            new Promise((resolve) => setTimeout(resolve, 1000)), // 1 second timeout
+        ]);
+    }
+    externalMCPSDKClients.clear();
+    externalMCPClients.clear();
+}
 //# sourceMappingURL=beam.js.map