Photon

bun add -g @portel/photon photon new my-tool photon

That opens Beam, the generated human UI. Addphoton mcp install my-toolwhen you want the same capability inside Claude Desktop or another MCP client.

Interfaces are optional. Intent is mandatory.

The weather example is intentionally small: one TypeScript method, a few docblock tags, and one@uiHTML 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/mcpendpoint.

Photon is the modern dev stack for the agentic age: each photon is a small, auditable brick that can be used by humans, agents, schedulers, webhooks, and apps without rewriting the same capability for every interface.

That is the core idea:tiny trusted capabilities compose into larger systems. A photon can start as a helper method, become a CLI command, render as an app, run on a schedule, accept webhooks, and still expose a clean agent-readable contract.

// hello.photon.ts export default class Hello { greet(name: string) { return Hello, ${name}!; } }

That's a complete photon. From this single file you get:

$ photon cli hello greet --name Ada # CLI $ photon # Web UI at localhost:3008 $ photon mcp hello # MCP server for Claude, Cursor, etc.

No decorators. No registration. No server boilerplate. Just define the intent. Photon handles the rest.

From zero to an MCP server connected to Claude Desktop in three commands:

bun add -g @portel/photon photon new my-tool # Scaffolds ./my-tool.photon.ts in your CWD photon mcp install my-tool # Registers it in Claude Desktop's config # Restart Claude Desktop. Your tool is live.

Prefer the web dashboard? Skip step 3 and runphotoninstead — it opens Beam, the auto-generated UI.

bunx @portel/photon new my-tool bunx @portel/photon mcp install my-tool # pnpm users can use pnpm dlx instead: pnpm dlx @portel/photon new my-tool pnpm dlx @portel/photon mcp install my-tool

You write a TypeScript class. Methods are your capabilities. Types describe what's valid. Comments explain the intent. Photon reads all of it and generates three interfaces from one file. Same logic. Same validation. Same data.

analytics.photon.ts → Web UI (Beam) · CLI · MCP Server for AI

The more you express, the more Photon derives:

Beam is the web dashboard. Every photon becomes an interactive form automatically. Runphoton. That's the whole command.

The UI isfully auto-generatedfrom your method signatures: field types, validation, defaults, layouts. You never write frontend code. When you add a{@choice a,b,c}tag to a parameter, Beam renders a dropdown. When you mark a string as{@format email}, the field validates email format. The UI evolves as your code does.

When forms aren't the right interface for what you're building, you can replace Beam's auto-generated view with your own HTML. A global named after your photon is auto-injected (e.g.,analytics.onResult(data => ...)) — no framework required.window.photon.urlis also injected and resolves to the Beam base URL so your HTML can construct fetch paths correctly whether running locally or behind a reverse proxy.

Photons that declare HTTP routes with@get,@post,@put,@patch, or@deleteare shown in Beam as web apps. Routes support dynamic path segments (e.g.@get /items/:id) matched by specificity: literal segments win over parameters. Beam proxies requests to those routes and injects anx-photon-base-pathheader so the app can construct correct absolute paths regardless of where Beam is hosted.