@portel/photon 1.33.1 → 1.33.2

package/README.md

@@ -10,13 +10,15 @@
 [![Node](https://img.shields.io/badge/node-%3E%3D20-43853d.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)
 
-### Define intent once. Deliver everywhere.
+### Build MCP apps from TypeScript methods.
 
-Photon turns a single TypeScript file into:
+Define the capability once. Photon turns it into the interfaces people now
+expect around AI tools:
 
-- **MCP server** for AI agents  
-- **CLI tool** for automation  
-- **Web interface** for humans
+- **MCP server** for Claude, ChatGPT, Cursor, and agents
+- **Embedded app UI** for chat clients that support MCP app resources
+- **CLI tool** for scripts, demos, and automation
+- **Beam web interface** for humans
 
 Photon is free and open source software released under the [MIT license](./LICENSE).
 
@@ -24,6 +26,36 @@ Photon is free and open source software released under the [MIT license](./LICEN
 
 ---
 
+## From one method to every surface
+
+The weather example is intentionally small: one TypeScript method, a few
+docblock tags, and one `@ui` HTML asset. Photon turns that into a CLI command,
+Beam UI, MCP tool, and embedded app surface for MCP app-capable chat clients.
+Claude Desktop can run it from a local stdio MCP command; ChatGPT developer
+mode can connect to the same Photon over a public HTTPS `/mcp` endpoint.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/photon-surface-map.svg" alt="Infographic showing one Photon method becoming CLI, Beam, MCP, Claude Desktop, ChatGPT, and other agent surfaces" width="100%">
+</div>
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/chat-clients-photon-weather-showcase.gif" alt="Animated Photon weather showcase with matched ChatGPT and Claude Desktop MCP app demos" width="100%">
+</div>
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/weather-showcase-hero.png" alt="Photon weather showcase: one method rendered across Beam, CLI, and chat app surfaces" width="100%">
+</div>
+
+[Follow the step-by-step tutorial](./docs/tutorials/from-method-to-chat-app.md)
+or open the runnable example in
+[`examples/weather-showcase`](./examples/weather-showcase).
+Real-client proof is included for
+[Claude Desktop](https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/claude-weather-real.png)
+and
+[ChatGPT developer mode](https://raw.githubusercontent.com/portel-dev/photon/main/assets/showcase/weather/chatgpt-photon-weather-local-dot.png).
+
+---
+
 ## One definition. Multiple interfaces.
 
 <div align="center">
@@ -575,6 +607,7 @@ Uses Bun's compiler under the hood. The binary bundles the photon, its `@depende
 | Guide | |
 |---|---|
 | [Getting Started](./docs/getting-started.md) | Install, build, and run your first photon in 5 minutes |
+| [From Method to Chat App](./docs/tutorials/from-method-to-chat-app.md) | Weather showcase: CLI, Beam, MCP, and embedded app UI from one method |
 | [Core Concepts](./docs/concepts.md) | The 6 ideas behind Photon |
 | [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) | Public reference for every docblock tag Photon understands |
 | [Output Formats](./docs/formats.md) | Visual gallery of every `@format` type |

package/dist/auto-ui/frontend/pure-view.html

@@ -236,9 +236,12 @@
         // Handle JSON-RPC tools/call from bridge and form components
         if (msg.jsonrpc === '2.0' && msg.method === 'tools/call' && msg.id != null) {
           var rawName = (msg.params && msg.params.name) || '';
-          // Don't double-prefix: invoke-form sends fully-qualified names (photon/method),
+          // Don't double-prefix: invoke-form sends fully-qualified names (photon.method),
           // bridge sends unqualified names (just method). Check for prefix before adding.
-          var toolName = rawName.indexOf('/') !== -1 ? rawName : photonName + '/' + rawName;
+          var toolName =
+            rawName.indexOf('.') !== -1 || rawName.indexOf('/') !== -1
+              ? rawName
+              : photonName + '.' + rawName;
           var args = (msg.params && msg.params.arguments) || {};
 
           var doCall = function() {

package/dist/auto-ui/streamable-http-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamable-http-transport.d.ts","sourceRoot":"","sources":["../../src/auto-ui/streamable-http-transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"streamable-http-transport.d.ts","sourceRoot":"","sources":["../../src/auto-ui/streamable-http-transport.ts"],"names":[],"mappings":"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"}

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

@@ -148,6 +148,33 @@ function decodeJWTCaller(authHeader) {
         return undefined;
     }
 }
+function isOpenAIAppSession(session) {
+    const name = session.clientInfo?.name?.toLowerCase();
+    return name === 'chatgpt' || !!name?.includes('openai');
+}
+function namespacedToolName(serverName, methodName) {
+    return `${serverName}.${methodName}`;
+}
+function toolNameForSession(session, photonName, methodName) {
+    return isOpenAIAppSession(session) ? methodName : namespacedToolName(photonName, methodName);
+}
+function splitNamespacedToolName(name) {
+    const dotIndex = name.indexOf('.');
+    if (dotIndex !== -1) {
+        return {
+            serverName: name.slice(0, dotIndex),
+            methodName: name.slice(dotIndex + 1),
+        };
+    }
+    const slashIndex = name.indexOf('/');
+    if (slashIndex !== -1) {
+        return {
+            serverName: name.slice(0, slashIndex),
+            methodName: name.slice(slashIndex + 1),
+        };
+    }
+    return null;
+}
 // ════════════════════════════════════════════════════════════════════════════════
 // SESSION MANAGEMENT
 // ════════════════════════════════════════════════════════════════════════════════
@@ -1150,7 +1177,7 @@ const handlers = {
                     : undefined;
                 const meta = buildToolMCPMeta(method, { uiResourceUri });
                 tools.push({
-                    name: `${photon.name}/${method.name}`,
+                    name: toolNameForSession(session, photon.name, method.name),
                     description: method.description || `Execute ${method.name}`,
                     inputSchema: method.params || { type: 'object', properties: {} },
                     'x-photon-id': photon.id, // Unique ID (hash of path) for subscriptions
@@ -1186,7 +1213,7 @@ const handlers = {
             if (!photon.configured || !photon.stateful)
                 continue;
             tools.push({
-                name: `${photon.name}/_use`,
+                name: namespacedToolName(photon.name, '_use'),
                 description: `Switch to a named instance of ${photon.name}. Omit name to select interactively.`,
                 inputSchema: {
                     type: 'object',
@@ -1201,21 +1228,21 @@ const handlers = {
                 'x-photon-internal': true,
             });
             tools.push({
-                name: `${photon.name}/_instances`,
+                name: namespacedToolName(photon.name, '_instances'),
                 description: `List all available instances of ${photon.name}.`,
                 inputSchema: { type: 'object', properties: {} },
                 'x-photon-id': photon.id,
                 'x-photon-internal': true,
             });
             tools.push({
-                name: `${photon.name}/_undo`,
+                name: namespacedToolName(photon.name, '_undo'),
                 description: `Undo the last state mutation on ${photon.name}. Reverts the most recent change.`,
                 inputSchema: { type: 'object', properties: {} },
                 'x-photon-id': photon.id,
                 'x-photon-internal': true,
             });
             tools.push({
-                name: `${photon.name}/_redo`,
+                name: namespacedToolName(photon.name, '_redo'),
                 description: `Redo the last undone mutation on ${photon.name}. Re-applies a previously undone change.`,
                 inputSchema: { type: 'object', properties: {} },
                 'x-photon-id': photon.id,
@@ -1230,7 +1257,7 @@ const handlers = {
                 for (const method of mcp.methods) {
                     const meta = buildToolMCPMeta(method, { uiResourceUri: method.linkedUi });
                     tools.push({
-                        name: `${mcp.name}/${method.name}`,
+                        name: namespacedToolName(mcp.name, method.name),
                         description: method.description || `Execute ${method.name}`,
                         inputSchema: method.params || { type: 'object', properties: {} },
                         'x-external-mcp': true, // Marker for frontend to identify external MCPs
@@ -1542,9 +1569,31 @@ const handlers = {
         if (name === 'beam/studio-parse') {
             return handleBeamStudioParse(req, args || {});
         }
-        // Parse tool name: server-name/method-name or namespace:server-name/method-name
-        const slashIndex = name.indexOf('/');
-        if (slashIndex === -1) {
+        // Parse tool name: server-name.method-name.
+        // ChatGPT/OpenAI app sessions receive slashless names in tools/list because
+        // their connector layer treats slash-qualified names as app resource paths.
+        let serverName;
+        let methodName;
+        const namespacedName = splitNamespacedToolName(name);
+        if (!namespacedName && isOpenAIAppSession(session)) {
+            const matches = ctx.photons.filter((photon) => photon.configured && photon.methods?.some((method) => method.name === name));
+            if (matches.length === 1) {
+                const photon = matches[0];
+                serverName = photon.name;
+                methodName = name;
+            }
+            else {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [{ type: 'text', text: `Invalid tool name: ${name}` }],
+                        isError: true,
+                    },
+                };
+            }
+        }
+        else if (!namespacedName) {
             return {
                 jsonrpc: '2.0',
                 id: req.id,
@@ -1554,8 +1603,10 @@ const handlers = {
                 },
             };
         }
-        const serverName = name.slice(0, slashIndex);
-        const methodName = name.slice(slashIndex + 1);
+        else {
+            serverName = namespacedName.serverName;
+            methodName = namespacedName.methodName;
+        }
         // Per-photon auth check: if this photon requires auth but caller is anonymous, reject
         const targetPhoton = ctx.photons.find((p) => p.name === serverName);
         // Claim-code scope enforcement: filtering tools/list alone is not a