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

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

Documentation Index

• Photon: Photon turns a single .photon.ts file into MCP tools, CLI commands,
• 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: Photon is the fastest way to turn a small, verified TypeScript method into
• 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.
• Convert an Existing Frontend App into a Photon: 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: > Architecture note: for serious app shells and reusable client-side renderers,
• The Photon 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: 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.
• Photon Layout Lab: Photon's visual formats are rendered by the same standalone renderer in a
• 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.
• MCP 2026 compatibility release notes: The current Photon release adds release-candidate support for MCP 2026-07-28
• MCP compatibility: Photon supports existing MCP 2025 clients and the MCP 2026-07-28
• Migrating MCP roots, sampling, and logging: MCP 2026-07-28 deprecates roots, sampling, and protocol logging. The
• Inbound OAuth for MCP Photons: Inbound OAuth authenticates an MCP client to a Photon so it can discover and
• 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
• MCP 2026 Stateless Deployment: Photon's MCP 2026 HTTP surface is request-scoped. A load balancer may send
• 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: Protocol features that make your photons discoverable, observable, and
• 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:
• Photon browser sessions: Photons that declare:
• 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: > Related proposal: Client-First UI Architecture
• Cloudflare Durable Object Bridge: How a stateful photon runs on Cloudflare Workers. Companion to
• Client-First UI Architecture: > Status: Proposal
• 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 2026 Compliance and Backward-Compatibility Specification: Status: Complete; release gates passing on 2026-07-28
• MCP conformance and SDK policy: Photon keeps its canonical server/runtime types independent of SDK classes,
• 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