@portel/photon 1.6.0 → 1.7.0

package/README.md

@@ -14,7 +14,9 @@ A framework, runtime, and ecosystem. Batteries included.
 [![Node](https://img.shields.io/badge/node-%3E%3D18-43853d.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)
 
-[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Beam UI](#beam) · [Marketplace](#marketplace) · [Docs](#documentation)
+[Quick Start](#quick-start) · [Why Photon](#why-did-we-build-this) · [Beam UI](#beam) · [How It Works](#how-it-works) · [Docs](#documentation)
+
+[![Watch: Why Photon? (2 min)](https://img.youtube.com/vi/FI0M8s6ZKv4/maxresdefault.jpg)](https://www.youtube.com/watch?v=FI0M8s6ZKv4)
 
 </div>
 
@@ -22,7 +24,7 @@ A framework, runtime, and ecosystem. Batteries included.
 
 ## What Is This Thing?
 
-So, here is the situation. You write a single TypeScript file. Just one. And somehow, through some dark magic I don’t fully understand either, you get three things at once:
+So, here is the situation. You write a single TypeScript file. Just one. And somehow, through some dark magic I don't fully understand either, you get three things at once:
 
 1.  **An MCP server** (so Claude or Cursor can use your tools).
 2.  **A CLI tool** (so you can run it from the terminal like a normal human).
@@ -36,20 +38,6 @@ It looks like this:
 
 You just write the logic. Photon deals with the protocols, schemas, and the boring stuff that usually makes you question your life choices.
 
-### The Basics
-
-If you are just skimming, here is what you need to know:
-
-| Concept | What it is | Learn more |
-|---------|-----------|------------|
-| **MCP** | A way for AI to use your tools. It’s a standard. | [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) |
-| **Photon file** | A `.photon.ts` file. You define tools as methods in a class. | [Guide](./GUIDE.md) |
-| **Beam** | A web dashboard. It shows your tools as forms. | [Beam UI](#beam) |
-| **Marketplace** | A way to get other people’s photons. | [Marketplace](#marketplace) |
-| **Daemon** | A background thing that handles messages and jobs. | [Daemon Pub/Sub](./DAEMON-PUBSUB.md) |
-| **Tags** | JSDoc comments that tell Photon what to do. | [Tag Reference](./DOCBLOCK-TAGS.md) |
-| **Custom UI** | When the auto-generated forms aren't enough. | [Custom UI Guide](./CUSTOM-UI.md) |
-
 ### Who Is This For?
 
 *   **Developers** who want to give AI access to their database but are too lazy to write a full server.
@@ -60,6 +48,18 @@ You don't need to know what "MCP" actually stands for. If you can write a TypeSc
 
 ---
 
+## Why did we build this?
+
+Three reasons, if you want the short version. ([Read the longer version](./WHY-PHOTON.md))
+
+**MCP is personal.** The best MCP is the one built for exactly one use case. Yours. Your team's. Your company's. When you stop building for everyone, the code gets absurdly simple. One file. Twelve lines. Not twelve hundred.
+
+**Solve once, run forever.** If an LLM figured out your workflow the first time, why ask it to re-derive the same answer from scratch every time? Photon lets you keep the answer. No middleman, no tokens, no latency.
+
+**Same door, every key.** AI calls it through MCP. You call it through CLI. You open it in Beam. Same methods, same data, same result. And half the time, you don't need AI at all. You just need the data.
+
+---
+
 ## Quick Start
 
 If you are the type who likes to just run commands and see what happens:
@@ -81,11 +81,69 @@ npx @portel/photon
 
 ---
 
+## Beam
+
+Beam is the dashboard. It's where you go to poke your tools and see if they work before you let an AI loose on them.
+
+Run `photon`. That's it.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="100%">
+</div>
+
+---
+
+## Connecting to AI
+
+If you want to use this with Claude or Cursor, you need the config.
+
+```bash
+photon info weather --mcp
+```
+
+It spits out some JSON:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "photon",
+      "args": ["mcp", "weather"]
+    }
+  }
+}
+```
+
+Copy that. Paste it into your AI client's config file. Done.
+
+Works with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any [MCP-compatible client](https://modelcontextprotocol.io).
+
+---
+
+## Marketplace
+
+We also have a marketplace. 35 photons and counting.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="100%">
+</div>
+
+```bash
+photon search postgres
+photon add postgres
+```
+
+Browse the full catalog and documentation in the [official photons repository](https://github.com/portel-dev/photons).
+
+You can also make a private marketplace for your team, so internal tools stay off the public internet.
+
+---
+
 ## How It Works
 
 A photon is just a TypeScript class. The **public methods become tools**. Photon reads your code, looks at the types, reads your comments, and then generates everything else.
 
-I’ll show you.
+I'll show you.
 
 ### Step 1: The Bare Minimum
 
@@ -107,7 +165,7 @@ export default class Weather {
 *   `photon` (The web UI)
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1 — Bare method in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1 — Bare method in Beam" width="100%">
 </div>
 
 ### Step 2: Adding Descriptions
@@ -134,7 +192,7 @@ export default class Weather {
 **What happens:** Now the UI has helpful text. Also, the AI client reads this to understand what the tool does.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2 — JSDoc descriptions in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2 — JSDoc descriptions in Beam" width="100%">
 </div>
 
 ### Step 3: Configuration (The clever bit)
@@ -160,7 +218,7 @@ export default class Weather {
 **What happens:** Beam creates a settings panel. `apiKey` becomes a password field. It also maps to environment variables like `WEATHER_API_KEY`. It just works.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3 — Configuration panel in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3 — Configuration panel in Beam" width="100%">
 </div>
 
 ### Step 4: Validation (Stop bad inputs)
@@ -223,7 +281,7 @@ VideoProcessor requires the following CLI tools to be installed:
 > See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all available tags. There are 30+ covering validation, UI hints, scheduling, webhooks, and more.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4 — Validation and formatting in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4 — Validation and formatting in Beam" width="100%">
 </div>
 
 ### Step 5: Custom UI (When you want to be fancy)
@@ -267,7 +325,7 @@ export default class Weather {
 > Custom UIs follow the [MCP Apps Extension (SEP-1865)](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) standard and work across compatible hosts. See the [Custom UI Guide](./CUSTOM-UI.md).
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5 — Custom UI result in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5 — Custom UI result in Beam" width="100%">
 </div>
 
 ### In Summary
@@ -281,129 +339,24 @@ export default class Weather {
 | **5. Custom UI** | HTML | A custom app |
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="100%">
 </div>
 
 ---
 
-## Beam
-
-Beam is the dashboard. It’s where you go to poke your tools and see if they work before you let an AI loose on them.
-
-Run `photon`. That’s it.
-
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="700">
-</div>
-
----
-
-## Connecting to AI
-
-If you want to use this with Claude or Cursor, you need the config.
-
-```bash
-photon info weather --mcp
-```
-
-It spits out some JSON:
-
-```json
-{
-  "mcpServers": {
-    "weather": {
-      "command": "photon",
-      "args": ["mcp", "weather"]
-    }
-  }
-}
-```
-
-Copy that. Paste it into your AI client’s config file. Done.
+## The Basics
 
-Works with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any [MCP-compatible client](https://modelcontextprotocol.io).
-
----
-
-## Why did we build this?
-
-Writing an MCP server usually involves 4 to 6 files and about 150 lines of code before you even start writing the thing you actually wanted to write.
-
-With Photon, it’s one file.
-
-| | Traditional MCP | Photon |
-|---|---|---|
-| **Files** | 4-6 (server, transport, schemas, types, config) | 1 |
-| **Boilerplate** | 150+ lines | 0 |
-| **Dependencies** | Manual `npm install` | Automatic |
-| **Schema** | Hand-written JSON Schema | Generated from TS types |
-| **Config** | Manual env var parsing | Automatic from Constructor |
-
-It is unnecessarily difficult to do it the old way. So we stopped doing it.
-
----
-
-## Marketplace
-
-We also have a marketplace. 31 photons and counting.
-
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="700">
-</div>
-
-```bash
-photon search postgres
-photon add postgres
-```
-
-### Available Photons
-
-**Productivity**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 📌 **kanban** | Multi-tenant task boards for humans and AI | 33 |
-| 📬 **git-box** | Mailbox-style Git interface, manage repos like an inbox | 58 |
-| 📬 **form-inbox** | Webhook-powered form submission collector | 12 |
-| 📅 **google-calendar** | Calendar integration via OAuth | 9 |
-| 🎫 **jira** | Project management and issue tracking | 10 |
-| 💬 **slack** | Send messages and manage Slack workspaces | 7 |
-| 📧 **email** | Send and receive via SMTP/IMAP | 8 |
-
-**Infrastructure**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 📁 **filesystem** | Safe, cross-platform file operations | 13 |
-| 🔀 **git** | Local git repository operations | 11 |
-| 🐙 **github-issues** | Manage GitHub issues and comments | 7 |
-| 🐳 **docker** | Container and image management | 10 |
-| ☁️ **aws-s3** | S3 object storage operations | 11 |
-| 🌐 **web** | DuckDuckGo search + Readability extraction | 2 |
-
-**Databases**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 🐘 **postgres** | PostgreSQL queries and schema ops | 7 |
-| 🗄️ **sqlite** | SQLite database operations | 9 |
-| 🍃 **mongodb** | MongoDB document CRUD and aggregation | 13 |
-| ⚡ **redis** | Key-value store, lists, sets, pub/sub | 18 |
-
-**Utilities and Demos**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 🕐 **time** | Timezone conversion and queries | 3 |
-| 🧮 **math** | Expression evaluator (trig, stats, etc.) | 1 |
-| 📊 **code-diagram** | Generate Mermaid diagrams from code | 3 |
-| 🔴 **connect-four** | Play against AI with distributed locks | 8 |
-| 🍳 **kitchen-sink** | Every runtime feature in one file | 25 |
-| 📋 **dashboard** | MCP Apps UI demo | 6 |
-| 📺 **team-dashboard** | TV/monitor-optimized team display | 20 |
-| 🎭 **mcp-orchestrator** | Combine multiple MCPs into workflows | 10 |
+If you are just skimming, here is what you need to know:
 
-You can also make a private marketplace for your team, so internal tools stay off the public internet.
+| Concept | What it is | Learn more |
+|---------|-----------|------------|
+| **MCP** | A way for AI to use your tools. It's a standard. | [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) |
+| **Photon file** | A `.photon.ts` file. You define tools as methods in a class. | [Guide](./GUIDE.md) |
+| **Beam** | A web dashboard. It shows your tools as forms. | [Beam UI](#beam) |
+| **Marketplace** | A way to get other people's photons. | [Marketplace](#marketplace) |
+| **Daemon** | A background thing that handles messages and jobs. | [Daemon Pub/Sub](./DAEMON-PUBSUB.md) |
+| **Tags** | JSDoc comments that tell Photon what to do. | [Tag Reference](./DOCBLOCK-TAGS.md) |
+| **Custom UI** | When the auto-generated forms aren't enough. | [Custom UI Guide](./CUSTOM-UI.md) |
 
 ---
 
@@ -516,4 +469,3 @@ If you find a bug, or if my code offends you, feel free to open an issue or a PR
 Made by [Portel](https://github.com/portel-dev)
 
 </div>
-

package/dist/auto-ui/beam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"beam.d.ts","sourceRoot":"","sources":["../../src/auto-ui/beam.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA0xBH,wBAAsB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAs8ElF;AAkYD;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAsB9C"}
+{"version":3,"file":"beam.d.ts","sourceRoot":"","sources":["../../src/auto-ui/beam.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAixBH,wBAAsB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0/ElF;AAiYD;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAsB9C"}

package/dist/auto-ui/beam.js

@@ -14,6 +14,7 @@ import * as os from 'os';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
+import { isPathWithin, isLocalRequest, setSecurityHeaders, readBody, SimpleRateLimiter } from '../shared/security.js';
 /**
  * Generate a unique ID for a photon based on its path.
  * This ensures photons with the same name from different paths are distinguishable.
@@ -178,8 +179,7 @@ async function loadExternalMCPs(config) {
                 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');
+                    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) {
@@ -257,8 +257,7 @@ async function loadExternalMCPs(config) {
                         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');
+                        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) {
@@ -358,8 +357,7 @@ async function reconnectExternalMCP(name) {
             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');
+                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) {
@@ -671,8 +669,8 @@ export async function startBeam(rawWorkingDir, port) {
                     defaultValue: p.defaultValue,
                 }));
                 // Extract @ui template path from class-level JSDoc
-                const classJsdocMatch = source.match(/\/\*\*[\s\S]*?\*\/\s*(?=export\s+default\s+class)/)
-                    || source.match(/^\/\*\*([\s\S]*?)\*\//);
+                const classJsdocMatch = source.match(/\/\*\*[\s\S]*?\*\/\s*(?=export\s+default\s+class)/) ||
+                    source.match(/^\/\*\*([\s\S]*?)\*\//);
                 if (classJsdocMatch) {
                     const uiMatch = classJsdocMatch[0].match(/@ui\s+([^\s*]+)/);
                     if (uiMatch) {
@@ -745,7 +743,9 @@ export async function startBeam(rawWorkingDir, port) {
                     linkedUi: linkedAsset?.id,
                     ...(schema.isStatic ? { isStatic: true } : {}),
                     ...(schema.webhook ? { webhook: schema.webhook } : {}),
-                    ...(schema.scheduled || schema.cron ? { scheduled: schema.scheduled || schema.cron } : {}),
+                    ...(schema.scheduled || schema.cron
+                        ? { scheduled: schema.scheduled || schema.cron }
+                        : {}),
                     ...(schema.locked ? { locked: schema.locked } : {}),
                 };
             });
@@ -819,7 +819,8 @@ export async function startBeam(rawWorkingDir, port) {
                 promptCount,
                 installSource,
                 ...(constructorParams.length > 0 && { requiredParams: constructorParams }),
-                ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+                ...(mcp.injectedPhotons &&
+                    mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
             };
         }
         catch (error) {
@@ -1014,8 +1015,12 @@ export async function startBeam(rawWorkingDir, port) {
             return null; // UI asset not found
         }
     };
+    // Security: rate limiter for API endpoints
+    const apiRateLimiter = new SimpleRateLimiter(30, 60_000);
     // Create HTTP server
     const server = http.createServer(async (req, res) => {
+        // Security: set standard security headers on all responses
+        setSecurityHeaders(res);
         const url = new URL(req.url || '/', `http://${req.headers.host}`);
         // ══════════════════════════════════════════════════════════════════════════
         // MCP Streamable HTTP Transport (standard MCP clients like Claude Desktop)
@@ -1133,17 +1138,18 @@ export async function startBeam(rawWorkingDir, port) {
                     root = path.resolve(workdirEnv);
                 }
             }
-            const dirPath = url.searchParams.get('path') || root || workingDir;
+            // Security: default browse root to workingDir if not specified
+            if (!root) {
+                root = workingDir;
+            }
+            const dirPath = url.searchParams.get('path') || root;
             try {
                 const resolved = path.resolve(dirPath);
-                // Validate path is within root (if specified)
-                if (root) {
-                    const resolvedRoot = path.resolve(root);
-                    if (!resolved.startsWith(resolvedRoot)) {
-                        res.writeHead(403);
-                        res.end(JSON.stringify({ error: 'Access denied: outside allowed directory' }));
-                        return;
-                    }
+                // Security: always enforce path boundary using isPathWithin
+                if (!isPathWithin(resolved, root)) {
+                    res.writeHead(403);
+                    res.end(JSON.stringify({ error: 'Access denied: outside allowed directory' }));
+                    return;
                 }
                 const stat = await fs.stat(resolved);
                 if (!stat.isDirectory()) {
@@ -1187,6 +1193,12 @@ export async function startBeam(rawWorkingDir, port) {
                 return;
             }
             const resolved = path.resolve(filePath);
+            // Security: prevent path traversal — file must be within working directory
+            if (!isPathWithin(resolved, workingDir)) {
+                res.writeHead(403);
+                res.end('Access denied: outside allowed directory');
+                return;
+            }
             try {
                 const fileStat = await fs.stat(resolved);
                 if (!fileStat.isFile()) {
@@ -1367,9 +1379,19 @@ export async function startBeam(rawWorkingDir, port) {
             }
             // Resolve template path relative to photon's directory
             const photonDir = path.dirname(photon.path);
-            const fullTemplatePath = path.isAbsolute(templateFile)
-                ? templateFile
-                : path.join(photonDir, templateFile);
+            // Security: reject absolute template paths — must be relative to photon dir
+            if (path.isAbsolute(templateFile)) {
+                res.writeHead(403);
+                res.end(JSON.stringify({ error: 'Absolute template paths are not allowed' }));
+                return;
+            }
+            const fullTemplatePath = path.join(photonDir, templateFile);
+            // Security: validate resolved path is within photon directory
+            if (!isPathWithin(fullTemplatePath, photonDir)) {
+                res.writeHead(403);
+                res.end(JSON.stringify({ error: 'Template path traversal detected' }));
+                return;
+            }
             try {
                 const templateContent = await fs.readFile(fullTemplatePath, 'utf-8');
                 res.setHeader('Content-Type', 'text/html');
@@ -1608,38 +1630,49 @@ export async function startBeam(rawWorkingDir, port) {
         }
         // Invoke API: Direct HTTP endpoint for method invocation (used by PWA)
         if (url.pathname === '/api/invoke' && req.method === 'POST') {
-            let body = '';
-            req.on('data', (chunk) => (body += chunk));
-            req.on('end', async () => {
-                try {
-                    const { photon: photonName, method, args } = JSON.parse(body);
-                    if (!photonName || !method) {
-                        res.writeHead(400);
-                        res.end(JSON.stringify({ error: 'Missing photon or method' }));
-                        return;
-                    }
-                    const mcp = photonMCPs.get(photonName);
-                    if (!mcp || !mcp.instance) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Photon not found: ${photonName}` }));
-                        return;
-                    }
-                    if (typeof mcp.instance[method] !== 'function') {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Method not found: ${method}` }));
-                        return;
-                    }
-                    const result = await mcp.instance[method](args || {});
-                    res.setHeader('Content-Type', 'application/json');
-                    res.writeHead(200);
-                    res.end(JSON.stringify({ result }));
+            // Security: only allow local requests
+            if (!isLocalRequest(req)) {
+                res.writeHead(403);
+                res.end(JSON.stringify({ error: 'Forbidden: non-local request' }));
+                return;
+            }
+            // Security: rate limiting
+            const clientKey = req.socket?.remoteAddress || 'unknown';
+            if (!apiRateLimiter.isAllowed(clientKey)) {
+                res.writeHead(429);
+                res.end(JSON.stringify({ error: 'Too many requests' }));
+                return;
+            }
+            try {
+                const body = await readBody(req);
+                const { photon: photonName, method, args } = JSON.parse(body);
+                if (!photonName || !method) {
+                    res.writeHead(400);
+                    res.end(JSON.stringify({ error: 'Missing photon or method' }));
+                    return;
                 }
-                catch (err) {
-                    res.setHeader('Content-Type', 'application/json');
-                    res.writeHead(500);
-                    res.end(JSON.stringify({ error: err.message || String(err) }));
+                const mcp = photonMCPs.get(photonName);
+                if (!mcp || !mcp.instance) {
+                    res.writeHead(404);
+                    res.end(JSON.stringify({ error: `Photon not found: ${photonName}` }));
+                    return;
                 }
-            });
+                if (typeof mcp.instance[method] !== 'function') {
+                    res.writeHead(404);
+                    res.end(JSON.stringify({ error: `Method not found: ${method}` }));
+                    return;
+                }
+                const result = await mcp.instance[method](args || {});
+                res.setHeader('Content-Type', 'application/json');
+                res.writeHead(200);
+                res.end(JSON.stringify({ result }));
+            }
+            catch (err) {
+                const status = err.message?.includes('too large') ? 413 : 500;
+                res.setHeader('Content-Type', 'application/json');
+                res.writeHead(status);
+                res.end(JSON.stringify({ error: err.message || String(err) }));
+            }
             return;
         }
         // Platform Bridge API: Generate platform compatibility script
@@ -2354,7 +2387,8 @@ export async function startBeam(rawWorkingDir, port) {
                     icon: reloadClassMeta.icon,
                     internal: reloadClassMeta.internal,
                     ...(reloadConstructorParams.length > 0 && { requiredParams: reloadConstructorParams }),
-                    ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+                    ...(mcp.injectedPhotons &&
+                        mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
                 };
                 if (isNewPhoton) {
                     photons.push(reloadedPhoton);
@@ -2499,7 +2533,9 @@ export async function startBeam(rawWorkingDir, port) {
                     process.exit(1);
                 }
             });
-            server.listen(currentPort, '0.0.0.0', () => {
+            // Security: bind to localhost by default, configurable via BEAM_BIND_ADDRESS
+            const bindAddress = process.env.BEAM_BIND_ADDRESS || '127.0.0.1';
+            server.listen(currentPort, bindAddress, () => {
                 process.env.BEAM_PORT = String(currentPort);
                 const url = `http://localhost:${currentPort}`;
                 console.log(`\n⚡ Photon Beam → ${url} (loading photons...)\n`);
@@ -2529,9 +2565,7 @@ export async function startBeam(rawWorkingDir, port) {
     const photonStatus = unconfiguredCount > 0
         ? `${configuredCount} ready, ${unconfiguredCount} need setup`
         : `${configuredCount} photon${configuredCount !== 1 ? 's' : ''} ready`;
-    const mcpStatus = externalMCPList.length > 0
-        ? `, ${connectedMCPs}/${externalMCPList.length} MCPs`
-        : '';
+    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();
@@ -2673,7 +2707,9 @@ export async function startBeam(rawWorkingDir, port) {
                             externalMCPSDKClients.delete(name);
                         }
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        /* ignore */
+                    }
                     externalMCPClients.delete(name);
                     logger.info(`🔌 Removed external MCP: ${name}`);
                 }
@@ -2701,7 +2737,9 @@ export async function startBeam(rawWorkingDir, port) {
                                 externalMCPSDKClients.delete(name);
                             }
                         }
-                        catch { /* ignore */ }
+                        catch {
+                            /* ignore */
+                        }
                         externalMCPClients.delete(name);
                         externalMCPs.splice(idx, 1);
                     }
@@ -2812,7 +2850,8 @@ async function configurePhotonViaMCP(photonName, config, photons, photonMCPs, lo
             isApp,
             appEntry: mainMethod,
             assets: mcp.assets,
-            ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+            ...(mcp.injectedPhotons &&
+                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
         };
         photons[photonIndex] = configuredPhoton;
         logger.info(`✅ ${photonName} configured via MCP`);
@@ -2908,7 +2947,8 @@ async function reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, saved
             description: reloadClassMeta.description,
             icon: reloadClassMeta.icon,
             internal: reloadClassMeta.internal,
-            ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+            ...(mcp.injectedPhotons &&
+                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
         };
         photons[photonIndex] = reloadedPhoton;
         logger.info(`🔄 ${photonName} reloaded via MCP`);
@@ -3000,10 +3040,7 @@ async function generatePhotonHelpMarkdown(photonName, photons) {
     const mdPath = path.join(sourceDir, `${photonName}.md`);
     // Check if .md file already exists and is newer than the photon source
     try {
-        const [mdStat, srcStat] = await Promise.all([
-            fs.stat(mdPath),
-            fs.stat(photon.path),
-        ]);
+        const [mdStat, srcStat] = await Promise.all([fs.stat(mdPath), fs.stat(photon.path)]);
         if (mdStat.mtimeMs >= srcStat.mtimeMs) {
             const existing = await fs.readFile(mdPath, 'utf-8');
             if (existing.trim()) {