Photon Examples

Example photons for the Photon runtime — every file is a complete, working MCP server.

Quick Start

npm install -g @portel/photon     # Install the runtime
photon beam                       # Open the web UI

Then install any example:

photon add walkthrough            # Interactive tutorial
photon add render-showcase        # All 48 output formats
photon add input-showcase         # All 22 input widgets

What's a Photon?

A single .photon.ts file that becomes a full MCP server. Every public method becomes a tool:

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

That's it. Run with photon beam, photon cli hello greet --name World, or connect from Claude/Cursor.

Examples

Learning

Photon	What You'll Learn
walkthrough	15-slide interactive tutorial — parameters, formats, state, streaming, custom UI, deployment
render-showcase	All 48 @format types — table, gauge, chart, metric, timeline, calendar, map, and more
input-showcase	All 22 input widgets — date picker, tags, rating, segmented, code editor, markdown

Real-World Patterns

Photon	Pattern
pizzaz-shop	E-commerce with menu, cart, orders — @stateful + structured output
shopping-cart	Cart management — add, remove, checkout flow
deploy-pipeline	Multi-stage deployment with rollback — async operations
background-job	Job queue with progress tracking — async * generators

Advanced Features

Photon	Feature
ag-ui-showcase	AG-UI protocol events — streaming, progress, state snapshots
context-aware	Environment detection and adaptive behavior
discoverable	Service capability metadata for agent discovery
observable	Real-time computation streaming with yield

Custom UI Templates

HTML templates using declarative data-method bindings — zero JavaScript:

Template	UI Pattern
dashboard.template.html	Multi-widget dashboard with live data bindings
remote.template.html	TV remote control with button grid
keypad.template.html	Numeric keypad with display
player.template.html	Media player controls

Usage

Web UI (Beam)

photon beam                          # All photons in sidebar
photon beam walkthrough              # Focus on one photon

CLI

photon cli walkthrough main          # View walkthrough slides
photon cli render-showcase table     # See table rendering
photon cli input-showcase rate       # Try star rating widget
photon cli pizzaz-shop menu          # Browse the pizza menu

MCP (Claude, Cursor, etc.)

photon mcp render-showcase --config  # Generate MCP config JSON

Contributing

Create a .photon.ts file in local/ and submit a PR. Guidelines:

• One file per photon — self-contained, no external dependencies if possible
• Single-word method names — start, add, list, not startGame, addItem
• Use @format — show off the rendering system
• Include JSDoc — descriptions become tool descriptions for LLMs
• Keep assets separate — slides, images, HTML in a subfolder named after the photon

photon-examples

Singular focus. Precise target.

Photons are single-file TypeScript MCP servers that supercharge AI assistants with focused capabilities. Each photon delivers ONE thing exceptionally well - from filesystem operations to cloud integrations.

Built on the Model Context Protocol (MCP), photons are:

• 📦 One-command install via Photon CLI
• 🎯 Laser-focused on singular capabilities
• ⚡ Zero-config with auto-dependency management
• 🔌 Universal - works with Claude Desktop, Claude Code, and any MCP client

📦 Available Photons

Photon	Focus	Tools	Features
Ag Ui Showcase	AG-UI Event Showcase Demonstrates how photon yields map to AG-UI protocol events. String yields become TEXT_MESSAGE events, progress yields become STEP events, and return values become STATE_SNAPSHOT events.	3	⚡
Background Job	Background Job Processor Demonstrates MCP Tasks for fire-and-forget async operations. Designed for tasks/create — the client gets a task ID immediately and polls tasks/get for progress and results.	2	⚡
Context Aware	Context-Aware Photon Demonstrates bidirectional state exposure where frontend widget state flows into photon methods via this._clientState.	2	-
Deploy Pipeline	Deploy Pipeline Demonstrates persistent approvals for destructive operations. Approval confirmations survive page navigation and server restarts.	2	⚡
Discoverable	Discoverable Service Demonstrates Server Cards and A2A Agent Cards. Both card types are auto-generated from the same photon metadata — rich docblocks, @stateful tag, and method descriptions map directly to MCP Server Card tools and A2A Agent Card skills.	3	-
Docs	Docs — Markdown Document Editor with PDF Export A document editor backed by plain markdown files with YAML frontmatter. Each instance is a document: _use('quarterly-report') → quarterly-report.md. Pass a full path to open any file: _use('/path/to/doc.md'). Features page-aware preview via Paged.js, TOC generation, footnotes, custom containers (note/warning/tip), multi-column layouts, and PDF export.	11	🎨
Input Showcase	Input Showcase Demonstrates all input format types in the Photon auto-UI. Each method showcases a different input widget.	22	-
Observable	Observable Computation Service Demonstrates OpenTelemetry GenAI instrumentation. When @opentelemetry/api is installed, all tool calls produce gen_ai.tool.call spans with standardized attributes. Without the package, everything works with zero overhead.	2	-
Pizzaz Shop	AI Pizza Ordering Assistant Demonstrates the AI+Human transaction workflow for food ordering: 1. AI suggests pizzas based on preferences 2. Human selects and customizes items 3. Human reviews cart and confirms order 4. System processes order with delivery info	5	⚡
Render Showcase	Render Showcase Demonstrates photon.render() — how custom UIs can use auto UI format renderers (table, gauge, chart, etc.) without building everything from scratch. Each method returns sample data in a shape that a specific format renderer understands. The custom UI dashboard calls photon.render(container, data, format) to visualize them.	13	🎨🎨
Shopping Cart	AI Shopping Assistant Demonstrates the AI+Human transaction workflow for e-commerce: 1. AI suggests products based on query 2. Human reviews and selects items 3. Human confirms purchase 4. System processes order	4	⚡
Slides	Slides — AI-Native Presentation Tool Each instance is a deck: _use('quarterly-review') → quarterly-review.md. Pass a full path to open any markdown file: _use('/path/to/deck.md').	14	🎨🎨
Spreadsheet	Spreadsheet — CSV-backed spreadsheet with formulas A spreadsheet engine that works on plain CSV files. Formulas (=SUM, =AVG, etc.) are stored directly in CSV cells and evaluated at runtime. Named instances map to CSV files: _use('budget') → budget.csv in your spreadsheets folder. Pass a full path to open any CSV: _use('/path/to/data.csv').	37	🎨🎨
Walkthrough	Photon Walkthrough An interactive step-by-step guide to building photons. Every demo is a real method on this photon — zero external dependencies. The slides show code for named classes, but the live UI calls these methods.	8	⚡⚡

Total: 14 photons ready to use

---

🚀 Quick Start

1. Install Photon

npm install -g @portel/photon

2. Add Any Photon

photon add filesystem
photon add git
photon add aws-s3

3. Use It

# Run as MCP server
photon mcp filesystem

# Get config for your MCP client
photon get filesystem --mcp

Output (paste directly into your MCP client config):

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

Add the output to your MCP client's configuration. Consult your client's documentation for setup instructions.

That's it! Your AI assistant now has 14 focused tools at its fingertips.

---

🎨 Claude Code Integration

This marketplace is also available as a Claude Code plugin, enabling seamless installation of individual photons directly from Claude Code's plugin manager.

Install as Claude Code Plugin

# In Claude Code, run:
/plugin marketplace add portel-dev/photons

Once added, you can install individual photons:

# Install specific photons you need
/plugin install filesystem@photons-marketplace
/plugin install git@photons-marketplace
/plugin install knowledge-graph@photons-marketplace

Benefits of Claude Code Plugin

• 🎯 Granular Installation: Install only the photons you need
• 🔄 Auto-Updates: Plugin stays synced with marketplace
• ⚡ Zero Config: Photon CLI auto-installs on first use
• 🛡️ Secure: No credentials shared with AI (interactive setup available)
• 📦 Individual MCPs: Each photon is a separate installable plugin

How This Plugin Is Built

This marketplace doubles as a Claude Code plugin through automatic generation:

# Generate marketplace AND Claude Code plugin files
photon maker sync --claude-code

This single command:

1. Scans all .photon.ts files
2. Generates .marketplace/photons.json manifest
3. Creates .claude-plugin/marketplace.json for Claude Code
4. Generates documentation for each photon
5. Creates auto-install hooks for seamless setup

Result: One source of truth, two distribution channels (Photon CLI + Claude Code).

---

⚛️ What Are Photons?

Photons are laser-focused modules - each does ONE thing exceptionally well:

• 📁 Filesystem - File operations
• 🐙 Git - Repository management
• ☁️ AWS S3 - Cloud storage
• 📅 Google Calendar - Calendar integration
• 🕐 Time - Timezone operations
• ... and more

Each photon delivers singular focus to a precise target.

Key Features:

• 🎯 Each photon does one thing perfectly
• 📦 14 production-ready photons available
• ⚡ Auto-installs dependencies
• 🔧 Works out of the box
• 📄 Single-file design (easy to fork and customize)

🎯 The Value Proposition

Before Photon

For each MCP server:

1. Find and clone the repository
2. Install dependencies manually
3. Configure environment variables
4. Write MCP client config JSON by hand
5. Repeat for every server

With Photon

# Install from marketplace
photon add filesystem

# Get MCP config
photon get filesystem --mcp

Output (paste directly into your MCP client config):

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

That's it. No dependencies, no environment setup, no configuration files.

Difference:

• ✅ One CLI, one command
• ✅ Zero configuration
• ✅ Instant installation
• ✅ Auto-dependencies
• ✅ Consistent experience

💡 Use Cases

For Claude Users:

photon add filesystem git github-issues
photon get --mcp  # Get config for all three

Add to Claude Desktop → Now Claude can read files, manage repos, create issues

For Teams:

photon add postgres mongodb redis
photon get --mcp

Give Claude access to your data infrastructure

For Developers:

photon add docker git slack
photon get --mcp

Automate your workflow through AI

🔍 Browse & Search

# List all photons
photon get

# Search by keyword
photon search calendar

# View details
photon get google-calendar

# Upgrade all
photon upgrade

🏢 For Enterprises

Create your own marketplace:

# 1. Organize photons
mkdir company-photons && cd company-photons

# 2. Generate marketplace
photon maker sync

# 3. Share with team
git push origin main

# Team members use:
photon marketplace add company/photons
photon add your-internal-tool

---

Built with singular focus. Deployed with precise targeting.

Made with ⚛️ by Portel