@portel/photon-core 1.2.0 → 1.3.0

package/src/mcp-sdk-transport.ts

@@ -0,0 +1,449 @@
+/**
+ * MCP SDK Transport for Photon Core
+ *
+ * Uses the official @modelcontextprotocol/sdk for connecting to MCP servers.
+ * Supports multiple transports:
+ * - stdio: Local processes (command + args)
+ * - sse: Server-Sent Events over HTTP
+ * - streamable-http: HTTP streaming
+ * - websocket: WebSocket connections
+ *
+ * Configuration formats:
+ * 1. stdio (local process):
+ *    { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
+ *
+ * 2. sse (HTTP SSE):
+ *    { "url": "http://localhost:3000/mcp", "transport": "sse" }
+ *
+ * 3. streamable-http:
+ *    { "url": "http://localhost:3000/mcp", "transport": "streamable-http" }
+ *
+ * 4. websocket:
+ *    { "url": "ws://localhost:3000/mcp", "transport": "websocket" }
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  MCPClient,
+  MCPTransport,
+  MCPClientFactory,
+  MCPToolInfo,
+  MCPToolResult,
+  MCPNotConnectedError,
+  MCPToolError,
+  createMCPProxy,
+} from './mcp-client.js';
+
+/**
+ * MCP Server configuration
+ * Supports multiple transport types
+ */
+export interface MCPServerConfig {
+  // For stdio transport (local process)
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+
+  // For HTTP/WS transports
+  url?: string;
+  transport?: 'stdio' | 'sse' | 'streamable-http' | 'websocket';
+
+  // Authentication (for HTTP transports)
+  headers?: Record<string, string>;
+}
+
+/**
+ * Full MCP configuration file format
+ */
+export interface MCPConfig {
+  mcpServers: Record<string, MCPServerConfig>;
+}
+
+/**
+ * Manages a single MCP server connection using official SDK
+ */
+class SDKMCPConnection {
+  private client: Client | null = null;
+  private transport: any = null;
+  private tools: MCPToolInfo[] = [];
+  private initialized = false;
+
+  constructor(
+    private name: string,
+    private config: MCPServerConfig,
+    private verbose: boolean = false
+  ) {}
+
+  private log(message: string): void {
+    if (this.verbose) {
+      console.error(`[MCP:${this.name}] ${message}`);
+    }
+  }
+
+  /**
+   * Create appropriate transport based on config
+   */
+  private createTransport(): any {
+    const transportType = this.config.transport || (this.config.command ? 'stdio' : 'sse');
+
+    switch (transportType) {
+      case 'stdio': {
+        if (!this.config.command) {
+          throw new Error(`stdio transport requires 'command' in config for ${this.name}`);
+        }
+        this.log(`Creating stdio transport: ${this.config.command} ${(this.config.args || []).join(' ')}`);
+        return new StdioClientTransport({
+          command: this.config.command,
+          args: this.config.args,
+          cwd: this.config.cwd,
+          env: this.config.env,
+        });
+      }
+
+      case 'sse': {
+        if (!this.config.url) {
+          throw new Error(`sse transport requires 'url' in config for ${this.name}`);
+        }
+        this.log(`Creating SSE transport: ${this.config.url}`);
+        return new SSEClientTransport(new URL(this.config.url), {
+          requestInit: this.config.headers ? { headers: this.config.headers } : undefined,
+        });
+      }
+
+      case 'streamable-http': {
+        if (!this.config.url) {
+          throw new Error(`streamable-http transport requires 'url' in config for ${this.name}`);
+        }
+        this.log(`Creating streamable HTTP transport: ${this.config.url}`);
+        return new StreamableHTTPClientTransport(new URL(this.config.url), {
+          requestInit: this.config.headers ? { headers: this.config.headers } : undefined,
+        });
+      }
+
+      case 'websocket': {
+        if (!this.config.url) {
+          throw new Error(`websocket transport requires 'url' in config for ${this.name}`);
+        }
+        this.log(`Creating WebSocket transport: ${this.config.url}`);
+        return new WebSocketClientTransport(new URL(this.config.url));
+      }
+
+      default:
+        throw new Error(`Unknown transport type: ${transportType}`);
+    }
+  }
+
+  /**
+   * Connect to the MCP server
+   */
+  async connect(): Promise<void> {
+    if (this.client) {
+      return; // Already connected
+    }
+
+    this.transport = this.createTransport();
+    this.client = new Client(
+      {
+        name: 'photon-core',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          roots: { listChanged: false },
+        },
+      }
+    );
+
+    this.log('Connecting...');
+    await this.client.connect(this.transport);
+    this.log('Connected');
+
+    // List available tools
+    const toolsResult = await this.client.listTools();
+    this.tools = (toolsResult.tools || []).map((t: any) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    }));
+
+    this.log(`Loaded ${this.tools.length} tools`);
+    this.initialized = true;
+  }
+
+  /**
+   * Call a tool
+   */
+  async callTool(toolName: string, parameters: Record<string, any>): Promise<MCPToolResult> {
+    if (!this.client || !this.initialized) {
+      throw new MCPNotConnectedError(this.name);
+    }
+
+    try {
+      const result = await this.client.callTool({
+        name: toolName,
+        arguments: parameters,
+      });
+
+      // Convert to MCPToolResult format
+      if (result?.content && Array.isArray(result.content)) {
+        return {
+          content: result.content.map((c: any) => ({
+            type: c.type || 'text',
+            text: c.text,
+            data: c.data,
+            mimeType: c.mimeType,
+          })),
+          isError: result.isError as boolean | undefined,
+        };
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: typeof result === 'string' ? result : JSON.stringify(result),
+        }],
+        isError: false,
+      };
+    } catch (error: any) {
+      throw new MCPToolError(this.name, toolName, error.message);
+    }
+  }
+
+  /**
+   * List available tools
+   */
+  listTools(): MCPToolInfo[] {
+    return this.tools;
+  }
+
+  /**
+   * Check if connected
+   */
+  isConnected(): boolean {
+    return this.initialized && this.client !== null;
+  }
+
+  /**
+   * Disconnect
+   */
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      this.log('Disconnecting...');
+      await this.client.close();
+      this.client = null;
+      this.transport = null;
+      this.initialized = false;
+    }
+  }
+}
+
+/**
+ * SDK-based MCP Transport using official @modelcontextprotocol/sdk
+ */
+export class SDKMCPTransport implements MCPTransport {
+  private connections: Map<string, SDKMCPConnection> = new Map();
+
+  constructor(
+    private config: MCPConfig,
+    private verbose: boolean = false
+  ) {}
+
+  private log(message: string): void {
+    if (this.verbose) {
+      console.error(`[MCPTransport] ${message}`);
+    }
+  }
+
+  /**
+   * Get or create connection to an MCP server
+   */
+  private async getConnection(mcpName: string): Promise<SDKMCPConnection> {
+    let connection = this.connections.get(mcpName);
+
+    if (connection?.isConnected()) {
+      return connection;
+    }
+
+    const serverConfig = this.config.mcpServers[mcpName];
+    if (!serverConfig) {
+      throw new MCPNotConnectedError(mcpName);
+    }
+
+    connection = new SDKMCPConnection(mcpName, serverConfig, this.verbose);
+    await connection.connect();
+    this.connections.set(mcpName, connection);
+
+    return connection;
+  }
+
+  async callTool(mcpName: string, toolName: string, parameters: Record<string, any>): Promise<MCPToolResult> {
+    const connection = await this.getConnection(mcpName);
+    return connection.callTool(toolName, parameters);
+  }
+
+  async listTools(mcpName: string): Promise<MCPToolInfo[]> {
+    const connection = await this.getConnection(mcpName);
+    return connection.listTools();
+  }
+
+  async isConnected(mcpName: string): Promise<boolean> {
+    if (!this.config.mcpServers[mcpName]) {
+      return false;
+    }
+    const connection = this.connections.get(mcpName);
+    return connection?.isConnected() ?? false;
+  }
+
+  listServers(): string[] {
+    return Object.keys(this.config.mcpServers);
+  }
+
+  async disconnectAll(): Promise<void> {
+    for (const connection of this.connections.values()) {
+      await connection.disconnect();
+    }
+    this.connections.clear();
+  }
+}
+
+/**
+ * SDK-based MCP Client Factory
+ */
+export class SDKMCPClientFactory implements MCPClientFactory {
+  private transport: SDKMCPTransport;
+
+  constructor(config: MCPConfig, verbose: boolean = false) {
+    this.transport = new SDKMCPTransport(config, verbose);
+  }
+
+  create(mcpName: string): MCPClient {
+    return new MCPClient(mcpName, this.transport);
+  }
+
+  async listServers(): Promise<string[]> {
+    return this.transport.listServers();
+  }
+
+  async disconnect(): Promise<void> {
+    await this.transport.disconnectAll();
+  }
+
+  getTransport(): SDKMCPTransport {
+    return this.transport;
+  }
+}
+
+/**
+ * Resolve an MCP source to a runnable configuration
+ * Handles: GitHub shorthand, npm packages, URLs, local paths
+ */
+export function resolveMCPSource(
+  name: string,
+  source: string,
+  sourceType: 'github' | 'npm' | 'url' | 'local'
+): MCPServerConfig {
+  switch (sourceType) {
+    case 'npm': {
+      // npm:@scope/package or npm:package
+      const packageName = source.replace(/^npm:/, '');
+      return {
+        command: 'npx',
+        args: ['-y', packageName],
+        transport: 'stdio',
+      };
+    }
+
+    case 'github': {
+      // GitHub shorthand: owner/repo
+      // Try to run via npx assuming it's published to npm
+      return {
+        command: 'npx',
+        args: ['-y', `@${source}`],
+        transport: 'stdio',
+      };
+    }
+
+    case 'url': {
+      // Full URL - determine transport from protocol
+      if (source.startsWith('ws://') || source.startsWith('wss://')) {
+        return {
+          url: source,
+          transport: 'websocket',
+        };
+      }
+      // Default to SSE for HTTP URLs
+      return {
+        url: source,
+        transport: 'sse',
+      };
+    }
+
+    case 'local': {
+      // Local path - run directly with node
+      const resolvedPath = source.replace(/^~/, process.env.HOME || '');
+      return {
+        command: 'node',
+        args: [resolvedPath],
+        transport: 'stdio',
+      };
+    }
+
+    default:
+      throw new Error(`Unknown MCP source type: ${sourceType}`);
+  }
+}
+
+/**
+ * Load MCP configuration from standard locations
+ */
+export async function loadMCPConfig(verbose: boolean = false): Promise<MCPConfig> {
+  const log = verbose ? (msg: string) => console.error(`[MCPConfig] ${msg}`) : () => {};
+
+  const configPaths = [
+    process.env.PHOTON_MCP_CONFIG,
+    path.join(process.cwd(), 'photon.mcp.json'),
+    path.join(os.homedir(), '.config', 'photon', 'mcp.json'),
+    path.join(os.homedir(), '.photon', 'mcp.json'),
+  ].filter(Boolean) as string[];
+
+  for (const configPath of configPaths) {
+    try {
+      const content = await fs.readFile(configPath, 'utf-8');
+      const config = JSON.parse(content) as MCPConfig;
+
+      if (config.mcpServers && typeof config.mcpServers === 'object') {
+        log(`Loaded MCP config from ${configPath}`);
+        log(`Found ${Object.keys(config.mcpServers).length} MCP servers`);
+        return config;
+      }
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        log(`Failed to load ${configPath}: ${error.message}`);
+      }
+    }
+  }
+
+  log('No MCP config found, MCP access will be unavailable');
+  return { mcpServers: {} };
+}
+
+/**
+ * Create an SDK-based MCP client factory from default config
+ */
+export async function createSDKMCPClientFactory(
+  verbose: boolean = false
+): Promise<SDKMCPClientFactory> {
+  const config = await loadMCPConfig(verbose);
+  return new SDKMCPClientFactory(config, verbose);
+}
+
+// Re-export for convenience
+export { MCPClient, createMCPProxy };

package/src/schema-extractor.ts

@@ -10,7 +10,7 @@
 
 import * as fs from 'fs/promises';
 import * as ts from 'typescript';
-import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo } from './types.js';
+import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency } from './types.js';
 
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
@@ -876,4 +876,74 @@ export class SchemaExtractor {
 
     return yields;
   }
+
+  /**
+   * Extract MCP dependencies from source code
+   * Parses @mcp tags in file-level or class-level JSDoc comments
+   *
+   * Format: @mcp <name> <source>
+   *
+   * Source formats:
+   * - GitHub shorthand: anthropics/mcp-server-github
+   * - npm package: npm:@modelcontextprotocol/server-filesystem
+   * - Local path: ./my-local-mcp or /absolute/path
+   * - Full URL: https://github.com/user/repo
+   *
+   * Example:
+   * ```
+   * /**
+   *  * @mcp github anthropics/mcp-server-github
+   *  * @mcp fs npm:@modelcontextprotocol/server-filesystem
+   *  *\/
+   * ```
+   */
+  extractMCPDependencies(source: string): MCPDependency[] {
+    const dependencies: MCPDependency[] = [];
+
+    // Match @mcp <name> <source> pattern
+    // Supports multiline JSDoc comments
+    const mcpRegex = /@mcp\s+(\w+)\s+([^\s*]+(?:\s+[^\s*@][^\s*]*)*)/g;
+
+    let match;
+    while ((match = mcpRegex.exec(source)) !== null) {
+      const [, name, rawSource] = match;
+      const source = rawSource.trim();
+
+      // Determine source type
+      const sourceType = this.classifyMCPSource(source);
+
+      dependencies.push({
+        name,
+        source,
+        sourceType,
+      });
+    }
+
+    return dependencies;
+  }
+
+  /**
+   * Classify MCP source type based on format
+   */
+  private classifyMCPSource(source: string): 'github' | 'npm' | 'url' | 'local' {
+    // npm package: npm:@scope/package or npm:package
+    if (source.startsWith('npm:')) {
+      return 'npm';
+    }
+
+    // Full URL
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+      return 'url';
+    }
+
+    // Local path (relative or absolute)
+    if (source.startsWith('./') || source.startsWith('../') ||
+        source.startsWith('/') || source.startsWith('~') ||
+        /^[A-Za-z]:[\\/]/.test(source)) {
+      return 'local';
+    }
+
+    // Default: GitHub shorthand (owner/repo)
+    return 'github';
+  }
 }

package/src/types.ts

@@ -69,6 +69,40 @@ export interface ConstructorParam {
   defaultValue?: any;
 }
 
+/**
+ * MCP Dependency declaration from @mcp tag
+ * Format: @mcp <name> <source>
+ *
+ * Source formats (following marketplace conventions):
+ * - GitHub shorthand: anthropics/mcp-server-github
+ * - npm package: npm:@modelcontextprotocol/server-filesystem
+ * - Local path: ./my-local-mcp
+ * - Full URL: https://github.com/user/repo
+ *
+ * Example:
+ * ```typescript
+ * /**
+ *  * @mcp github anthropics/mcp-server-github
+ *  * @mcp fs npm:@modelcontextprotocol/server-filesystem
+ *  *\/
+ * export default class MyPhoton extends PhotonMCP {
+ *   async doSomething() {
+ *     const issues = await this.github.list_issues({ repo: 'owner/repo' });
+ *   }
+ * }
+ * ```
+ */
+export interface MCPDependency {
+  /** Local name to use for accessing this MCP (e.g., 'github') */
+  name: string;
+  /** Source identifier (GitHub shorthand, npm package, URL, or path) */
+  source: string;
+  /** Resolved source type */
+  sourceType: 'github' | 'npm' | 'url' | 'local';
+  /** Environment variables to pass (from @env tags) */
+  env?: Record<string, string>;
+}
+
 /**
  * Template type - for text generation with variable substitution
  * Maps to MCP Prompts, HTTP template endpoints, CLI help generators, etc.