@portel/photon-core 1.3.0 → 1.4.0

package/src/index.ts

@@ -83,11 +83,14 @@ export {
   MCPError,
   MCPNotConnectedError,
   MCPToolError,
+  MCPConfigurationError,
   createMCPProxy,
   type MCPToolInfo,
   type MCPToolResult,
   type MCPTransport,
   type MCPClientFactory,
+  type MCPSourceType,
+  type MissingMCPInfo,
 } from './mcp-client.js';
 
 // MCP SDK Transport - official SDK-based transport implementation
@@ -107,6 +110,7 @@ export {
   // Type guards - check yield direction
   isAskYield,
   isEmitYield,
+  isCheckpointYield,
   getAskType,
   getEmitType,
 
@@ -136,6 +140,17 @@ export {
   type AskNumber,
   type AskFile,
   type AskDate,
+  type AskForm,
+  type AskUrl,
+
+  // Form schema types (for AskForm)
+  type FormSchema,
+  type FormSchemaProperty,
+  type FormSchemaArrayProperty,
+
+  // MCP elicitation result types
+  type ElicitAction,
+  type FormElicitResult,
 
   // Emit yield types (output to user)
   type EmitYield,
@@ -146,9 +161,14 @@ export {
   type EmitToast,
   type EmitThinking,
   type EmitArtifact,
+  type EmitUI,
 
-  // Combined type
+  // Checkpoint yield type (for stateful workflows)
+  type CheckpointYield,
+
+  // Combined types
   type PhotonYield,
+  type StatefulYield,
 
   // Execution config
   type InputProvider,
@@ -191,3 +211,55 @@ export {
   type ElicitHandler,
   type PromptHandler,
 } from './elicit.js';
+
+// Photon Runtime Configuration - ~/.photon/mcp-servers.json
+export {
+  // Constants
+  PHOTON_CONFIG_DIR,
+  MCP_SERVERS_CONFIG_FILE,
+  // Load/Save
+  loadPhotonMCPConfig,
+  savePhotonMCPConfig,
+  // Query
+  isMCPConfigured,
+  getMCPServerConfig,
+  listMCPServers,
+  // Modify
+  setMCPServerConfig,
+  removeMCPServerConfig,
+  // Utilities
+  toMCPConfig,
+  resolveEnvVars,
+  // Types
+  type PhotonMCPConfig,
+} from './photon-config.js';
+
+// Stateful Workflow Execution - JSONL persistence with checkpoints
+export {
+  // Constants
+  RUNS_DIR,
+
+  // State Log - JSONL persistence
+  StateLog,
+
+  // Resume state parsing
+  parseResumeState,
+
+  // Stateful executor
+  executeStatefulGenerator,
+  generateRunId,
+
+  // Run management
+  listRuns,
+  getRunInfo,
+  deleteRun,
+  cleanupRuns,
+
+  // Types re-exported from stateful.ts
+  type CheckpointYield as StatefulCheckpointYield,
+  type StatefulYield as StatefulWorkflowYield,
+  isCheckpointYield as isStatefulCheckpointYield,
+  type ResumeState,
+  type StatefulExecutorConfig,
+  type StatefulExecutionResult,
+} from './stateful.js';

package/src/mcp-client.ts

@@ -282,6 +282,260 @@ export class MCPToolError extends MCPError {
   }
 }
 
+/**
+ * MCP source type - how the MCP was declared
+ */
+export type MCPSourceType = 'npm' | 'github' | 'local' | 'url' | 'unknown';
+
+/**
+ * Information about a missing MCP dependency
+ */
+export interface MissingMCPInfo {
+  name: string;
+  source: string;
+  sourceType: MCPSourceType;
+  declaredIn?: string; // Photon file that declared this dependency
+  originalError?: string;
+}
+
+/**
+ * Error thrown when MCP is not configured correctly
+ * Provides detailed, actionable guidance for users
+ */
+export class MCPConfigurationError extends MCPError {
+  public readonly configPath: string;
+  public readonly missingMCPs: MissingMCPInfo[];
+
+  constructor(missingMCPs: MissingMCPInfo[]) {
+    const configPath = `~/.photon/mcp-servers.json`;
+    const message = MCPConfigurationError.formatMessage(missingMCPs, configPath);
+    super(missingMCPs[0]?.name || 'unknown', message);
+    this.name = 'MCPConfigurationError';
+    this.configPath = configPath;
+    this.missingMCPs = missingMCPs;
+  }
+
+  /**
+   * Format detailed error message with configuration instructions
+   */
+  private static formatMessage(missingMCPs: MissingMCPInfo[], configPath: string): string {
+    const lines: string[] = [
+      '',
+      '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+      '❌ MCP Configuration Required',
+      '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+      '',
+    ];
+
+    // List missing MCPs
+    lines.push(`The following MCP server${missingMCPs.length > 1 ? 's are' : ' is'} required but not configured:`);
+    lines.push('');
+
+    for (const mcp of missingMCPs) {
+      lines.push(`  • ${mcp.name}`);
+      if (mcp.source) {
+        lines.push(`    Source: ${mcp.source} (${mcp.sourceType})`);
+      }
+      if (mcp.declaredIn) {
+        lines.push(`    Declared in: ${mcp.declaredIn}`);
+      }
+      if (mcp.originalError) {
+        lines.push(`    Error: ${mcp.originalError}`);
+      }
+      lines.push('');
+    }
+
+    // Configuration instructions
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    lines.push('🔧 How to Fix');
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    lines.push('');
+    lines.push(`Add the following to ${configPath}:`);
+    lines.push('');
+
+    // Generate example config
+    const exampleConfig = MCPConfigurationError.generateExampleConfig(missingMCPs);
+    lines.push(exampleConfig);
+    lines.push('');
+
+    // Step-by-step instructions
+    lines.push('Steps:');
+    lines.push(`  1. Create or edit ${configPath}`);
+    lines.push('  2. Add the configuration above');
+    lines.push('  3. Replace placeholder values with your actual configuration');
+    lines.push('  4. Restart the Photon');
+    lines.push('');
+
+    // Per-source-type guidance
+    const uniqueTypes = new Set(missingMCPs.map(m => m.sourceType));
+    if (uniqueTypes.size > 0) {
+      lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+      lines.push('📖 Configuration Guide');
+      lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+      lines.push('');
+
+      for (const type of uniqueTypes) {
+        lines.push(...MCPConfigurationError.getSourceTypeGuide(type));
+        lines.push('');
+      }
+    }
+
+    lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate example JSON config for missing MCPs
+   */
+  private static generateExampleConfig(missingMCPs: MissingMCPInfo[]): string {
+    const servers: Record<string, any> = {};
+
+    for (const mcp of missingMCPs) {
+      servers[mcp.name] = MCPConfigurationError.getExampleServerConfig(mcp);
+    }
+
+    const config = { mcpServers: servers };
+    return JSON.stringify(config, null, 2)
+      .split('\n')
+      .map(line => '  ' + line)
+      .join('\n');
+  }
+
+  /**
+   * Get example server config based on source type
+   */
+  private static getExampleServerConfig(mcp: MissingMCPInfo): Record<string, any> {
+    switch (mcp.sourceType) {
+      case 'npm':
+        return {
+          command: 'npx',
+          args: ['-y', mcp.source],
+          env: {
+            '// Add required environment variables here': '',
+          },
+        };
+
+      case 'github': {
+        // Parse github source: owner/repo or owner/repo#branch
+        const [repo, branch] = mcp.source.split('#');
+        const args = ['-y', `github:${repo}`];
+        if (branch) {
+          args[1] = `github:${repo}#${branch}`;
+        }
+        return {
+          command: 'npx',
+          args,
+          env: {
+            '// Add required environment variables here': '',
+          },
+        };
+      }
+
+      case 'url':
+        if (mcp.source.startsWith('ws://') || mcp.source.startsWith('wss://')) {
+          return {
+            url: mcp.source,
+            transport: 'websocket',
+          };
+        }
+        return {
+          url: mcp.source,
+          transport: 'sse',
+        };
+
+      case 'local':
+        return {
+          command: mcp.source,
+          args: [],
+          cwd: '// Optional: working directory',
+        };
+
+      default:
+        return {
+          '// Configure this MCP server': '',
+          command: 'npx',
+          args: ['-y', '<package-name>'],
+        };
+    }
+  }
+
+  /**
+   * Get source-type specific guidance
+   */
+  private static getSourceTypeGuide(type: MCPSourceType): string[] {
+    switch (type) {
+      case 'npm':
+        return [
+          '📦 NPM Packages:',
+          '   MCP servers from npm are run via npx.',
+          '   Example: @modelcontextprotocol/server-github',
+          '',
+          '   {',
+          '     "command": "npx",',
+          '     "args": ["-y", "@modelcontextprotocol/server-github"],',
+          '     "env": {',
+          '       "GITHUB_TOKEN": "ghp_your_token_here"',
+          '     }',
+          '   }',
+        ];
+
+      case 'github':
+        return [
+          '🐙 GitHub Repositories:',
+          '   MCP servers from GitHub repos are cloned and run.',
+          '   Format: owner/repo or owner/repo#branch',
+          '',
+          '   {',
+          '     "command": "npx",',
+          '     "args": ["-y", "github:anthropics/mcp-server-github"],',
+          '     "env": {',
+          '       "GITHUB_TOKEN": "ghp_your_token_here"',
+          '     }',
+          '   }',
+        ];
+
+      case 'url':
+        return [
+          '🌐 Remote URLs:',
+          '   MCP servers running on remote hosts.',
+          '',
+          '   HTTP/SSE:',
+          '   {',
+          '     "url": "https://mcp.example.com/api",',
+          '     "transport": "sse",',
+          '     "headers": { "Authorization": "Bearer token" }',
+          '   }',
+          '',
+          '   WebSocket:',
+          '   {',
+          '     "url": "wss://mcp.example.com/ws",',
+          '     "transport": "websocket"',
+          '   }',
+        ];
+
+      case 'local':
+        return [
+          '💻 Local Commands:',
+          '   MCP servers running as local processes.',
+          '',
+          '   {',
+          '     "command": "/path/to/mcp-server",',
+          '     "args": ["--port", "3000"],',
+          '     "cwd": "/working/directory",',
+          '     "env": { "CONFIG": "value" }',
+          '   }',
+        ];
+
+      default:
+        return [
+          '⚙️ Custom Configuration:',
+          '   Configure the MCP server based on its documentation.',
+        ];
+    }
+  }
+}
+
 /**
  * Create a proxy-based MCP client that allows direct method calls
  *

package/src/photon-config.ts

@@ -0,0 +1,201 @@
+/**
+ * Photon Runtime Configuration
+ *
+ * Manages ~/.photon/mcp-servers.json for MCP server configuration.
+ * Compatible with Claude Desktop's mcpServers format.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import type { MCPConfig, MCPServerConfig } from './mcp-sdk-transport.js';
+
+/**
+ * Default config directory
+ */
+export const PHOTON_CONFIG_DIR = path.join(os.homedir(), '.photon');
+
+/**
+ * Default MCP servers config file
+ */
+export const MCP_SERVERS_CONFIG_FILE = path.join(PHOTON_CONFIG_DIR, 'mcp-servers.json');
+
+/**
+ * Photon MCP servers configuration file format
+ * Compatible with Claude Desktop's mcpServers format
+ */
+export interface PhotonMCPConfig {
+  mcpServers: Record<string, MCPServerConfig>;
+}
+
+/**
+ * Load MCP servers configuration from ~/.photon/mcp-servers.json
+ *
+ * @param configPath Optional custom config path (defaults to ~/.photon/mcp-servers.json)
+ * @returns The MCP configuration, or empty config if file doesn't exist
+ */
+export async function loadPhotonMCPConfig(configPath?: string): Promise<PhotonMCPConfig> {
+  const filePath = configPath || MCP_SERVERS_CONFIG_FILE;
+
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const config = JSON.parse(content) as PhotonMCPConfig;
+
+    // Validate structure
+    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+      console.error(`Invalid config format in ${filePath}: missing mcpServers`);
+      return { mcpServers: {} };
+    }
+
+    return config;
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      // File doesn't exist - return empty config
+      return { mcpServers: {} };
+    }
+    console.error(`Failed to load config from ${filePath}: ${error.message}`);
+    return { mcpServers: {} };
+  }
+}
+
+/**
+ * Save MCP servers configuration to ~/.photon/mcp-servers.json
+ *
+ * @param config The configuration to save
+ * @param configPath Optional custom config path
+ */
+export async function savePhotonMCPConfig(
+  config: PhotonMCPConfig,
+  configPath?: string
+): Promise<void> {
+  const filePath = configPath || MCP_SERVERS_CONFIG_FILE;
+  const dir = path.dirname(filePath);
+
+  // Ensure directory exists
+  await fs.mkdir(dir, { recursive: true });
+
+  // Write config with pretty formatting
+  await fs.writeFile(filePath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/**
+ * Check if an MCP server is configured
+ *
+ * @param mcpName The MCP server name to check
+ * @param config Optional pre-loaded config (loads from file if not provided)
+ */
+export async function isMCPConfigured(
+  mcpName: string,
+  config?: PhotonMCPConfig
+): Promise<boolean> {
+  const cfg = config || await loadPhotonMCPConfig();
+  return mcpName in cfg.mcpServers;
+}
+
+/**
+ * Get configuration for a specific MCP server
+ *
+ * @param mcpName The MCP server name
+ * @param config Optional pre-loaded config
+ * @returns The server config or undefined if not found
+ */
+export async function getMCPServerConfig(
+  mcpName: string,
+  config?: PhotonMCPConfig
+): Promise<MCPServerConfig | undefined> {
+  const cfg = config || await loadPhotonMCPConfig();
+  return cfg.mcpServers[mcpName];
+}
+
+/**
+ * Add or update an MCP server configuration
+ *
+ * @param mcpName The MCP server name
+ * @param serverConfig The server configuration
+ * @param configPath Optional custom config path
+ */
+export async function setMCPServerConfig(
+  mcpName: string,
+  serverConfig: MCPServerConfig,
+  configPath?: string
+): Promise<void> {
+  const config = await loadPhotonMCPConfig(configPath);
+  config.mcpServers[mcpName] = serverConfig;
+  await savePhotonMCPConfig(config, configPath);
+}
+
+/**
+ * Remove an MCP server configuration
+ *
+ * @param mcpName The MCP server name to remove
+ * @param configPath Optional custom config path
+ */
+export async function removeMCPServerConfig(
+  mcpName: string,
+  configPath?: string
+): Promise<void> {
+  const config = await loadPhotonMCPConfig(configPath);
+  delete config.mcpServers[mcpName];
+  await savePhotonMCPConfig(config, configPath);
+}
+
+/**
+ * List all configured MCP servers
+ *
+ * @param configPath Optional custom config path
+ * @returns Array of MCP server names
+ */
+export async function listMCPServers(configPath?: string): Promise<string[]> {
+  const config = await loadPhotonMCPConfig(configPath);
+  return Object.keys(config.mcpServers);
+}
+
+/**
+ * Convert PhotonMCPConfig to MCPConfig (for SDK transport)
+ */
+export function toMCPConfig(config: PhotonMCPConfig): MCPConfig {
+  return {
+    mcpServers: config.mcpServers,
+  };
+}
+
+/**
+ * Merge environment variables into MCP server config
+ * Supports ${VAR_NAME} syntax for env var references
+ *
+ * @param serverConfig The server config to process
+ * @returns Config with env vars resolved
+ */
+export function resolveEnvVars(serverConfig: MCPServerConfig): MCPServerConfig {
+  const resolved = { ...serverConfig };
+
+  // Process env object if present
+  if (resolved.env) {
+    const processedEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(resolved.env)) {
+      processedEnv[key] = resolveEnvValue(value);
+    }
+    resolved.env = processedEnv;
+  }
+
+  // Process args if present
+  if (resolved.args) {
+    resolved.args = resolved.args.map(resolveEnvValue);
+  }
+
+  // Process url if present
+  if (resolved.url) {
+    resolved.url = resolveEnvValue(resolved.url);
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve ${VAR_NAME} references in a string value
+ */
+function resolveEnvValue(value: string): string {
+  return value.replace(/\$\{([^}]+)\}/g, (_, varName) => {
+    return process.env[varName] || '';
+  });
+}