# 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](/docs/getting-started): Install Photon and build your first .photon.ts file.
- [Core Concepts](/docs/concepts): The mental model behind methods, comments, formats, state, settings, and surfaces.
- [From Method to Chat App](/docs/tutorials/from-method-to-chat-app): A weather example that runs as CLI, Beam, MCP, and embedded chat UI.
- [Output Formats](/docs/formats): Visual result formats for tables, charts, markdown, mermaid, cards, dashboards, and more.
- [Docblock Tags](/docs/reference/DOCBLOCK-TAGS): Public reference for every docblock tag Photon understands.
- [Complete Developer Guide](/docs/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

- npm: @portel/photon
- GitHub: https://github.com/portel-dev/photon
- License: MIT


## Documentation Index

- [Photon](/): Photon turns a single <code>.photon.ts</code> file into MCP tools, CLI commands,
- [Why Photon](/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](/readme): Photon is the fastest way to turn a small, verified TypeScript method into
- [Photon MCP Developer Guide](/docs/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](/docs/PROMISES): > Define intent once. Deliver everywhere.
- [Troubleshooting Guide](/docs/TROUBLESHOOTING): Comprehensive guide to diagnosing and fixing common Photon MCP issues.
- [Core Concepts](/docs/concepts): Six ideas that explain how Photon works. Each builds on the previous one.
- [Output Formats](/docs/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](/docs/getting-started): One TypeScript file. Three interfaces. No boilerplate.
- [Advanced Photon Guide](/docs/guides/ADVANCED): Deep dive into Photon's advanced features, patterns, and best practices.
- [OAuth Authentication](/docs/guides/AUTH): > This guide is about photons requesting third-party OAuth tokens, such as
- [Photon Development Best Practices](/docs/guides/BEST-PRACTICES): Guidelines for creating high-quality, consistent Photon MCPs.
- [Build an MCP Server in TypeScript](/docs/guides/BUILD-MCP-SERVER-TYPESCRIPT): Photon lets you build a TypeScript MCP server from one `.photon.ts` file. You
- [Cloudflare Bindings — `Cloudflare` injection](/docs/guides/CF-BINDINGS): 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.
- [Convert an Existing Frontend App into a Photon](/docs/guides/CONVERT-FRONTEND-APP): Use this guide when adapting an existing Vite, React, Vue, Svelte, Angular, or plain HTML app into a Photon custom UI. A photon can validate and still have a broken UI bundle, so treat the UI checks below as part of the definition of done.
- [Custom UI Development Guide](/docs/guides/CUSTOM-UI): > Architecture note: for serious app shells and reusable client-side renderers,
- [The Photon Daemon](/docs/guides/DAEMON): Every runtime that executes photons - Beam, `photon cli`, MCP stdio/SSE servers, scheduled jobs - delegates to a single background daemon process. No runtime runs photon code directly. The daemon owns photon instances, state, locks, schedules, and the event bus, so all clients see the same live instances.
- [Photon Deployment Guide](/docs/guides/DEPLOYMENT): Production deployment strategies for photon applications.
- [Photon Initialization: Complete Setup Guide](/docs/guides/INITIALIZATION): 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](/docs/guides/MARKETPLACE-CONFIG): 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](/docs/guides/MARKETPLACE-PUBLISHING): Create and manage photon marketplaces for teams, organizations, or public distribution.
- [MCP 2026 compatibility release notes](/docs/guides/MCP-2026-RELEASE-NOTES): Photon 1.36.1 adds release-candidate support for MCP `2026-07-28` over
- [MCP compatibility](/docs/guides/MCP-COMPATIBILITY): Photon 1.36.1 supports existing MCP 2025 clients and the MCP `2026-07-28`
- [Migrating MCP roots, sampling, and logging](/docs/guides/MCP-DEPRECATED-FEATURES): MCP `2026-07-28` deprecates roots, sampling, and protocol logging. The
- [Securing MCP with JWT](/docs/guides/MCP-JWT-AUTH): Photon can protect deployed MCP tool calls with short-lived JWT access tokens.
- [Add a UI to an MCP Server](/docs/guides/MCP-SERVER-UI): Photon can add a UI to an MCP server without splitting your project into a
- [MCP 2026 Stateless Deployment](/docs/guides/MCP-STATELESS-DEPLOYMENT): Photon's MCP 2026 HTTP surface is request-scoped. A load balancer may send
- [Photon Naming Conventions](/docs/guides/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](/docs/guides/PHOTON-INJECTION): 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](/docs/guides/PROTOCOL-FEATURES): Protocol features that make your photons discoverable, observable, and
- [Search Keyword Coverage](/docs/guides/SEARCH-KEYWORD-COVERAGE): This page tracks the search and answer-engine phrases Photon should cover in
- [Search Measurement Playbook](/docs/guides/SEARCH-MEASUREMENT): Use this playbook to measure whether Photon is discoverable in Google Search,
- [Shell Integration](/docs/guides/SHELL-INTEGRATION): Run photons as direct terminal commands with full tab completion.
- [VS Code Support Plan](/docs/guides/VSCODE-SUPPORT): Photon now has two strong building blocks for IDE support:
- [Registering an MCP Client with a Photon AS](/docs/guides/mcp-client-registration): > This guide covers the hosted Photon authorization-server path for MCP
- [Observability](/docs/guides/observability): Photon ships with OpenTelemetry instrumentation baked in — traces, metrics,
- [Photon Architecture](/docs/internals/ARCHITECTURE): > **This document defines the vision, architecture, and constraints of Photon.**
- [Auto-UI Architecture](/docs/internals/AUTO-UI-ARCHITECTURE): > Related proposal: Client-First UI Architecture
- [Cloudflare Durable Object Bridge](/docs/internals/CF-DURABLE-OBJECTS): How a stateful photon runs on Cloudflare Workers. Companion to
- [Client-First UI Architecture](/docs/internals/CLIENT-FIRST-UI-ARCHITECTURE): > Status: Proposal
- [Constructor Context: Env Capture, Instances, and Config](/docs/internals/CONSTRUCTOR-CONTEXT): 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](/docs/internals/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](/docs/internals/DAEMON-PUBSUB): Full-featured daemon infrastructure for local development via Unix sockets. Provides pub/sub messaging, distributed locks, scheduled jobs, and webhooks.
- [Elicitation Architecture](/docs/internals/ELICITATION-ARCHITECTURE): Photon uses generator functions with `yield` statements for:
- [Lifecycle Hooks & Ingress Model](/docs/internals/LIFECYCLE-AND-INGRESS): **Status**: Design approved, implementation in progress (as of 2026-04-17)
- [MCP 2026 Compliance and Backward-Compatibility Specification](/docs/internals/MCP-2026-COMPLIANCE-SPEC): **Status:** Complete; release gates passing on 2026-07-28
- [MCP conformance and SDK policy](/docs/internals/MCP-CONFORMANCE): Photon keeps its protocol model independent of the official TypeScript SDK.
- [MCP Elicitation Implementation Plan](/docs/internals/MCP-ELICITATION-IMPLEMENTATION): We have a **custom generator-based elicitation** system:
- [MCP OAuth Authorization for Deployed Photons](/docs/internals/MCP-OAUTH-AUTHZ-PROPOSAL): Status: V1 implementation plan for agent review
- [Middleware: Bridging Ideal Code and the Real World](/docs/internals/MIDDLEWARE): 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](/docs/internals/OAUTH-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](/docs/internals/PHOTON-DIR-AND-NAMESPACE): **Status**: Canonical. Any code that disagrees is a bug.
- [Rendering Engine — Design Document](/docs/internals/RENDERING-ENGINE): > Status: Draft
- [@stateful State Synchronization & Metadata Architecture](/docs/internals/STATEFUL-STATE-SYNC): > **This document explains how Photon synchronizes state, manages data persistence, and tracks object lifecycle through the @stateful framework.**
- [Photon UX Guidelines](/docs/internals/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](/docs/reference/CLAIM-CODES): By default a Photon daemon exposes every installed photon to every
- [Photon CSV Format Specification](/docs/reference/CSV-FORMAT): **Version 1.0** — A backward-compatible extension to standard CSV that embeds column metadata in an optional format row.
- [Supported Docblock Tags](/docs/reference/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](/docs/reference/INTENT-METADATA): Photon derives surface-neutral intent from the MCP-visible method contract. There
- [Distributed Locks](/docs/reference/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](/docs/reference/LONG-RUNNING-METHODS): Photons are invoked by both humans at a terminal and by autonomous agents
- [MCP Dependencies: Consuming External MCPs](/docs/reference/MCP-DEPENDENCIES): 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`](/docs/reference/MCP-PRIMITIVES): Photon exposes the MCP protocol's user-facing primitives as methods on
- [Webhooks](/docs/reference/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](/docs/tsx-rendering): Photon ships a tiny built-in JSX runtime that maps `<jsx />` to real DOM
- [From TypeScript Method to Embedded Chat UI](/docs/tutorials/from-method-to-chat-app): Weather is intentionally simple here. The point is not weather. The point is