Photon

What Photon does

The Photon MCP server lets developers define an agent-facing capability as a TypeScript class method. Photon uses the method signature, type annotations, comments, and selected tags to derive tool definitions, input rules, documentation, and interface behavior. The implementation can then be exposed through MCP, a command-line interface, and Beam, Photon’s generated web interface.

The same source can also provide an embedded app surface for MCP clients that support app resources. Additional capabilities include web routes, schedules, webhooks, retries, state, and audit history when a capability becomes a longer-running workflow. A Photon can also be loaded from application code through the createPhotonRuntime API without starting a server.

This project is listed in the 💻 Developer Tools category and is relevant when a team wants one TypeScript implementation to serve agents, scripts, web users, and automation.

How it works

A .photon.ts file contains the capability. Photon reads exported classes and their methods, then creates the surrounding runtime and interfaces. Method parameters become tool inputs; TypeScript types contribute validation and UI field information; JSDoc supplies descriptions for clients and users. Tags can add behavior such as validation, formatting, schedules, webhooks, and HTTP routes.

For example, a method with a pattern constraint can use that rule in Beam forms, CLI execution, and the MCP schema. This keeps the validation behavior consistent across surfaces. Photon supports inheritance from Photon, constructor injection, and composition without inheritance. Cloudflare resources can be provided through separate Cloudflare injection.

The resulting MCP service can run locally through stdio, including from Claude Desktop, or be made available through a public HTTPS /mcp endpoint for clients such as ChatGPT developer mode. The repository also documents Cursor usage.

Setup and configuration

Install the package globally with Bun, scaffold a project, and start it with:

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

The new command creates a .photon.ts file in the current directory. Running photon opens the Beam interface. To register the capability with Claude Desktop, use:

photon mcp install my-tool

The package can also be run without a global installation with bunx or pnpm dlx. Node.js 20 or newer is required. Photon compiles TypeScript internally, so a tsconfig.json is not required. Project files can live in the current directory or under ~/.photon/; persistent user settings are stored under ~/.photon/state/<photon>/.

Tools and capabilities

The Photon MCP server provides or derives:

• MCP tool definitions from class methods
• CLI commands for invoking capabilities
• Beam web interfaces for human users
• Embedded app resources for compatible MCP clients
• Input validation from TypeScript types and annotations
• Documentation from JSDoc comments
• Optional routes, schedules, webhooks, retries, state, and audit history
• Runtime loading for calling Photon methods from Node.js applications

Photon is released under the MIT license. When using createPhotonRuntime, the host application remains responsible for authorization, and the loaded code runs inside the application process.