ps-bridge 1.0.0

AI Agent to Adobe Photoshop bridge

· ·

PS Bridge — Universal AI Agent ↔ Adobe Photoshop Bridge

Let any AI agent drive Adobe Photoshop in real-time, batch-process photos, and automate creative workflows — without plugins or manual scripting.

PS Bridge is an open-source local bridge tool that runs a lightweight HTTP server on the workstation where Photoshop is installed. It provides MCP (Model Context Protocol), REST API, and Python CLI — three integration modes — so any AI agent (Claude, Codex, Cursor, etc.) can control Photoshop programmatically.

Supported AI Agents

• 🟣 Claude Desktop / Claude Code — native MCP support
• 🟢 Cursor / Windsurf — native MCP support
• 🔵 Codex CLI — REST API or MCP
• ⚪ Any HTTP client — raw REST API
• 🟡 Terminal / shell — Python CLI

---

✨ Capabilities

Category	Operations
Document I/O	open, close, save, flatten, duplicate
Adjustments	Curves, Levels, Brightness/Contrast, Hue/Saturation, Vibrance, Exposure, Shadows/Highlights, Color Balance, Photo Filter
Auto	Auto Levels, Auto Contrast, Auto Color
Filters	Unsharp Mask, Sharpen, Denoise, Gaussian Blur
Geometry	Resize, Crop, Smart Crop, Rotate
Other	Undo, Snapshot, Revert, Preview (base64), Diagnose (histogram/color cast/blur/noise)
Batch	Glob-pattern batch processing, recipe-based batch application
Presets	Portrait retouch, Product clean, Social square, Film emulation, HDR look, Quick fix

---

🧱 Architecture

┌────────────────────────────────────────────────┐
│ AI Agent (Claude / Codex / Cursor / ...)       │
│                                                │
│  ┌─ MCP (stdio)  ────── ps_* tools ──────┐    │
│  └─ REST API (HTTP) ── /api/tools ───────┘    │
│  └─ Python CLI ─────── ps-bridge cmd ────┘    │
└─────────────────────┬──────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────┐
│ Local Workstation (macOS / Windows)            │
│                                                │
│  bridge_server.py  ← Python HTTP Server        │
│       ↓  DoJavaScript / AppleScript            │
│  Adobe Photoshop                               │
│       ↓  ExtendScript                          │
│  ps_stdlib.jsx    ← 28 PS.* operations         │
└────────────────────────────────────────────────┘

Key Components

• bridge/ — HTTP server + platform backends (AppleScript / COM) + JSX runtime
• codex_ps/ — Python client library (usable from any Python environment)
• presets/ — YAML recipe definitions
• tests/ — 43 tests, no Photoshop required to run

---

🚀 Quick Start

1. Install & Start the Bridge

cd bridge

# Windows
.\install.ps1
.\run_bridge.ps1

# macOS
chmod +x install.sh run_bridge.sh
./install.sh
./run_bridge.sh

On success you'll see:

=== PS Bridge ===
Token      : KcORqqpGiC8_Kl-yHMrs9C9vweEFUq16
Listening  : http://127.0.0.1:8765
PS health  : {'ok': True, 'app': 'Adobe Photoshop 2025', ...}

2. Verify Connectivity

curl -s http://127.0.0.1:8765/health \
  -H "Authorization: Bearer $(python -c 'import json; print(json.load(open("bridge/bridge.token"))["token"])')"

---

🤖 AI Agent Integration

Mode 1: MCP (Recommended)

Any MCP-compatible agent can call Photoshop tools directly via stdio transport.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "photoshop": {
      "command": "python",
      "args": ["/path/to/bridge/mcp_server.py"]
    }
  }
}

Restart Claude Desktop. The agent will have access to these tools:

Tool	Function
ps_open	Open an image
ps_apply	Apply adjustment/filter
ps_preview	Get base64 preview
ps_presets	List built-in presets
ps_apply_preset	Apply a preset recipe
ps_batch	Batch process multiple images
ps_state	Get document state
ps_save	Save the document
ps_undo	Undo last operation
ps_flatten	Flatten layers
ps_resize	Resize image
ps_diagnose	Analyze image
ps_health	Check connection health
ps_close	Close the document

Cursor / Windsurf

{
  "mcpServers": {
    "photoshop": {
      "command": "python",
      "args": ["/path/to/bridge/mcp_server.py"]
    }
  }
}

Test MCP Directly

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python bridge/mcp_server.py
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ps_health","arguments":{}}}' | python bridge/mcp_server.py

Mode 2: REST API (Any HTTP Client)

TOKEN=$(python -c 'import json; print(json.load(open("bridge/bridge.token"))["token"])')
BASE="http://127.0.0.1:8765"
AUTH="Authorization: Bearer $TOKEN"

curl -s "$BASE/api/tools" -H "$AUTH" | python -m json.tool
curl -s "$BASE/health" -H "$AUTH" | python -m json.tool
curl -s -X POST "$BASE/open" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/me/photo.jpg"}' | python -m json.tool
curl -s -X POST "$BASE/apply" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"op": "vibrance", "params": {"vibrance": 20, "saturation": 5}}' | python -m json.tool
curl -s "$BASE/preview?size=800" -H "$AUTH" | python -m json.tool
curl -s -X POST "$BASE/batch" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"glob": "photos/*.jpg", "recipe": "quick-fix", "out_dir": "out/"}' | python -m json.tool

Mode 3: Python CLI (Any Terminal)

export PS_BRIDGE_URL=http://127.0.0.1:8765
export PS_BRIDGE_TOKEN=$(python -c 'import json; print(json.load(open("bridge/bridge.token"))["token"])')

python -m codex_ps health
python -m codex_ps presets
python -m codex_ps open photo.jpg
python -m codex_ps apply vibrance --vibrance 15
python -m codex_ps preview --size 600 --out preview.jpg
python -m codex_ps batch "photos/*.jpg" --recipe portrait-retouch --out out/
python -m codex_ps diagnose photo.jpg

Mode 4: Python SDK (Programmatic)

from codex_ps.client import BridgeClient, from_env

client = from_env()
# or: client = BridgeClient("http://127.0.0.1:8765", "your-token")

client.open("photo.jpg")
client.apply("vibrance", {"vibrance": 20, "saturation": 5})
preview = client.preview(size=800)
with open("preview.jpg", "wb") as f:
    f.write(preview)

---

🔧 Environment Variables

Variable (new)	Variable (legacy)	Purpose
PS_BRIDGE_URL	CODEX_PS_URL	Bridge server URL
PS_BRIDGE_TOKEN	CODEX_PS_TOKEN	Auth token

---

📁 Directory Structure

outputs/
├── bridge/           # HTTP server + platform backends
├── codex_ps/         # Python client library
├── presets/          # YAML recipe definitions
├── tests/            # 43 tests (no PS needed)
├── SMOKE_TEST.md     # Acceptance checklist
└── README.md         # This file

---

🔌 Cloudflare Tunnel (Remote Access)

cd bridge
./tunnel_cloudflare.sh   # macOS
.\tunnel_cloudflare.ps1  # Windows

---

🧪 Tests

cd outputs
python -m pytest tests/ -v

---

📜 License

MIT.