@portel/photon-core 1.2.0 → 1.3.0

package/README.md

@@ -200,6 +200,87 @@ await depManager.clearAllCache();
 
 ---
 
+### MCP SDK Transport
+
+Connect to external MCPs using the official `@modelcontextprotocol/sdk`. Supports multiple transports:
+
+```typescript
+import {
+  SDKMCPClientFactory,
+  SDKMCPTransport,
+  loadMCPConfig,
+  createSDKMCPClientFactory,
+  resolveMCPSource
+} from '@portel/photon-core';
+
+// Create from config
+const config = {
+  mcpServers: {
+    // stdio transport (local process)
+    github: {
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-github'],
+      env: { GITHUB_TOKEN: 'your-token' }
+    },
+    // SSE transport (HTTP)
+    remote: {
+      url: 'http://localhost:3000/mcp',
+      transport: 'sse'
+    },
+    // WebSocket transport
+    realtime: {
+      url: 'ws://localhost:8080/mcp',
+      transport: 'websocket'
+    },
+    // Streamable HTTP transport
+    streaming: {
+      url: 'http://localhost:3000/mcp',
+      transport: 'streamable-http'
+    }
+  }
+};
+
+const factory = new SDKMCPClientFactory(config);
+const github = factory.create('github');
+
+// List tools
+const tools = await github.list();
+
+// Call a tool
+const issues = await github.call('list_issues', { repo: 'owner/repo' });
+
+// Or use the proxy for fluent API
+import { createMCPProxy } from '@portel/photon-core';
+const githubProxy = createMCPProxy(github);
+const issues = await githubProxy.list_issues({ repo: 'owner/repo' });
+```
+
+**Transport Types:**
+
+| Transport | Config | Use Case |
+|-----------|--------|----------|
+| `stdio` | `command`, `args` | Local CLI-based MCPs |
+| `sse` | `url`, `transport: 'sse'` | HTTP Server-Sent Events |
+| `streamable-http` | `url`, `transport: 'streamable-http'` | HTTP streaming |
+| `websocket` | `url`, `transport: 'websocket'` | WebSocket connections |
+
+**Helper Functions:**
+
+```typescript
+// Load config from standard locations
+// Checks: PHOTON_MCP_CONFIG env, ./photon.mcp.json, ~/.config/photon/mcp.json
+const config = await loadMCPConfig();
+
+// Create factory from default config
+const factory = await createSDKMCPClientFactory();
+
+// Resolve marketplace sources to config
+const config = resolveMCPSource('github', 'anthropics/mcp-server-github', 'github');
+// → { command: 'npx', args: ['-y', '@anthropics/mcp-server-github'], transport: 'stdio' }
+```
+
+---
+
 ### `SchemaExtractor`
 
 Extracts JSON schemas from TypeScript method signatures and JSDoc comments.

package/dist/base.d.ts

@@ -26,7 +26,19 @@
  *   }
  * }
  * ```
+ *
+ * With MCP access (requires runtime support):
+ * ```typescript
+ * export default class SlackReporter extends PhotonMCP {
+ *   async report() {
+ *     const github = this.mcp('github');
+ *     const issues = await github.call('list_issues', { repo: 'foo/bar' });
+ *     // Or with proxy: await github.list_issues({ repo: 'foo/bar' })
+ *   }
+ * }
+ * ```
  */
+import { MCPClient, MCPClientFactory } from './mcp-client.js';
 /**
  * Simple base class for creating Photon MCPs
  *
@@ -35,6 +47,16 @@
  * - Return value = Tool result
  */
 export declare class PhotonMCP {
+    /**
+     * MCP client factory - injected by runtime
+     * @internal
+     */
+    protected _mcpFactory?: MCPClientFactory;
+    /**
+     * Cache of MCP client instances
+     * @internal
+     */
+    private _mcpClients;
     /**
      * Get MCP name from class name
      * Converts PascalCase to kebab-case (e.g., MyAwesomeMCP → my-awesome-mcp)
@@ -54,5 +76,50 @@ export declare class PhotonMCP {
      */
     onInitialize?(): Promise<void>;
     onShutdown?(): Promise<void>;
+    /**
+     * Get an MCP client for calling external MCP servers
+     *
+     * Enables Photons to call tools on other MCP servers via the MCP protocol.
+     * This is language-agnostic - the MCP can be written in any language
+     * (Python, Rust, Go, etc.) as long as it speaks MCP protocol.
+     *
+     * @param mcpName The name of the MCP server to connect to
+     * @returns MCP client with call(), list(), find() methods, plus proxy for direct tool calls
+     *
+     * @example
+     * ```typescript
+     * // Using call() method
+     * const github = this.mcp('github');
+     * const issues = await github.call('list_issues', { repo: 'owner/repo' });
+     *
+     * // Using proxy (tool name as method)
+     * const issues = await github.list_issues({ repo: 'owner/repo' });
+     *
+     * // Listing available tools
+     * const tools = await github.list();
+     *
+     * // Finding tools
+     * const issueTools = await github.find('issue');
+     * ```
+     *
+     * @throws Error if MCP factory is not set (runtime doesn't support MCP access)
+     */
+    mcp(mcpName: string): MCPClient & Record<string, (params?: any) => Promise<any>>;
+    /**
+     * Set the MCP client factory
+     * Called by the runtime to enable MCP access
+     *
+     * @internal
+     */
+    setMCPFactory(factory: MCPClientFactory): void;
+    /**
+     * Check if MCP access is available
+     */
+    hasMCPAccess(): boolean;
+    /**
+     * List all available MCP servers
+     * Requires MCP factory to be set
+     */
+    listMCPServers(): Promise<string[]>;
 }
 //# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM;IAQ3B;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,MAAM,EAAE;IA0BjC;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBlE;;OAEG;IACG,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAC9B,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CACnC"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAkB,MAAM,iBAAiB,CAAC;AAE9E;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB;;;OAGG;IACH,SAAS,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAEzC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAsF;IAEzG;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM;IAQ3B;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,MAAM,EAAE;IA0BjC;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBlE;;OAEG;IACG,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAC9B,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAoBhF;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAM9C;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAM1C"}

package/dist/base.js

@@ -26,7 +26,19 @@
  *   }
  * }
  * ```
+ *
+ * With MCP access (requires runtime support):
+ * ```typescript
+ * export default class SlackReporter extends PhotonMCP {
+ *   async report() {
+ *     const github = this.mcp('github');
+ *     const issues = await github.call('list_issues', { repo: 'foo/bar' });
+ *     // Or with proxy: await github.list_issues({ repo: 'foo/bar' })
+ *   }
+ * }
+ * ```
  */
+import { createMCPProxy } from './mcp-client.js';
 /**
  * Simple base class for creating Photon MCPs
  *
@@ -35,6 +47,16 @@
  * - Return value = Tool result
  */
 export class PhotonMCP {
+    /**
+     * MCP client factory - injected by runtime
+     * @internal
+     */
+    _mcpFactory;
+    /**
+     * Cache of MCP client instances
+     * @internal
+     */
+    _mcpClients = new Map();
     /**
      * Get MCP name from class name
      * Converts PascalCase to kebab-case (e.g., MyAwesomeMCP → my-awesome-mcp)
@@ -88,5 +110,75 @@ export class PhotonMCP {
             throw error;
         }
     }
+    /**
+     * Get an MCP client for calling external MCP servers
+     *
+     * Enables Photons to call tools on other MCP servers via the MCP protocol.
+     * This is language-agnostic - the MCP can be written in any language
+     * (Python, Rust, Go, etc.) as long as it speaks MCP protocol.
+     *
+     * @param mcpName The name of the MCP server to connect to
+     * @returns MCP client with call(), list(), find() methods, plus proxy for direct tool calls
+     *
+     * @example
+     * ```typescript
+     * // Using call() method
+     * const github = this.mcp('github');
+     * const issues = await github.call('list_issues', { repo: 'owner/repo' });
+     *
+     * // Using proxy (tool name as method)
+     * const issues = await github.list_issues({ repo: 'owner/repo' });
+     *
+     * // Listing available tools
+     * const tools = await github.list();
+     *
+     * // Finding tools
+     * const issueTools = await github.find('issue');
+     * ```
+     *
+     * @throws Error if MCP factory is not set (runtime doesn't support MCP access)
+     */
+    mcp(mcpName) {
+        if (!this._mcpFactory) {
+            throw new Error(`MCP access not available. To use this.mcp('${mcpName}'), the Photon must be run in a runtime that supports MCP access (e.g., NCP with MCP servers configured).`);
+        }
+        // Return cached client if available
+        let client = this._mcpClients.get(mcpName);
+        if (client) {
+            return client;
+        }
+        // Create new client and cache it
+        const rawClient = this._mcpFactory.create(mcpName);
+        client = createMCPProxy(rawClient);
+        this._mcpClients.set(mcpName, client);
+        return client;
+    }
+    /**
+     * Set the MCP client factory
+     * Called by the runtime to enable MCP access
+     *
+     * @internal
+     */
+    setMCPFactory(factory) {
+        this._mcpFactory = factory;
+        // Clear cached clients when factory changes
+        this._mcpClients.clear();
+    }
+    /**
+     * Check if MCP access is available
+     */
+    hasMCPAccess() {
+        return !!this._mcpFactory;
+    }
+    /**
+     * List all available MCP servers
+     * Requires MCP factory to be set
+     */
+    async listMCPServers() {
+        if (!this._mcpFactory) {
+            return [];
+        }
+        return this._mcpFactory.listServers();
+    }
 }
 //# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IACpB;;;OAGG;IACH,MAAM,CAAC,UAAU;QACf,OAAO,IAAI,CAAC,IAAI;aACb,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,iCAAiC;aACrD,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;aAC1B,WAAW,EAAE;aACb,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,sBAAsB;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,cAAc;QACnB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,MAAM,OAAO,GAAa,EAAE,CAAC;QAE7B,8CAA8C;QAC9C,IAAI,OAAO,GAAG,SAAS,CAAC;QACxB,OAAO,OAAO,IAAI,OAAO,KAAK,SAAS,CAAC,SAAS,EAAE,CAAC;YAClD,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACnD,2EAA2E;gBAC3E,IACE,IAAI,KAAK,aAAa;oBACtB,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;oBACrB,IAAI,KAAK,cAAc;oBACvB,IAAI,KAAK,YAAY;oBACrB,OAAQ,SAAiB,CAAC,IAAI,CAAC,KAAK,UAAU;oBAC9C,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EACvB,CAAC;oBACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC,CAAC;YACH,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,QAAgB,EAAE,UAAe;QACjD,MAAM,MAAM,GAAI,IAAY,CAAC,QAAQ,CAAC,CAAC;QAEvC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACnD,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,0BAA0B,QAAQ,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACvE,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CAOF"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -38,6 +38,8 @@ export { SchemaExtractor } from './schema-extractor.js';
 export { formatOutput, detectFormat, renderPrimitive, renderList, renderTable, renderTree, renderNone, formatKey, formatValue, formatToMimeType, printSuccess, printError, printInfo, printWarning, printHeader, STATUS, } from './cli-formatter.js';
 export { resolvePath, listFiles, ensureDir, resolvePhotonPath, listPhotonFiles, ensurePhotonDir, DEFAULT_PHOTON_DIR, type ResolverOptions, } from './path-resolver.js';
 export * from './types.js';
+export { MCPClient, MCPError, MCPNotConnectedError, MCPToolError, createMCPProxy, type MCPToolInfo, type MCPToolResult, type MCPTransport, type MCPClientFactory, } from './mcp-client.js';
+export { SDKMCPTransport, SDKMCPClientFactory, loadMCPConfig, createSDKMCPClientFactory, resolveMCPSource, type MCPServerConfig, type MCPConfig, } from './mcp-sdk-transport.js';
 export { isAskYield, isEmitYield, getAskType, getEmitType, isAsyncGeneratorFunction, isAsyncGenerator, executeGenerator, extractAsks, createPrefilledProvider, NeedsInputError, wrapAsGenerator, type AskYield, type AskText, type AskPassword, type AskConfirm, type AskSelect, type AskNumber, type AskFile, type AskDate, type EmitYield, type EmitStatus, type EmitProgress, type EmitStream, type EmitLog, type EmitToast, type EmitThinking, type EmitArtifact, type PhotonYield, type InputProvider, type OutputHandler, type GeneratorExecutorConfig, type ExtractedAsk, isInputYield, isProgressYield, isStreamYield, isLogYield, extractYields, type PromptYield, type ConfirmYield, type SelectYield, type ProgressYield, type StreamYield, type LogYield, type ExtractedYield, } from './generator.js';
 export { prompt, confirm, elicit, elicitReadline, elicitNativeDialog, setPromptHandler, getPromptHandler, setElicitHandler, getElicitHandler, type ElicitOptions, type ElicitResult, type ElicitHandler, type PromptHandler, } from './elicit.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAG5B,cAAc,YAAY,CAAC;AAI3B,OAAO,EAEL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EAGX,wBAAwB,EACxB,gBAAgB,EAGhB,gBAAgB,EAGhB,WAAW,EAGX,uBAAuB,EACvB,eAAe,EAGf,eAAe,EAGf,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,OAAO,EAGZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EAGjB,KAAK,WAAW,EAGhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EAGjB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAEL,MAAM,EACN,OAAO,EAEP,MAAM,EACN,cAAc,EACd,kBAAkB,EAElB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAEhB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAG5B,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,QAAQ,EACR,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,yBAAyB,EACzB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAEL,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EAGX,wBAAwB,EACxB,gBAAgB,EAGhB,gBAAgB,EAGhB,WAAW,EAGX,uBAAuB,EACvB,eAAe,EAGf,eAAe,EAGf,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,OAAO,EAGZ,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,YAAY,EAGjB,KAAK,WAAW,EAGhB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EAGjB,YAAY,EACZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAEL,MAAM,EACN,OAAO,EAEP,MAAM,EACN,cAAc,EACd,kBAAkB,EAElB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAEhB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -44,6 +44,10 @@ export { formatOutput, detectFormat, renderPrimitive, renderList, renderTable, r
 export { resolvePath, listFiles, ensureDir, resolvePhotonPath, listPhotonFiles, ensurePhotonDir, DEFAULT_PHOTON_DIR, } from './path-resolver.js';
 // Types
 export * from './types.js';
+// MCP Protocol Client - for calling external MCPs from Photons
+export { MCPClient, MCPError, MCPNotConnectedError, MCPToolError, createMCPProxy, } from './mcp-client.js';
+// MCP SDK Transport - official SDK-based transport implementation
+export { SDKMCPTransport, SDKMCPClientFactory, loadMCPConfig, createSDKMCPClientFactory, resolveMCPSource, } from './mcp-sdk-transport.js';
 // Generator-based tools with ask/emit pattern
 // See generator.ts for comprehensive documentation
 export { 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,wBAAwB;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAE5B,kBAAkB;AAClB,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,QAAQ;AACR,cAAc,YAAY,CAAC;AAE3B,8CAA8C;AAC9C,mDAAmD;AACnD,OAAO;AACL,sCAAsC;AACtC,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW;AAEX,sBAAsB;AACtB,wBAAwB,EACxB,gBAAgB;AAEhB,2CAA2C;AAC3C,gBAAgB;AAEhB,kDAAkD;AAClD,WAAW;AAEX,qBAAqB;AACrB,uBAAuB,EACvB,eAAe;AAEf,UAAU;AACV,eAAe;AA+Bf,oCAAoC;AACpC,YAAY,EACZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,GAQd,MAAM,gBAAgB,CAAC;AAExB,iEAAiE;AACjE,OAAO;AACL,uDAAuD;AACvD,MAAM,EACN,OAAO;AACP,2BAA2B;AAC3B,MAAM,EACN,cAAc,EACd,kBAAkB;AAClB,oCAAoC;AACpC,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GAMjB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,wBAAwB;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,GACP,MAAM,oBAAoB,CAAC;AAE5B,kBAAkB;AAClB,OAAO,EACL,WAAW,EACX,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAE5B,QAAQ;AACR,cAAc,YAAY,CAAC;AAE3B,+DAA+D;AAC/D,OAAO,EACL,SAAS,EACT,QAAQ,EACR,oBAAoB,EACpB,YAAY,EACZ,cAAc,GAKf,MAAM,iBAAiB,CAAC;AAEzB,kEAAkE;AAClE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,yBAAyB,EACzB,gBAAgB,GAGjB,MAAM,wBAAwB,CAAC;AAEhC,8CAA8C;AAC9C,mDAAmD;AACnD,OAAO;AACL,sCAAsC;AACtC,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW;AAEX,sBAAsB;AACtB,wBAAwB,EACxB,gBAAgB;AAEhB,2CAA2C;AAC3C,gBAAgB;AAEhB,kDAAkD;AAClD,WAAW;AAEX,qBAAqB;AACrB,uBAAuB,EACvB,eAAe;AAEf,UAAU;AACV,eAAe;AA+Bf,oCAAoC;AACpC,YAAY,EACZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,GAQd,MAAM,gBAAgB,CAAC;AAExB,iEAAiE;AACjE,OAAO;AACL,uDAAuD;AACvD,MAAM,EACN,OAAO;AACP,2BAA2B;AAC3B,MAAM,EACN,cAAc,EACd,kBAAkB;AAClB,oCAAoC;AACpC,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GAMjB,MAAM,aAAa,CAAC"}

package/dist/mcp-client.d.ts

@@ -0,0 +1,179 @@
+/**
+ * MCP Protocol Client for Photons
+ *
+ * Enables Photons to call external MCPs via the MCP protocol.
+ * This is runtime-agnostic - the actual transport is provided by the runtime (NCP, Lumina, etc.)
+ *
+ * Usage in Photon:
+ * ```typescript
+ * export default class MyPhoton extends PhotonMCP {
+ *   async doSomething() {
+ *     const github = this.mcp('github');
+ *     const issues = await github.call('list_issues', { repo: 'foo/bar' });
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Tool information returned from MCP discovery
+ */
+export interface MCPToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: {
+        type: 'object';
+        properties?: Record<string, any>;
+        required?: string[];
+    };
+}
+/**
+ * Result from an MCP tool call
+ */
+export interface MCPToolResult {
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Interface that runtimes must implement to provide MCP connectivity
+ * This keeps photon-core runtime-agnostic
+ */
+export interface MCPTransport {
+    /**
+     * Call a tool on an MCP server
+     * @param mcpName The MCP server name
+     * @param toolName The tool to call
+     * @param parameters Tool parameters
+     */
+    callTool(mcpName: string, toolName: string, parameters: Record<string, any>): Promise<MCPToolResult>;
+    /**
+     * List available tools on an MCP server
+     * @param mcpName The MCP server name
+     */
+    listTools(mcpName: string): Promise<MCPToolInfo[]>;
+    /**
+     * Check if an MCP server is connected/available
+     * @param mcpName The MCP server name
+     */
+    isConnected(mcpName: string): Promise<boolean>;
+}
+/**
+ * Factory interface for creating MCP clients
+ * Runtimes implement this to provide MCP access to Photons
+ */
+export interface MCPClientFactory {
+    /**
+     * Create an MCP client for a specific server
+     * @param mcpName The MCP server name
+     */
+    create(mcpName: string): MCPClient;
+    /**
+     * List all available MCP servers
+     */
+    listServers(): Promise<string[]>;
+}
+/**
+ * MCP Client - Protocol wrapper for calling external MCPs
+ *
+ * Provides a clean async interface for Photons to call MCP tools.
+ * The actual protocol communication is handled by the transport layer.
+ */
+export declare class MCPClient {
+    private mcpName;
+    private transport;
+    private toolsCache;
+    constructor(mcpName: string, transport: MCPTransport);
+    /**
+     * Get the MCP server name
+     */
+    get name(): string;
+    /**
+     * Call a tool on this MCP server
+     *
+     * @param toolName The tool to call
+     * @param parameters Tool parameters
+     * @returns Tool result (parsed from MCP response)
+     *
+     * @example
+     * ```typescript
+     * const github = this.mcp('github');
+     * const issues = await github.call('list_issues', { repo: 'owner/repo', state: 'open' });
+     * ```
+     */
+    call(toolName: string, parameters?: Record<string, any>): Promise<any>;
+    /**
+     * List all available tools on this MCP server
+     *
+     * @returns Array of tool information
+     *
+     * @example
+     * ```typescript
+     * const github = this.mcp('github');
+     * const tools = await github.list();
+     * // [{ name: 'list_issues', description: '...' }, ...]
+     * ```
+     */
+    list(): Promise<MCPToolInfo[]>;
+    /**
+     * Find tools matching a query
+     *
+     * @param query Search query (matches name or description)
+     * @returns Matching tools
+     *
+     * @example
+     * ```typescript
+     * const github = this.mcp('github');
+     * const issueTools = await github.find('issue');
+     * ```
+     */
+    find(query: string): Promise<MCPToolInfo[]>;
+    /**
+     * Check if this MCP server is connected
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Clear the tools cache (useful after reconnection)
+     */
+    clearCache(): void;
+    /**
+     * Parse MCP tool result into a usable value
+     */
+    private parseResult;
+}
+/**
+ * Base class for MCP-related errors
+ */
+export declare class MCPError extends Error {
+    readonly mcpName: string;
+    constructor(mcpName: string, message: string);
+}
+/**
+ * Error thrown when MCP server is not connected
+ */
+export declare class MCPNotConnectedError extends MCPError {
+    constructor(mcpName: string);
+}
+/**
+ * Error thrown when MCP tool call fails
+ */
+export declare class MCPToolError extends MCPError {
+    readonly toolName: string;
+    readonly details: string;
+    constructor(mcpName: string, toolName: string, details: string);
+}
+/**
+ * Create a proxy-based MCP client that allows direct method calls
+ *
+ * This enables a more fluent API:
+ * ```typescript
+ * const github = this.mcp('github');
+ * // Instead of: await github.call('list_issues', { repo: 'foo/bar' })
+ * // You can do: await github.list_issues({ repo: 'foo/bar' })
+ * ```
+ */
+export declare function createMCPProxy(client: MCPClient): MCPClient & Record<string, (params?: any) => Promise<any>>;
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/mcp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"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"}