Photon

Appearance

LLM Reference ​

/llms.txt and /llms-full.txt are generated during the docs build.

Photon ​

Photon is an open source TypeScript runtime that turns a single .photon.ts class into an MCP server for AI agents, a CLI tool, and a Beam web dashboard.

Start Here ​

  • Getting Started: Install Photon and build your first .photon.ts file.
  • Core Concepts: The mental model behind methods, comments, formats, state, settings, and surfaces.
  • From Method to Chat App: A weather example that runs as CLI, Beam, MCP, and embedded chat UI.
  • Output Formats: Visual result formats for tables, charts, markdown, mermaid, cards, dashboards, and more.
  • Docblock Tags: Public reference for every docblock tag Photon understands.
  • Complete Developer Guide: Comprehensive reference for authoring and operating photons.

Core Claims ​

  • One TypeScript class can expose the same capability through MCP, CLI, and web UI.
  • JSDoc comments and TypeScript types become AI-readable tool descriptions, validation, CLI help, and form UI.
  • Photon supports custom MCP app UIs, schedules, webhooks, state, settings, dependency metadata, and deployment paths.

Package ​

Documentation Index ​

  • Photon Documentation: Prefer a one-off run?
  • Why Photon: Here's something the MCP ecosystem got backwards. Everyone is building MCPs for everyone. Configuration options for twelve database engines. Auth flows for providers you've never heard of. README files longer than the actual code.
  • README: Define the capability once. Photon turns it into the interfaces people now
  • Photon MCP Developer Guide: > New to Photon? Start with Getting Started instead — you'll be running your first photon in 5 minutes. This page is the comprehensive reference for when you need to look something up.
  • Photon Platform Promises: > Define intent once. Deliver everywhere.
  • Troubleshooting Guide: Comprehensive guide to diagnosing and fixing common Photon MCP issues.
  • Core Concepts: Six ideas that explain how Photon works. Each builds on the previous one.
  • Output Formats: Add @format to any method to control how its return value is displayed. Without it, Photon renders JSON. With it, you get tables, charts, diagrams, dashboards, and more.
  • Getting Started: One TypeScript file. Three interfaces. No boilerplate.
  • Advanced Photon Guide: Deep dive into Photon's advanced features, patterns, and best practices.
  • OAuth Authentication: > This guide is about photons requesting third-party OAuth tokens, such as
  • Photon Development Best Practices: Guidelines for creating high-quality, consistent Photon MCPs.
  • Build an MCP Server in TypeScript: Photon lets you build a TypeScript MCP server from one .photon.ts file. You
  • Cloudflare Bindings — Cloudflare injection: Photons reach Cloudflare resources (KV, R2, D1, Queues, Vectorize, Workers AI, Images, Browser Rendering) through a single injected dependency: Cloudflare. The same code runs locally against a miniflare sandbox and on a deployed Worker against real bindings.
  • Custom UI Development Guide: Build rich interactive UIs for your photons. A global named after your photon file is auto-injected into the iframe — call methods and subscribe to events directly (e.g., kanban.onTaskMove(cb)).
  • Photon Deployment Guide: Production deployment strategies for photon applications.
  • Photon Initialization: Complete Setup Guide: The photon init command suite configures your system for optimal Photon usage with shell integration, tab completion, and daemon auto-start.
  • Sharing Configuration Across a Marketplace of Photons: When you build a set of related photons that work together, they often need to agree on a few values: a data directory, an API base URL, a tenant ID, a sync interval. This guide covers how to do that today, the patterns to avoid, and the open enhancement that will eventually make it ergonomic.
  • Marketplace Publishing Guide: Create and manage photon marketplaces for teams, organizations, or public distribution.
  • Securing MCP with JWT: Photon can protect deployed MCP tool calls with short-lived JWT access tokens.
  • Add a UI to an MCP Server: Photon can add a UI to an MCP server without splitting your project into a
  • Photon Naming Conventions: Clean, consistent naming makes photons intuitive across all use cases: MCP servers, CLI tools, and programmatic usage.
  • Photon Injection Model — Three Ways to Author a Photon: A photon is a single TypeScript class. The runtime needs to give that class access to memory, scheduling, emit, cross-photon calls, MCP, Cloudflare bindings, and more. There are three ways the class can receive those capabilities, and you pick the one that matches your situation. Same API, same behavior — only the access path differs.
  • Protocol Features Guide: Seven protocol features that make your photons discoverable, observable, and interoperable with external agents and UIs.
  • Search Keyword Coverage: This page tracks the search and answer-engine phrases Photon should cover in
  • Search Measurement Playbook: Use this playbook to measure whether Photon is discoverable in Google Search,
  • Shell Integration: Run photons as direct terminal commands with full tab completion.
  • VS Code Support Plan: Photon now has two strong building blocks for IDE support:
  • Registering an MCP Client with a Photon AS: > This guide covers the hosted Photon authorization-server path for MCP
  • Observability: Photon ships with OpenTelemetry instrumentation baked in — traces, metrics,
  • Photon Architecture: > This document defines the vision, architecture, and constraints of Photon.
  • Auto-UI Architecture: Photon's Auto-UI system automatically generates appropriate UI components based on the data returned from .photon.ts methods. This allows developers to focus on business logic while the runtime handles presentation across different interfaces (CLI, MCP, Web).
  • Cloudflare Durable Object Bridge: How a stateful photon runs on Cloudflare Workers. Companion to
  • Constructor Context: Env Capture, Instances, and Config: Constructor parameters are Photon’s runtime contract. Photon resolves them when a photon is loaded, stores the values it owns under the current PHOTON_DIR, and replays those values when daemon-hosted photons are reconstructed after restart.
  • Constructor Injection: Photon uses a single mechanism for all dependency injection: constructor parameters. The runtime inspects each parameter and determines what to inject based on its type and matching docblock declarations.
  • Daemon Protocol: Full-featured daemon infrastructure for local development via Unix sockets. Provides pub/sub messaging, distributed locks, scheduled jobs, and webhooks.
  • Elicitation Architecture: Photon uses generator functions with yield statements for:
  • Lifecycle Hooks & Ingress Model: Status: Design approved, implementation in progress (as of 2026-04-17)
  • MCP Elicitation Implementation Plan: We have a custom generator-based elicitation system:
  • MCP OAuth Authorization for Deployed Photons: Status: V1 implementation plan for agent review
  • Middleware: Bridging Ideal Code and the Real World: Every developer writes the same boilerplate. You have a clean function that does one thing well — then you wrap it in try/catch for retries, add a cache layer, bolt on rate limiting, sprinkle timeout protection, and suddenly your 10-line function is 60 lines of infrastructure.
  • OAuth 2.1 Authorization Server: SERV ships a standards-compliant OAuth 2.1 authorization server so self-hosted photon deployments don't need an external identity provider. The AS accepts MCP clients via both Client ID Metadata Documents (CIMD, MCP 2025-11 spec) and Dynamic Client Registration (RFC 7591), with CIMD treated as the preferred path.
  • PHOTON_DIR and Namespace: Status: Canonical. Any code that disagrees is a bug.
  • Rendering Engine — Design Document: > Status: Draft
  • @stateful State Synchronization & Metadata Architecture: > This document explains how Photon synchronizes state, manages data persistence, and tracks object lifecycle through the @stateful framework.
  • Photon UX Guidelines: These conventions keep the CLI, MCP runtime, and playground output consistent and professional. Follow them when adding new commands or runtime features.
  • Claim Codes — scoped remote access: By default a Photon daemon exposes every installed photon to every
  • Photon CSV Format Specification: Version 1.0 — A backward-compatible extension to standard CSV that embeds column metadata in an optional format row.
  • Supported Docblock Tags: Photon uses JSDoc-style docblock tags to extract metadata, configure tools, and generate documentation. This page lists all supported tags organized by where they can be used.
  • Intent Metadata: Photon derives surface-neutral intent from the MCP-visible method contract. There
  • Distributed Locks: Photon provides distributed locking for concurrent access control. Locks are coordinated through the daemon and available to any photon method.
  • Long-Running Methods: The Heartbeat Contract: Photons are invoked by both humans at a terminal and by autonomous agents
  • MCP Dependencies: Consuming External MCPs: Photons can consume external MCP servers at runtime, enabling powerful orchestration workflows that combine multiple MCPs written in any language (Python, Rust, Go, Node.js, etc.).
  • MCP Primitives on this: Photon exposes the MCP protocol's user-facing primitives as methods on
  • Webhooks: Photon methods can receive HTTP webhook callbacks from external services. Webhook methods are exposed as POST endpoints on the daemon.
  • Photon TSX rendering contract: Photon ships a tiny built-in JSX runtime that maps <jsx /> to real DOM
  • From TypeScript Method to Embedded Chat UI: Weather is intentionally simple here. The point is not weather. The point is

Released under the MIT License.

Copyright Portel Dev