photon

Photon lets you author a TypeScript class whose methods are your capabilities. Photon then auto-generates three interfaces from a single code file: a web UI (Beam) for humans, a CLI for scripting, and an MCP server for AI agents. With a minimal class and method signatures, you get a human-friendly form, a programmable CLI, and a machine-facing MCP tool that Claude, Cursor, or any MCP-compatible client can invoke. To use the MCP server portion, you expose your photon as an MCP endpoint and provide tool metadata (names, inputs, outputs, and validation) so AI agents can discover and call your methods. The README demonstrates how to query the MCP configuration (photon info analytics --mcp) and generate a JSON spec that describes the MCP server, which can be pasted into an AI client.

Prerequisites:

• Node.js v18+ installed on your system
• npm (bundled with Node.js) or pnpm/yarn if you prefer other package managers

Installation steps:

1. Install Photon globally (or use npx for one-off usage):

npm install -g @portel/photon

2. Create a new tool with Photon (generates boilerplate and wiring):

photon maker new my-tool

3. Start Beam (optional, for human UI):

photon

If you prefer to run without installing globally, you can use npx as shown in the quick start:

npx @portel/photon maker new my-tool
npx @portel/photon

Note: The repository assumes you’re building in TypeScript; Photon compiles TypeScript internally and does not require a separate tsconfig.json in standard setups.

Tips and notes:

• Photon relies on TypeScript type information and JSDoc comments to generate UI, CLI, and MCP schemas. Keep your method signatures well-typed and document parameters for best AI understanding.
• The MCP interface produced can be consumed by Claude, Cursor, and any MCP-compliant client. You can paste the generated mcpServers JSON into your AI client’s configuration.
• Photon can also expose a custom UI via the MCP Apps Extension standard if you integrate a custom frontend for your tool.
• Environment variables can be surfaced through constructor parameters and mapped to runtime config in the Photon UI, enabling configurable behavior without code changes.
• If you modify method inputs or add new validations, the MCP schema and UI will update automatically to reflect the changes.