# Photon [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/portel-dev/photon  
**GitHub Stars:** 100  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/portel-photon

## Description
Build MCP servers, CLI tools, and web dashboards for AI agents from a single TypeScript file.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## 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:

```bash
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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/portel-photon/readme_