Metadata-Version: 2.4
Name: ps-bridge
Version: 1.0.0
Summary: AI Agent to Adobe Photoshop bridge
Author: PS Bridge Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/ps-bridge/ps-bridge
Project-URL: Issues, https://github.com/ps-bridge/ps-bridge/issues
Keywords: photoshop,ai,agent,mcp,image-editing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Provides-Extra: win
Requires-Dist: pywin32>=306; extra == "win"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Provides-Extra: all
Requires-Dist: pywin32>=306; extra == "all"
Dynamic: license-file

﻿[![简体中文](https://img.shields.io/badge/简体中文-zh--CN-blue)](README.zh-CN.md) · [![English](https://img.shields.io/badge/English-en-green)](README.md) · [![繁體中文](https://img.shields.io/badge/繁體中文-zh--TW-orange)](README.zh-TW.md)

# 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

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

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

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

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

#### Test MCP Directly

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

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

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

```python
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)

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

---

## 🧪 Tests

```bash
cd outputs
python -m pytest tests/ -v
```

---

## 📜 License

MIT.
