photon

One TypeScript capability becomes the whole agent stack.

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:

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.*

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

// 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:

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.

Or try without installing globally:

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

> Requires Node.js 20+. TypeScript is compiled internally; no `tsconfig.json` needed.

>

> Where do photon files live? `./` (a project directory you cd into) or `~/.photon/` (global, auto-discovered). User settings persist under `~/.photon/state//`. See Where things live.

How It Works

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:

When you add a `@param city {@pattern ^[a-zA-Z\s]+$}` annotation, Beam validates it in the form, the CLI validates it before running, and the MCP schema enforces it for the AI. One annotation. Three consumers.

Three ways to author

`extends Photon` is one shape. You can also inject `Photon` as a constructor parameter when you already extend something else, or compose without inheritance — same API either way. CF resources reach the photon through a separate `Cloudflare` injection so portable photons stay portable. See docs/guides/PHOTON-INJECTION.md.

Beam: Human Exploration

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

The UI is fully auto-generated from 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.url` is 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.

> Custom UIs follow the official MCP Apps Extension and work across compatible hosts. See the Custom UI Guide.

Photons that declare HTTP routes with `@get`, `@post`, `@put`, `@patch`, or `@delete` are 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 an `x-photon-base-path` header so the app can construct correct absolute paths regardless of where Beam is hosted.

AI Agents: Machine Invocation

Photon ships separate, tested MCP adapters: sessionful MCP 2025 over stdio and

Streamable HTTP, plus stateless MCP `2026-07-28` release-candidate support over

Streamable HTTP. See the

compatibility matrix and runnable clients,

or run `photon doctor mcp` against your installed runtime.

photon info analytics --mcp

{
  "mcpServers": {
    "analytics": {
      "command": "photon",
      "args": ["mcp", "analytics"]
    }
  }
}

Paste into your AI client's config. Your photon is now an MCP server. Claude can call your methods. Cursor can call your methods. Any MCP-compatible host can call your methods.

The AI sees the same thing a human sees in Beam: the method names, the parameter descriptions from your JSDoc, the validation rules from your types. The JSDoc comment you wrote to document the tool for yourself is what Claude reads to decide when and how to call it.

The MCP tools themselves work with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. When your photon has a custom UI, clients that support the MCP Apps Extension can render it natively, as shown in the weather proof above.

How a Photon Evolves

Here is how a photon grows. Each step adds one thing and gets multiple capabilities from it.

Add comments: AI understands your intent

/**
 * Weather - Check weather forecasts worldwide
 */
export default class Weather {
  /**
   * Get the weather forecast for a city
   * @param city City name (e.g., "London")
   */
  async forecast(params: { city: string }) { ... }
}

The class description becomes how AI clients introduce the tool to users. The `@param` description is what the AI reads before deciding what value to pass. Same comments. Human help text and AI contract at once.

Declare configuration: a settings tool appears

export default class Weather {
  /** User-tunable knobs. Photon auto-generates a `settings` tool from this. */
  protected settings = {
    /** Units for forecast values */
    units: 'metric',
    /** Polling interval in seconds */
    pollIntervalSec: 300,
  };

  async forecast(params: { city: string }) {
    const res = await fetch(`...?units=${this.settings.units}`);
    return await res.json();
  }
}

`protected settings` is the canonical way to expose runtime knobs. Photon reads the JSDoc on each property, generates an MCP `settings` tool with typed inputs, and persists user changes to `~/.photon/state//-settings.json`. Inside methods, `this.settings` is a read-only Proxy. To change a value, the user (or AI) calls the auto-generated `settings` tool.

For secrets that should never be persisted in a settings file (API keys, tokens), use a constructor parameter instead. Photon maps the parameter name to an env var:

export default class Weather {
  constructor(private apiKey: string) {}  // → WEATHER_API_KEY
}

The constructor pattern is for primitives that come from `.env`. The `protected settings` pattern is for everything else, including any knob the user should be able to change at runtime without restarting. When in doubt, reach for `settings`.

Add tags: behavior extends across all surfaces

/**
 * @dependencies node-fetch@^3.0.0
 */
export default class Weather {
  /**
   * @param city City name {@example London} {@pattern ^[a-zA-Z\s]+$}
   * @param days Number of days {@min 1} {@max 7}
   * @format table
   */
  async forecast(params: { city: string; days?: number }) { ... }
}

`@dependencies` installs `node-fetch` automatically on first run, no manual package install needed. The `{@pattern}` validates in the form, the CLI, and the MCP schema simultaneously. `days` becomes a number spinner with bounds. `@format table` renders the result as a table in Beam. One annotation, three surfaces.

System CLI dependencies

If your photon wraps a command-line tool, declare it and Photon enforces it at load time:

/**
 * @cli ffmpeg - https://ffmpeg.org/download.html
 */
export default class VideoProcessor {
  async convert({ input, format }: { input: string; format: string }) {
    // ffmpeg is guaranteed to exist when this runs
  }
}

What Comes for Free

Things you don't build because Photon handles them:

Coordination: Locks + Events

Two primitives. Together they unlock a class of things that are surprisingly hard to build today.

Locks serialize access. When a method is marked `@locked`, only one caller can execute at a time, whether that caller is a human in Beam, a CLI script, or an AI agent. Everyone else waits their turn.

Events push state changes to any browser UI in real time. `this.emit({ event: 'boardUpdated', data: board })` on the server becomes `chess.onBoardUpdated(handler)` in your custom UI — named after your photon file. No WebSockets to configure. No polling. Events are delivered via SSE through the MCP Streamable HTTP transport.

Together: turn-based coordination with live state.

export default class Chess {
  /** Make a move. Locks ensure human and AI alternate turns. */
  /** @locked */
  async move(params: { from: string; to: string }) {
    const result = await this.applyMove(params.from, params.to);

    // Browser UI updates instantly, no polling needed
    this.emit({ event: 'boardUpdated', data: result.board });
    this.emit({ event: 'turnChanged', data: { next: result.nextPlayer } });

    return result;
  }
}

// In your custom UI (ui/chess.html)
// The global `chess` is auto-injected, named after your photon file
chess.onBoardUpdated(board => renderBoard(board));
chess.onTurnChanged(({ next }) => showTurn(next));

// Call server methods directly
chess.move({ from: 'e2', to: 'e4' });

A human moves through Beam. Claude is configured with the MCP server. The lock ensures they truly alternate. Events keep the board live on both sides. That's a fully functional turn-based chess game, human vs AI, in about 50 lines of application logic.

The same pattern applies beyond games: approval workflows where a human reviews before AI continues, collaborative tools where edits from any source appear instantly, simulations where steps must execute in strict sequence, any system where who acts next matters.

MCP Primitives on `this`

The MCP protocol's user-facing primitives are surfaced as plain methods

on every photon instance — no decorators, no capability flags, no SDK

imports. The runtime routes each call through whichever surface the

request arrived on (Beam, Claude Desktop, Cursor, CLI).

export default class Editor {
  async summarize(params: { text: string }) {
    // Ask the driving agent's LLM. No API key. Agent pays.
    return await this.sample({
      prompt: `Summarize in one sentence:\n\n${params.text}`,
      maxTokens: 128,
    });
  }

  async deploy() {
    if (!(await this.confirm('Ship to production?'))) return;
    const env = await this.elicit({
      ask: 'select',
      message: 'Which environment?',
      options: ['staging', 'prod'],
    });
    await this.run(env);
  }
}

Full reference: `docs/reference/MCP-PRIMITIVES.md`.

Remote Access: Claim Codes

By default every installed photon is visible to every connected MCP

client. When you want to pair a *remote* agent with a *subset* of your

photons — your phone driving Beam, a teammate reviewing one project,

a CI agent scoped to a single directory — generate a claim code:

$ photon claim --scope /workspace/proj --ttl 4h --label "phone"
✓ Claim code: R3K-9QZ
  Scope:      /workspace/proj
  Expires in: 4h

The remote client presents the code as the `Mcp-Claim-Code` header on

its MCP session. `tools/list` then only exposes photons whose source

lives under that directory. Sessions without a code keep full access —

the feature is strictly opt-in.

Full reference: `docs/reference/CLAIM-CODES.md`.

Marketplace

A curated set of photons is ready to install. The public gallery is now kept

small on purpose: polished apps and tools in one place, teaching examples in

another.

photon search boards
photon add boards

You can also install directly from any GitHub repository using qualified refs:

photon add owner/repo/photon-name

Browse the Photon Apps marketplace

for ready-to-use photons, or the

Photon Examples marketplace

for focused learning examples. You can also host a private marketplace for your

team: internal tools that stay off the public internet.

Commands

# Run
photon                            # Open Beam UI
photon mcp                  # Run as MCP server
photon mcp  --dev           # MCP server with hot reload
photon cli  [method]        # Run as CLI tool

# Install from GitHub
photon beam owner/repo/name       # Install & open in Beam
photon cli owner/repo/name method # Install & run via CLI

# Create
photon maker new            # Scaffold a new photon

# Build
photon build                # Compile to standalone binary
photon build  --with-app    # Include Beam UI in binary

# Manage
photon info                       # List all photons
photon info  --mcp          # Get MCP client config
photon maker validate       # Check for errors

# Marketplace
photon add                  # Install photon
photon search              # Search marketplace
photon upgrade                    # Upgrade all

# Ops
photon doctor                     # Diagnose environment
photon test                       # Run tests
photon ps                         # Observe & control scheduled jobs, webhooks, sessions

`photon ps`: scheduled jobs, webhooks, and sessions

`photon ps` is the operator surface for the daemon. Without arguments

it prints a four-section snapshot — ACTIVE schedules, DECLARED-but-

not-enrolled, WEBHOOKS, and ACTIVE SESSIONS.

photon ps                          # full snapshot
photon ps --json                   # structured output for scripts
photon ps --type active            # one section only
photon ps --base ~/Projects/kith   # filter to one PHOTON_DIR

Two-step model. A `@scheduled` annotation in source is DECLARED

until enrolled. Enrollment is per-machine, persistent, and explicit:

photon ps enable  newsletter:sendDigest    # DECLARED → ACTIVE
photon ps disable newsletter:sendDigest    # ACTIVE → suppressed (survives restart)
photon ps pause   newsletter:sendDigest    # stop firing without removing enrollment
photon ps resume  newsletter:sendDigest    # undo pause
photon ps history newsletter:sendDigest    # last 20 firings: timestamp, status, error

For manual cron schedules without a `@scheduled` tag, use the Beam Pulse

panel ("Add schedule") or call `this.schedule.create()` from photon code.

`this.schedule.create()` (programmatic schedules) skips DECLARED and

goes straight to ACTIVE. See

`docs/GUIDE.md#scheduling`

for the full reference, the daemon state layout, and `.photon-no-host`

for multi-host setups.

Install from GitHub

Use qualified refs to install and run photons directly from any GitHub repository:

photon beam Arul-/photons/claw        # Install from GitHub, open in Beam
photon cli Arul-/photons/todo add     # Install from GitHub, run method

The format is `owner/repo/photon-name`. Transitive `@photon` dependencies from the same repo are resolved automatically.

Compile to Binary

Build standalone executables from any photon — no Node.js required on the target machine:

photon build my-tool                         # Binary for current platform
photon build my-tool -t bun-linux-x64        # Cross-compile for Linux
photon build my-tool --with-app              # Embed Beam UI as a desktop app

Uses Bun's compiler under the hood. The binary bundles the photon, its `@dependencies`, and transitive `@photon` deps into a single file.

Tag Reference

> See the full Tag Reference for all 30+ tags with examples.

Documentation

Start here:

Go deeper:

Operate:

Reference: Complete Developer Guide · Tag Reference · Naming Conventions · Architecture · Lifecycle & Ingress · PHOTON_DIR & Namespace · Changelog · Contributing

Open Source

Photon is free and open source under the MIT license.

The project is still evolving and contributions are welcome.

• Star the repository if the idea resonates: `gh repo star portel-dev/photon`
• Report issues
• Contribute improvements or examples