Skip to content

PLUGIN.md

Latest commit

 

History

History
261 lines (181 loc) · 7.55 KB

PLUGIN.md

File metadata and controls

261 lines (181 loc) · 7.55 KB
Raw

Photons Claude Code Plugin

Official Claude Code marketplace plugin for Photon MCP servers - singular focus, precise target.

Note: The .claude-plugin/ directory is auto-generated by photon sync marketplace --claude-code. Do not manually edit files in this directory - they will be overwritten on the next sync.

What is This?

This plugin makes all 17 Photon MCP servers instantly available in Claude Code. Each photon is a focused, single-purpose MCP server for specific tasks like file operations, databases, cloud services, and integrations.

Installation

Add the photons marketplace to Claude Code:

/plugin marketplace add portel-dev/photons

Install the photons plugin:

/plugin install photons@photons-marketplace

That's it! The plugin will automatically:

  • ✅ Check if Photon CLI is installed
  • ✅ Install it automatically if missing
  • ✅ Make all 17 photons available as MCP servers

No manual setup required for the Photon CLI!

Available Photons

Core Utilities

  • photon-filesystem - File and directory operations
  • photon-git - Local git repository operations
  • photon-fetch - Web content fetching and markdown conversion
  • photon-time - Timezone and time conversion operations
  • photon-memory - Knowledge graph-based persistent memory
  • photon-math - Advanced math expression evaluator

Databases

  • photon-postgres - PostgreSQL database operations
  • photon-mongodb - NoSQL database operations
  • photon-redis - In-memory data store and cache
  • photon-sqlite - SQLite database operations

Cloud & Infrastructure

  • photon-aws-s3 - AWS S3 cloud object storage operations
  • photon-docker - Container management operations

Integrations

  • photon-github-issues - Manage GitHub repository issues
  • photon-jira - Project management and issue tracking
  • photon-slack - Send messages and manage Slack workspace
  • photon-email - Send and receive emails via SMTP and IMAP
  • photon-google-calendar - Calendar integration

Configuration

Many photons require credentials or configuration (like database passwords, API tokens, etc.).

Interactive Setup (Recommended)

Run the interactive setup script to configure any photon:

bash .claude-plugin/scripts/setup-photon.sh

This script will:

  1. Show you which photons need configuration
  2. Guide you through entering credentials interactively
  3. Securely save them to your Claude Code MCP config
  4. Never share your credentials with the AI

Manual Configuration

If you prefer to configure manually, set environment variables or edit the MCP config directly:

Filesystem (photon-filesystem)

export FILESYSTEM_WORKDIR="$HOME/Documents"  # Optional, default: ~/Documents
export FILESYSTEM_MAXFILESIZE="10485760"     # Optional, default: 10MB
export FILESYSTEM_ALLOWHIDDEN="false"        # Optional, default: false

Git (photon-git)

export GIT_WORKDIR="/path/to/repo"  # Optional, current directory by default

GitHub Issues (photon-github-issues)

export GITHUB_ISSUES_TOKEN="ghp_..."      # Required: GitHub personal access token
export GITHUB_ISSUES_OWNER="username"     # Required: Repository owner
export GITHUB_ISSUES_REPO="repository"    # Required: Repository name

Jira (photon-jira)

export JIRA_HOST="https://yourcompany.atlassian.net"  # Required
export JIRA_EMAIL="your@email.com"                     # Required
export JIRA_TOKEN="your-api-token"                     # Required

Slack (photon-slack)

export SLACK_TOKEN="xoxb-..."  # Required: Slack bot token

Email (photon-email)

export EMAIL_SMTP_HOST="smtp.gmail.com"      # Required
export EMAIL_SMTP_PORT="587"                  # Required
export EMAIL_SMTP_USER="your@email.com"      # Required
export EMAIL_SMTP_PASSWORD="your-password"   # Required
export EMAIL_IMAP_HOST="imap.gmail.com"      # Required
export EMAIL_IMAP_PORT="993"                  # Required
export EMAIL_IMAP_USER="your@email.com"      # Required
export EMAIL_IMAP_PASSWORD="your-password"   # Required
export EMAIL_FROM="your@email.com"           # Required

Google Calendar (photon-google-calendar)

export GOOGLE_CALENDAR_CREDENTIALS="/path/to/credentials.json"  # Required
export GOOGLE_CALENDAR_TOKEN="/path/to/token.json"              # Required

PostgreSQL (photon-postgres)

export POSTGRE_S_Q_L_DATABASE="mydb"       # Required
export POSTGRE_S_Q_L_USER="username"       # Required
export POSTGRE_S_Q_L_PASSWORD="password"   # Required
export POSTGRE_S_Q_L_HOST="localhost"      # Optional, default: localhost
export POSTGRE_S_Q_L_PORT="5432"           # Optional, default: 5432
export POSTGRE_S_Q_L_SSL="false"           # Optional, default: false

MongoDB (photon-mongodb)

export MONGO_D_B_URI="mongodb://localhost:27017"  # Required
export MONGO_D_B_DATABASE="mydb"                  # Required

Redis (photon-redis)

export REDIS_HOST="localhost"     # Optional, default: localhost
export REDIS_PORT="6379"          # Optional, default: 6379
export REDIS_PASSWORD="password"  # Optional
export REDIS_DATABASE="0"         # Optional, default: 0

SQLite (photon-sqlite)

No environment variables required. Database path is specified in tool calls.

Docker (photon-docker)

export DOCKER_SOCKET_PATH="/var/run/docker.sock"  # Optional

AWS S3 (photon-aws-s3)

export AWS_S3_ACCESS_KEY_ID="AKIA..."           # Required
export AWS_S3_SECRET_ACCESS_KEY="..."           # Required
export AWS_S3_REGION="us-east-1"                # Optional, default: us-east-1

Fetch (photon-fetch)

No environment variables required.

Time (photon-time)

No environment variables required.

Memory (photon-memory)

export MEMORY_STORAGE_PATH="/path/to/storage"  # Optional

Math (photon-math)

No environment variables required.

Quick Start

  1. Install the plugin:

    /plugin marketplace add portel-dev/photons
/plugin install photons@photons-marketplace

  2. Configure photons that need credentials:

    bash .claude-plugin/scripts/setup-photon.sh

  3. Restart Claude Code to load the configured photons

  4. Start using photons! Claude will automatically use them when needed.

Usage Examples

Once installed and configured, Claude Code will automatically use the appropriate photons when needed. For example:

  • "List all files in my Documents folder" → Uses photon-filesystem
  • "Query the users table from the database" → Uses photon-postgres or photon-mongodb
  • "Create a new GitHub issue" → Uses photon-github-issues
  • "Upload file to S3 bucket" → Uses photon-aws-s3
  • "What time is it in Tokyo?" → Uses photon-time

Troubleshooting

Photon CLI Not Found

The plugin should automatically install the Photon CLI on first use. If you encounter issues:

npm install -g @portel/photon

Environment Variables Not Set

If a photon fails with "required parameter" errors, check that you've set the necessary environment variables for that specific photon (see Configuration section above).

Checking Available MCP Servers

To verify the photons are installed:

/mcp

You should see all photon-* servers listed.

Learn More

License

MIT