Photon

Un marco de TypeScript que convierte una sola clase en un servidor MCP, herramienta CLI y panel web con un mercado de 35 fotones listos para usar.

GitHub

Prueba este MCPPatrocinado

Documentación

Una capacidad de TypeScript se convierte en toda la pila de agentes.

Photon es la forma más rápida de convertir un método pequeño y verificado de TypeScript en algo que los humanos puedan operar y los agentes puedan confiar. Escribe la capacidad una vez; Photon deriva las interfaces, los contratos y el comportamiento en tiempo de ejecución a su alrededor:

Servidor MCP para Claude, ChatGPT, Cursor y agentes
UI de aplicación integrada para clientes de chat que admiten recursos de aplicaciones MCP
Herramienta CLI para scripts, demostraciones y automatización
Interfaz web Beam para humanos
Rutas web, horarios, webhooks, reintentos, estado e historial de auditoría cuando la capacidad crece hasta convertirse en un flujo de trabajo de producción

Photon es software gratuito y de código abierto publicado bajo la licencia MIT. La documentación completa está en photon.portel.dev.

Proyecto relacionado de Portel: NCP brinda a los agentes una interfaz MCP natural para descubrir y ejecutar herramientas en todo un ecosistema de herramientas. Photon construye capacidades confiables orientadas a agentes; NCP ayuda a los agentes a encontrarlas y usarlas junto con todas las demás MCP.

Pruébalo en dos minutos:

bun add -g @portel/photon
photon new my-tool
photon

Eso abre Beam, la UI humana generada. Agrega photon mcp install my-tool cuando quieras la misma capacidad dentro de Claude Desktop u otro cliente MCP.

Las interfaces son opcionales. La intención es obligatoria.

gh repo star portel-dev/photon

De un método a todas las superficies

El ejemplo del clima es intencionalmente pequeño: un método de TypeScript, algunas etiquetas de docblock y un activo HTML @ui. Photon lo convierte en un comando CLI, una UI de Beam, una herramienta MCP y una superficie de aplicación integrada para clientes de chat compatibles con aplicaciones MCP. Claude Desktop puede ejecutarlo desde un comando MCP stdio local; el modo desarrollador de ChatGPT puede conectarse al mismo Photon a través de un endpoint HTTPS público /mcp.

Infographic showing one Photon method becoming CLI, Beam, MCP, Claude Desktop, ChatGPT, and other agent surfaces

Clientes reales, mismo Photon:

_{El modo desarrollador de ChatGPT renderizando la UI del clima de Photon desde un endpoint HTTPS público /mcp.} _{Claude Desktop renderizando el mismo Photon a través de MCP local.}

Sigue el tutorial paso a paso o abre el ejemplo ejecutable en examples/weather-showcase. El tutorial también incluye Beam, CLI y una animación conceptual para la transformación completa.

La Promesa de Photon

Photon es la pila de desarrollo moderna para la era de los agentes: cada photon es un ladrillo pequeño y auditable que pueden usar humanos, agentes, programadores, webhooks y aplicaciones sin reescribir la misma capacidad para cada interfaz.

Photon agentic stack infographic showing one intent becoming MCP contracts, human surfaces, apps, operations, trust boundaries, and composable systems

Esa es la idea central: las capacidades diminutas y confiables se componen en sistemas más grandes. Un photon puede comenzar como un método auxiliar, convertirse en un comando CLI, renderizarse como una aplicación, ejecutarse en un horario, aceptar webhooks y aún así exponer un contrato limpio y legible por agentes.

Ejemplo

// hello.photon.ts
export default class Hello {
  greet(name: string) {
    return `Hello, ${name}!`;
  }
}

Eso es un photon completo. De este único archivo obtienes:

$ photon cli hello greet --name Ada        # CLI
$ photon                                    # Web UI at localhost:3008
$ photon mcp hello                          # MCP server for Claude, Cursor, etc.

Sin decoradores. Sin registro. Sin código repetitivo de servidor. Solo define la intención. Photon se encarga del resto.

Inicio Rápido

De cero a un servidor MCP conectado a Claude Desktop en tres comandos:

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.

¿Prefieres el panel web? Omite el paso 3 y ejecuta photon en su lugar: abre Beam, la UI generada automáticamente.

O prueba sin instalar globalmente:

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

Requiere Node.js 20+. TypeScript se compila internamente; no se necesita tsconfig.json.

¿Dónde viven los archivos photon? ./ (un directorio de proyecto al que haces cd) o ~/.photon/ (global, autodetectado). La configuración del usuario persiste en ~/.photon/state/<photon>/. Consulta Dónde viven las cosas.

Cómo Funciona

Escribes una clase de TypeScript. Los métodos son tus capacidades. Los tipos describen lo que es válido. Los comentarios explican la intención. Photon lee todo y genera tres interfaces a partir de un archivo. Misma lógica. Misma validación. Mismos datos.

Six Photon core concepts: methods, comments, types and tags, settings, UI and routes, and operations

analytics.photon.ts  →  Web UI (Beam)  ·  CLI  ·  MCP Server for AI

Cuanto más expresas, más deriva Photon:

Lo que escribes	Lo que Photon deriva
Firmas de métodos	Definiciones de herramientas: nombres, entradas, salidas
Anotaciones de tipos	Reglas de validación de entrada, tipos de campos de UI
Comentarios JSDoc	Documentación para clientes de IA y usuarios humanos
Parámetros del constructor	UI de configuración, mapeo de variables de entorno, inyección en tiempo de ejecución (`Photon`, `Cloudflare`, `CloudflareEnv`)
`@tags`	Validación, formato, programación, webhooks

Cuando agregas una anotación @param city {@pattern ^[a-zA-Z\s]+$}, Beam la valida en el formulario, el CLI la valida antes de ejecutar y el esquema MCP la aplica para la IA. Una anotación. Tres consumidores.

Tres formas de crear

extends Photon es una forma. También puedes inyectar Photon como parámetro del constructor cuando ya extiendes otra cosa, o componer sin herencia: la misma API de cualquier manera. Los recursos CF llegan al photon a través de una inyección separada Cloudflare para que los photons portátiles sigan siendo portátiles. Consulta docs/guides/PHOTON-INJECTION.md.

Beam: Exploración Humana

Beam es el panel web. Cada photon se convierte automáticamente en un formulario interactivo. Ejecuta photon. Ese es el comando completo.

La UI está completamente generada automáticamente a partir de tus firmas de métodos: tipos de campos, validación, valores predeterminados, diseños. Nunca escribes código frontend. Cuando agregas una etiqueta {@choice a,b,c} a un parámetro, Beam renderiza un menú desplegable. Cuando marcas una cadena como {@format email}, el campo valida el formato de correo electrónico. La UI evoluciona a medida que evoluciona tu código.

Cuando los formularios no son la interfaz adecuada para lo que estás construyendo, puedes reemplazar la vista generada automáticamente de Beam con tu propio HTML. Se inyecta automáticamente una global con el nombre de tu photon (por ejemplo, analytics.onResult(data => ...)): no se requiere framework. window.photon.url también se inyecta y resuelve a la URL base de Beam para que tu HTML pueda construir rutas fetch correctamente, ya sea que se ejecute localmente o detrás de un proxy inverso.

Las UI personalizadas siguen la Extensión oficial de Aplicaciones MCP y funcionan en hosts compatibles. Consulta la Guía de UI Personalizada.

Los photons que declaran rutas HTTP con @get, @post, @put, @patch o @delete se muestran en Beam como aplicaciones web. Las rutas admiten segmentos de ruta dinámicos (por ejemplo, @get /items/:id) que coinciden por especificidad: los segmentos literales ganan sobre los parámetros. Beam envía solicitudes a esas rutas e inyecta un encabezado x-photon-base-path para que la aplicación pueda construir rutas absolutas correctas independientemente de dónde esté alojado Beam.

Agentes de IA: Invocación Automática

Photon incluye adaptadores MCP separados y probados: MCP 2025 con sesión sobre stdio y HTTP Streamable, además de soporte de candidato a lanzamiento MCP 2026-07-28 sin estado sobre HTTP Streamable. Consulta la matriz de compatibilidad y clientes ejecutables, o ejecuta photon doctor mcp contra tu runtime instalado.

photon info analytics --mcp

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

Pégalo en la configuración de tu cliente de IA. Tu photon ahora es un servidor MCP. Claude puede llamar a tus métodos. Cursor puede llamar a tus métodos. Cualquier host compatible con MCP puede llamar a tus métodos.

La IA ve lo mismo que ve un humano en Beam: los nombres de los métodos, las descripciones de parámetros de tu JSDoc, las reglas de validación de tus tipos. El comentario JSDoc que escribiste para documentar la herramienta para ti mismo es lo que Claude lee para decidir cuándo y cómo llamarla.

Las herramientas MCP funcionan con Claude Desktop, Claude Code, Cursor y cualquier cliente compatible con MCP. Cuando tu photon tiene una UI personalizada, los clientes que admiten la Extensión de Aplicaciones MCP pueden renderizarla de forma nativa, como se muestra en la prueba del clima anterior.

Cómo Evoluciona un Photon

Así es como crece un photon. Cada paso agrega una cosa y obtiene múltiples capacidades de ella.

Agrega comentarios: la IA entiende tu intención

/**
 * 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 }) { ... }
}

La descripción de la clase se convierte en cómo los clientes de IA presentan la herramienta a los usuarios. La descripción de @param es lo que la IA lee antes de decidir qué valor pasar. Mismos comentarios. Texto de ayuda humano y contrato de IA a la vez.

Declara configuración: aparece una herramienta de ajustes

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 es la forma canónica de exponer perillas de tiempo de ejecución. Photon lee el JSDoc de cada propiedad, genera una herramienta MCP settings con entradas tipadas y persiste los cambios del usuario en ~/.photon/state/<photon>/<instance>-settings.json. Dentro de los métodos, this.settings es un Proxy de solo lectura. Para cambiar un valor, el usuario (o la IA) llama a la herramienta generada automáticamente settings.

Para secretos que nunca deben persistirse en un archivo de configuración (claves de API, tokens), usa un parámetro del constructor en su lugar. Photon mapea el nombre del parámetro a una variable de entorno:

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

El patrón del constructor es para primitivas que provienen de .env. El patrón protected settings es para todo lo demás, incluida cualquier perilla que el usuario deba poder cambiar en tiempo de ejecución sin reiniciar. En caso de duda, usa settings.

Agrega etiquetas: el comportamiento se extiende por todas las superficies

/**
 * @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 instala node-fetch automáticamente en la primera ejecución, sin necesidad de instalación manual de paquetes. El {@pattern} valida en el formulario, el CLI y el esquema MCP simultáneamente. days se convierte en un selector de números con límites. @format table renderiza el resultado como una tabla en Beam. Una anotación, tres superficies.

Dependencias CLI del sistema

Si tu photon envuelve una herramienta de línea de comandos, declárala y Photon la aplica en el momento de la carga:

/**
 * @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
  }
}

Lo Que Viene Gratis

Cosas que no construyes porque Photon las maneja:


Auto-UI	Formularios, tipos de campo, validación y diseños generados a partir de tus firmas
Instancias con estado	Múltiples instancias nombradas del mismo photon, cada una con estado aislado
Memoria persistente	`this.memory` le da a tu photon almacenamiento clave-valor por instancia, sin necesidad de base de datos
Ejecución programada	`@scheduled` ejecuta cualquier método en un horario cron
Webhooks	`@webhook` expone cualquier método como endpoint HTTP
OAuth (cliente)	Flujos OAuth 2.0 integrados para Google, GitHub, Microsoft
Servidor de autorización OAuth	Emite tokens a clientes MCP tú mismo: CIMD + DCR, PKCE, OIDC id_token, intercambio de tokens RFC 8693
Persistencia SQLite	El registro de auditoría, el historial de ejecución y las concesiones OAuth sobreviven al reinicio del daemon (bun:sqlite o better-sqlite3)
Operaciones del daemon	`photon ps` lista y controla trabajos programados, webhooks y sesiones en vivo
Bloqueos distribuidos	`@locked` serializa el acceso: un llamador a la vez, entre procesos
Llamadas entre photons	`this.call()` invoca los métodos de otro photon
Runtime Cloudflare	`this.cf.r2('blobs')`, `this.cf.d1('app')`, `this.cf.kv('cache')` — la misma forma localmente (miniflare) y desplegado (bindings reales). Ver CF-BINDINGS.md
Eventos en tiempo real	`this.emit()` dispara eventos nombrados a la UI del navegador sin cableado alguno
Renderizado en vivo	`this.render()` envía salida formateada a CLI y Beam en tiempo real
LLM delegado	`this.sample()` pide al modelo del agente conductor que genere texto — sin clave API, el agente paga
Confirmación / entrada en línea	`this.confirm()` y `this.elicit()` se enrutan a través de la UI nativa del cliente (diálogo de Beam, prompt de Claude)
Acceso remoto con alcance	`photon claim` genera un código de corta duración para limitar una sesión MCP remota a un directorio
Binarios independientes	`photon build` compila cualquier photon a un único ejecutable mediante Bun
Gestión de dependencias	`@dependencies` instala automáticamente paquetes npm en la primera ejecución

Coordinación: Bloqueos + Eventos

Dos primitivas. Juntas desbloquean una clase de cosas que hoy son sorprendentemente difíciles de construir.

Los bloqueos serializan el acceso. Cuando un método está marcado con @locked, solo un llamador puede ejecutarlo a la vez, ya sea un humano en Beam, un script de CLI o un agente de IA. Todos los demás esperan su turno.

Los eventos envían cambios de estado a cualquier UI del navegador en tiempo real. this.emit({ event: 'boardUpdated', data: board }) en el servidor se convierte en chess.onBoardUpdated(handler) en tu UI personalizada — nombrado según tu archivo de photon. Sin WebSockets que configurar. Sin polling. Los eventos se entregan vía SSE a través del transporte MCP Streamable HTTP.

Juntos: coordinación por turnos con estado en vivo.

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' });

Un humano se mueve a través de Beam. Claude está configurado con el servidor MCP. El bloqueo garantiza que realmente se alternen. Los eventos mantienen el tablero en vivo en ambos lados. Eso es un juego de ajedrez por turnos completamente funcional, humano vs IA, en unas 50 líneas de lógica de aplicación.

El mismo patrón se aplica más allá de los juegos: flujos de aprobación donde un humano revisa antes de que la IA continúe, herramientas colaborativas donde las ediciones de cualquier fuente aparecen al instante, simulaciones donde los pasos deben ejecutarse en secuencia estricta, cualquier sistema donde importa quién actúa después.

Primitivas MCP en `this`

Las primitivas orientadas al usuario del protocolo MCP se exponen como métodos simples en cada instancia de photon — sin decoradores, sin banderas de capacidad, sin imports de SDK. El runtime enruta cada llamada a través de la superficie por la que llegó la solicitud (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<string>({
      ask: 'select',
      message: 'Which environment?',
      options: ['staging', 'prod'],
    });
    await this.run(env);
  }
}

Primitiva	Qué hace
`await this.sample({ prompt })`	Delega la generación de LLM al modelo del llamador vía muestreo MCP
`await this.confirm(question)`	Prompt de sí/no — devuelve `boolean`
`await this.elicit(params)`	Entrada arbitraria (texto, selección, formulario, archivo, etc.)
`this.status(msg)` / `this.progress(v)`	Retroalimentación en vivo durante trabajos largos; se enruta al flujo SSE en Beam
`this.roots`	Raíces de workspace MCP declaradas por el cliente conectado (`roots/list`)
`this.notifyResourceUpdated(uri)`	Envía `notifications/resources/updated` a clientes suscritos

Referencia completa: docs/reference/MCP-PRIMITIVES.md.

Acceso Remoto: Códigos de Reclamación

Por defecto, cada photon instalado es visible para cada cliente MCP conectado. Cuando quieras emparejar un agente remoto con un subconjunto de tus photons — tu teléfono manejando Beam, un compañero revisando un proyecto, un agente de CI limitado a un solo directorio — genera un código de reclamación:

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

El cliente remoto presenta el código como el encabezado Mcp-Claim-Code en su sesión MCP. tools/list entonces solo expone photons cuyo código fuente se encuentre bajo ese directorio. Las sesiones sin código mantienen acceso completo — la función es estrictamente opt-in.

Referencia completa: docs/reference/CLAIM-CODES.md.

Marketplace

Un conjunto curado de photons está listo para instalar. La galería pública se mantiene pequeña a propósito: aplicaciones y herramientas pulidas en un lugar, ejemplos de aprendizaje en otro.

photon search boards
photon add boards

También puedes instalar directamente desde cualquier repositorio de GitHub usando refs calificados:

photon add owner/repo/photon-name

Explora el marketplace de Photon Apps para photons listos para usar, o el marketplace de Photon Examples para ejemplos de aprendizaje enfocados. También puedes alojar un marketplace privado para tu equipo: herramientas internas que permanecen fuera de la internet pública.

Comandos

# Run
photon                            # Open Beam UI
photon mcp <name>                 # Run as MCP server
photon mcp <name> --dev           # MCP server with hot reload
photon cli <name> [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 <name>           # Scaffold a new photon

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

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

# Marketplace
photon add <name>                 # Install photon
photon search <query>             # 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`: trabajos programados, webhooks y sesiones

photon ps es la superficie de operador para el daemon. Sin argumentos imprime una instantánea de cuatro secciones — PROGRAMACIONES ACTIVAS, DECLARADAS-pero- no-inscritas, WEBHOOKS y SESIONES ACTIVAS.

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

Modelo de dos pasos. Una anotación @scheduled en el código fuente está DECLARADA hasta que se inscribe. La inscripción es por máquina, persistente y explícita:

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

Para horarios cron manuales sin una etiqueta @scheduled, usa el panel Beam Pulse ("Añadir horario") o llama a this.schedule.create() desde el código del photon.

this.schedule.create() (horarios programáticos) omite DECLARADA y va directamente a ACTIVA. Ver docs/GUIDE.md#scheduling para la referencia completa, el diseño del estado del daemon y .photon-no-host para configuraciones multi-host.

Instalar desde GitHub

Usa refs calificados para instalar y ejecutar photons directamente desde cualquier repositorio de GitHub:

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

El formato es owner/repo/photon-name. Las dependencias @photon transitivas del mismo repositorio se resuelven automáticamente.

Compilar a Binario

Construye ejecutables independientes desde cualquier photon — sin necesidad de Node.js en la máquina de destino:

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

Usa el compilador de Bun internamente. El binario agrupa el photon, sus @dependencies y las dependencias @photon transitivas en un solo archivo.

Referencia de Etiquetas

Etiqueta	Dónde	Qué hace
`@dependencies`	Clase	Instala automáticamente paquetes npm en la primera ejecución
`@cli`	Clase	Declara dependencias CLI del sistema, verificadas al cargar
`@format`	Método	Renderizado de resultados (tabla, lista, markdown, código, etc.)
`@param ... {@choice a,b,c}`	Parámetro	Selección desplegable en Beam
`@param ... {@choice-from method}`	Parámetro	Desplegable dinámico poblado desde el valor de retorno de otro método
`@param ... {@format email}`	Parámetro	Validación de entrada y tipo de campo
`@param ... {@min N} {@max N}`	Parámetro	Restricciones de rango numérico
`@ui`	Clase/Método	Vincula una plantilla HTML personalizada
`@auth`	Clase	Requiere o describe autenticación MCP y puebla `this.caller`
`@scope`	Método	Anula el alcance OAuth inferido para una llamada de herramienta MCP protegida
`@expose`	Método	Auto-vincula a `POST /api/<kebab>` para fetch SPA (`public` omite la compuerta SameSite)
`@get /path`	Método	Ruta GET solo HTTP; se muestra como aplicación web en Beam, no como herramienta MCP. Soporta segmentos `:param`
`@post /path`	Método	Ruta POST solo HTTP; se muestra como aplicación web en Beam, no como herramienta MCP. Soporta segmentos `:param`
`@put /path`	Método	Ruta PUT solo HTTP; se muestra como aplicación web en Beam, no como herramienta MCP. Soporta segmentos `:param`
`@patch /path`	Método	Ruta PATCH solo HTTP; se muestra como aplicación web en Beam, no como herramienta MCP. Soporta segmentos `:param`
`@delete /path`	Método	Ruta DELETE solo HTTP; se muestra como aplicación web en Beam, no como herramienta MCP. Soporta segmentos `:param`
`@resource <uri>`	Método	Resolvedor dinámico de recursos MCP (forma canónica; reemplaza a `@Static`)
`@prompt`	Método	Plantilla de prompt MCP (forma canónica; reemplaza a `@Template`)
`@webhook`	Método	Expone como endpoint HTTP
`@scheduled`	Método	Ejecuta en un horario cron
`@locked`	Método	Bloqueo distribuido entre procesos
`@autorun`	Método	Auto-ejecuta al seleccionarse en Beam
`@mcp`	Clase	Inyecta otro servidor MCP como dependencia
`@icon`	Clase/Método	Establece icono emoji

Ver la Referencia de Etiquetas completa para las 30+ etiquetas con ejemplos.

Documentación

Empieza aquí:

Guía
Getting Started	Instala, construye y ejecuta tu primer photon en 5 minutos
From Method to Chat App	Demostración de clima: CLI, Beam, MCP y UI de aplicación embebida desde un solo método
Core Concepts	Las 6 ideas detrás de Photon
Tag Reference	Referencia pública para cada etiqueta docblock que Photon entiende
Output Formats	Galería visual de cada tipo de `@format`
Intent Metadata	Cómo comentarios, esquemas, anotaciones y formatos se mapean a superficies nativas
Settings	Declara perillas de runtime con `protected settings` (el patrón de configuración canónico)
Troubleshooting	Problemas comunes y soluciones

Profundiza:

Tema
Custom UI	Construye interfaces interactivas ricas con la API de puente de photon
OAuth	OAuth 2.0 integrado con Google, GitHub, Microsoft
MCP JWT Auth	Asegura llamadas de herramientas MCP desplegadas con JWTs de alcance limitado y corta duración
MCP Client Registration	Registra clientes MCP con el AS de Photon vía CIMD o DCR
Observability	Trazas OpenTelemetry, métricas, registros y errores estructurados
Protocol Features	Handshake de capacidades, errores estructurados, correlación de trazas
Daemon Pub/Sub	Mensajería en tiempo real entre procesos
Webhooks	Endpoints HTTP para servicios externos
Locks	Bloqueos distribuidos para acceso exclusivo
Advanced Patterns	Hooks de ciclo de vida, inyección de dependencias, flujos de trabajo interactivos
Marketplace Configuration	Compartir configuraciones entre photons relacionados en un marketplace
Deployment	Docker, Cloudflare Workers, AWS Lambda, Systemd

Opera:

Tema
The Photon Daemon	Ciclo de vida, resolución de PHOTON_DIR, resiliencia, solución de problemas
Security	Mejores prácticas y lista de verificación de auditoría
Marketplace Publishing	Crea y comparte marketplaces de equipo
Best Practices	Patrones para photons de producción

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

Código Abierto

Photon es gratuito y de código abierto bajo la licencia MIT. El proyecto sigue evolucionando y las contribuciones son bienvenidas.

Marca el repositorio con una estrella si la idea te resulta interesante: gh repo star portel-dev/photon
Reporta problemas
Contribuye con mejoras o ejemplos

Photon

Documentación

Una capacidad de TypeScript se convierte en toda la pila de agentes.

De un método a todas las superficies

La Promesa de Photon

Ejemplo

Inicio Rápido

Cómo Funciona

Tres formas de crear

Beam: Exploración Humana

Agentes de IA: Invocación Automática

Cómo Evoluciona un Photon

Agrega comentarios: la IA entiende tu intención

Declara configuración: aparece una herramienta de ajustes

Agrega etiquetas: el comportamiento se extiende por todas las superficies

Dependencias CLI del sistema

Lo Que Viene Gratis

Coordinación: Bloqueos + Eventos

Primitivas MCP en this

Acceso Remoto: Códigos de Reclamación

Marketplace

Comandos

photon ps: trabajos programados, webhooks y sesiones

Instalar desde GitHub

Compilar a Binario

Referencia de Etiquetas

Documentación

Código Abierto

Primitivas MCP en `this`

`photon ps`: trabajos programados, webhooks y sesiones