portel-dev/photon

Photon is the fastest way to turn a small, verified TypeScript method into
something humans can operate and agents can trust. Write the capability once;
Photon derives the interfaces, contracts, and runtime behavior around it:
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
Web routes, schedules, webhooks, retries, state, and audit history when the
capability grows into a production workflow
Photon is free and open source software released under the MIT license.
Full documentation lives at photon.portel.dev.
Related Portel project: NCP gives agents
one natural MCP interface to discover and run tools across a whole tool
ecosystem. Photon builds reliable agent-facing capabilities; NCP helps agents
find and use them alongside every other MCP.
Try it in two minutes:
bash
bun add -g @portel/photon
photon new my-tool
photon
That opens Beam, the generated human UI. Add photon mcp install my-tool when
you want the same capability inside Claude Desktop or another MCP client.
Interfaces are optional. Intent is mandatory.
bash
gh repo star portel-dev/photon
## 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.
Real clients, same Photon:
ChatGPT developer mode rendering the Photon weather UI from a public HTTPS /mcp endpoint.
Claude Desktop rendering the same Photon through local MCP.
Follow the step-by-step tutorial
or open the runnable example in
examples/weather-showcase.
The tutorial also includes Beam, CLI, and a concept animation for the full
transformation.
## The Photon Promise
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.
### Example
typescript
// 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.
### Quick Start
From zero to an MCP server connected to Claude Desktop in three commands:
bash
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 run photon instead — it opens Beam, the auto-generated UI.