Skip to content

README.md

Latest commit

 

History

History
294 lines (223 loc) · 10.5 KB

README.md

File metadata and controls

294 lines (223 loc) · 10.5 KB

photons

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

🏛️ Official Marketplace

This is the official Photon marketplace maintained by Portel. It comes pre-configured with Photon - no manual setup needed.

Already available to you:

  • ✅ Pre-installed with Photon
  • ✅ Automatically updated
  • ✅ Production-ready photons
  • ✅ Community-maintained

Want to contribute? We welcome contributions! Submit pull requests for:

  • 🐛 Bug fixes to existing photons
  • ✨ Enhancements and new features
  • 📦 New photons to add to the marketplace
  • 📝 Documentation improvements

Repository: github.com/portel-dev/photons

📦 Available Photons

Photon Focus Tools Features
AWS S3 Cloud object storage 11 -
Boards Modern Kanban Boards Photon Task management for humans and AI. Use named instances (_use('project-name')) for per-project boards. Perfect for project planning, AI working memory across sessions, and human-AI collaboration on shared tasks. 19 ⚡🎨📡
Code Diagram Mermaid visualization from source code 3 🔌📦
Daemon Features Scheduled Jobs, Webhooks, Locks, Pub/Sub 4 📡
Demo Feature showcase Comprehensive demonstration of Photon runtime features: return types, parameters, progress indicators, user input (elicitation), state management, and UI formats. 14 ⚡
Deploy Pipeline Multi-step workflow with checkpoints and approval gates 3 ⚡📡
Docker Container management 10 -
Expenses Expenses — Track spending with budgets and summaries 4 -
Feature Showcase Core Runtime Feature Demos Demonstrates every major Photon runtime feature with test methods to prove each one works. Run photon test feature-showcase to verify. 10 ⚡📡
Filesystem File and directory operations 12 -
Format Showcase Auto-UI Format Demos Demonstrates every auto-UI format type with sample data so developers can see how each visualization looks and choose appropriately. Run any method in Beam to see the visual output. 28 📡
Git Local git repository operations 11 -
GitHub Issues Manage repository issues 7 -
Hello World The simplest possible photon A photon is just a TypeScript class where each method becomes an MCP tool. 3 -
Input Showcase Input Showcase 6 -
Jira Issue tracking and project management 10 -
List List — Simple reactive list for testing state sync A minimal task list using @stateful with constructor-injected state. Perfect for testing end-to-end synchronization across clients. 3 -
Calculator Math expression evaluator Evaluate math expressions with functions like sqrt, sin, cos, mean, median, etc. 1 -
MongoDB Flexible document-oriented database 14 -
PostgreSQL Powerful relational database 7 -
Progressive Rendering Same Data, Better Display Six methods return the same team data, each progressively enhanced. 6 -
Redis High-performance in-memory data store 18 -
Truth Serum Forces unfiltered honesty, no hedging or diplomacy 10 -
Slack Send and manage messages 7 -
SQLite File or in-memory SQL database 9 -
Tags Test fixture: MCP Spec Tags Exercises ALL MCP standard annotations, content annotations, structured output, and icon image features. Used by tests/mcp-spec-tags.test.ts in the photon runtime. 12 -
Tasks Basic Tasks Basic — Stateless task list A simple todo list that works during a session but loses state on restart. Compare with tasks-live to see what persistence adds. 4 -
Tasks Live Tasks Live — Persistent reactive task list Same as tasks-basic but tasks survive restarts and UI updates in real-time. Uses this.memory for zero-boilerplate persistence. 4 -
Team Pulse Team Pulse — Async standup with team feed 4 -
Test Formats Test format-based input validation 5 -
Time Timezone and time conversion Timezone-aware time operations using native Node.js Intl API (zero dependencies). 3 -
Todo List Reactive collections in action A beautifully simple task manager showing Photon's reactive arrays. Just manipulate items like a normal array (push, splice, map) and the runtime automatically persists to disk and emits events so connected UIs update in real-time. No async boilerplate needed. Use @priority to filter by importance, @done to filter by status. 8 -
Weather Current weather and forecasts Zero-dependency weather API wrapper using Open-Meteo (free, no key required). 2 -
Web Search and read webpages 2 -

Total: 34 photons ready to use

🚀 Quick Start

1. Install Photon

bun add -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 34 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
  • 📦 34 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