🎨 PhotoCop

The AI-Native Professional Image Editor & Programmable Graphics Engine

Built for precision human creativity and autonomous AI agent workflows via Model Context Protocol (MCP).

📑 Table of Contents

• Vision & Philosophy

• System Architecture

• Key Features

  • 1. Command-Driven State Pipeline

  • 2. Non-Destructive Layer System

  • 3. All 24 Photoshop Blend Modes

  • 4. Dual AI Operation (In-App + MCP)

  • 5. Precision Brush & Canvas Engine

• Model Context Protocol (MCP) Server

  • Connecting External Agents

  • MCP Tool Catalog

• Keyboard Shortcuts

• Quick Start

  • Prerequisites

  • Installation

  • Starting the Editor

  • Building for Production

• AI Panel Configuration

• Project Structure

• Roadmap

• Contributing

• License

Related MCP server: Photopea MCP Server

💡 Vision & Philosophy

Traditional creative suites (like Adobe Photoshop and GIMP) were architected for manual human cursor interaction. Meanwhile, modern generative AI tools operate as opaque, single-prompt black boxes lacking fine-grained spatial and non-destructive layer control.

PhotoCop bridges this divide. It is a full-fledged, GPU-accelerated graphic manipulation suite where:

1. Humans get a professional, tactile UI with layers, masks, curves, clone stamps, and familiar shortcuts.

2. AI Agents get a programmatic, deterministic API via the Model Context Protocol (MCP) and structured command streams.

3. Every action—whether initiated by a mouse drag, a hotkey, an in-app LLM, or an external agent over MCP—passes through the exact same typed command pipeline with complete undo/redo provenance.

🏗 System Architecture

                  ┌───────────────────────────────────────────────┐
                  │                INPUT SOURCES                  │
                  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │
                  │  │ Human UI │  │ AI Panel │  │  MCP Server  │ │
                  │  └────┬─────┘  └────┬─────┘  └──────┬───────┘ │
                  └───────┼─────────────┼───────────────┼─────────┘
                          │             │               │
                          ▼             ▼               ▼
                 ═════════════════════════════════════════════════
                       Unified Command Dispatcher: dispatch(cmd)
                 ═════════════════════════════════════════════════
                                        │
                      ┌─────────────────┴─────────────────┐
                      ▼                                   ▼
         ┌─────────────────────────┐         ┌─────────────────────────┐
         │     Document Store      │         │      History Stack      │
         │  • Layer Hierarchy      │         │  • 100-step Undo/Redo   │
         │  • Blend Modes & Masks  │         │  • Source Attribution   │
         │  • Viewport & Selection │         │    (User / AI / MCP)    │
         └────────────┬────────────┘         └─────────────────────────┘
                      │
                      ▼
         ┌─────────────────────────────────────────────────────────────┐
         │            High-Performance Canvas Compositor               │
         │  • Offscreen Canvas Buffers                                 │
         │  • 24 Blend Modes (per-pixel math + CSS compositing)        │
         │  • Transform matrices (Scale, Rotate, Translate)            │
         │  • Dirty-rect invalidation via RAF renderVersion            │
         └─────────────────────────────┬───────────────────────────────┘
                                       │
                                       ▼
                            [ Interactive Canvas View ]

✨ Key Features

1. Command-Driven State Pipeline

Every mutation in PhotoCop is expressed as an explicit, serializable EditorCommand:

• pixel.paint_stroke, pixel.flood_fill, pixel.clone_stamp

• layer.create, layer.delete, layer.reorder, layer.set_opacity, layer.set_blend_mode

• layer.add_mask, layer.invert_mask, layer.set_transform

• adjustment.create, adjustment.update_curves, adjustment.update_levels

• selection.set_rect, selection.clear, selection.invert

• view.set_zoom, view.set_pan, history.undo, history.redo

Because every command is structured JSON, autonomous agents can dry-run, batch, replay, and verify edits seamlessly.

2. Non-Destructive Layer System

• Layer Types: Pixel, Adjustment, Fill (Solid), Text, and Group layers.

• Layer Masks: 8-bit alpha masks per layer, with support for live inversion, feathering, and toggleable state.

• Transformations: Non-destructive 2D affine transforms (rotation, position offset, non-uniform scaling).

• Adjustment Layers: Full live adjustment stack including RGB Curves (with cubic spline / bezier points), Levels, Brightness/Contrast, Hue/Saturation, and Invert.

3. All 24 Photoshop Blend Modes

Full mathematical parity with industry-standard digital compositing:

4. Dual AI Operation (In-App + MCP)

• Built-in AI Assistant Panel: Connect directly to OpenAI (GPT-4o), Anthropic (Claude 3.5 Sonnet), local Ollama (Llama 3 / Mistral), or any OpenAI-compatible API. The panel feeds current document metadata, visual downsampled previews, and tool catalogs to the model, which outputs executable command blocks.

• Native MCP Server: PhotoCop exposes its internals over the Model Context Protocol, turning the editor into an accessible toolset for external agentic environments.

5. Precision Brush & Canvas Engine

• Customizable Brush Dynamics: Hardness, spacing, flow, opacity, and brush radius.

• Tooling: Paintbrush, Pencil, Eraser, Clone Stamp, Paint Bucket (Flood Fill), Marquee Selection, Crop Overlay, Pan/Hand, and Zoom.

• Infinite Canvas Navigation: Smooth panning, zooming centered on the mouse cursor, and marching-ants selection marquee.

🔌 Model Context Protocol (MCP) Server

PhotoCop includes an embedded Model Context Protocol (MCP) server (src/mcp/server.ts) exposing over 30 programmatic tools and live document resources.

Connecting External Agents

Add PhotoCop to your agent client configuration (e.g. Claude Desktop, Cursor, Antigravity):

{
  "mcpServers": {
    "photocop": {
      "command": "node",
      "args": ["path/to/PhotoCop/photocop/dist/mcp-server.js"]
    }
  }
}

MCP Tool Catalog

⌨️ Keyboard Shortcuts

PhotoCop adopts standard industry keybindings for zero learning curve:

🚀 Quick Start

Prerequisites

• Node.js v18.0.0 or higher

• npm v9.0.0 or higher

Installation

Clone the repository:

git clone https://github.com/HunainxAhmed/PhotoCop.git
cd PhotoCop

Install dependencies:

cd photocop
npm install

Starting the Editor

Run the local Vite development server:

npm run dev

Open your browser and navigate to:

http://localhost:5173

You can also run commands directly from the workspace root:

npm run dev      # Starts Vite dev server
npm run build    # Compiles TypeScript and runs production bundle
npm run lint     # Runs oxlint analysis

Building for Production

Compile optimized production assets:

npm run build

Production assets are generated in photocop/dist/. To preview the production bundle locally:

npm run preview

🤖 AI Panel Configuration

1. In the PhotoCop interface, open the AI Assistant panel on the right sidebar.

2. Click the ⚙️ Settings button in the AI panel header.

3. Select your desired provider:

   • OpenAI: Set your API key (sk-...) and model (e.g., gpt-4o, gpt-4o-mini).

   • Anthropic: Set your Claude API key (sk-ant-...) and model (claude-3-5-sonnet-20241022).

   • Ollama (Local): Set the endpoint (default: http://localhost:11434) and model name (e.g., llama3).

   • Custom: Any OpenAI-compatible inference proxy or gateway.

4. Issue natural language requests such as:

   • "Boost the contrast of this portrait using a gentle S-curve adjustment."

   • "Create a solid dark vignette overlay with Multiply blend mode at 45% opacity."

   • "Isolate the bright highlights and invert the mask on layer 2."

The assistant analyzes the live layer graph and executes exact commands onto your canvas in real-time.

📁 Project Structure

PhotoCop/
├── assets/
│   └── hero.png                     # Application teaser and documentation assets
├── photocop/
│   ├── public/                      # Static assets and favicons
│   ├── src/
│   │   ├── assets/                  # UI artwork and icons
│   │   ├── components/              # Modular React UI components
│   │   │   ├── AIPanel.tsx          # Multi-provider AI assistant panel
│   │   │   ├── Canvas.tsx           # 2D Canvas renderer & event coordinator
│   │   │   ├── HistoryPanel.tsx     # Provenance-tracking undo/redo panel
│   │   │   ├── LayersPanel.tsx      # Layer stack, opacity, masks, thumbnails
│   │   │   ├── MenuBar.tsx          # Comprehensive application menus
│   │   │   ├── PerformanceMonitor.tsx # Real-time latency and FPS monitor
│   │   │   ├── PropertiesPanel.tsx  # Context-sensitive curve and brush sliders
│   │   │   ├── StatusBar.tsx        # Coordinates, tool state, zoom info
│   │   │   └── Toolbox.tsx          # Tool buttons and color swatches
│   │   ├── core/                    # Pure engine and graphics core
│   │   │   ├── blendModes.ts        # Blend mode definitions and constants
│   │   │   ├── brushEngine.ts       # Pixel stamping, spacing, flow math
│   │   │   ├── commandDispatcher.ts # Deterministic command execution engine
│   │   │   ├── commands.ts          # 40+ strongly-typed command interfaces
│   │   │   ├── compositor.ts        # Offscreen canvas compositor & math
│   │   │   ├── document.ts          # Layer/document constructors & mutators
│   │   │   └── types.ts             # Global type definitions
│   │   ├── mcp/                     # Model Context Protocol integration
│   │   │   └── server.ts            # 30+ MCP tools and live resources
│   │   ├── store/                   # Reactive state management
│   │   │   └── editorStore.ts       # Zustand store with command middleware
│   │   ├── App.tsx                  # Main workspace layout & shortcuts
│   │   ├── index.css                # Tailwind CSS stylesheets
│   │   └── main.tsx                 # React entry point
│   ├── index.html                   # HTML template
│   ├── package.json                 # Dependencies and build scripts
│   ├── tsconfig.json                # TypeScript compiler configuration
│   └── vite.config.ts               # Vite bundler configuration
├── .gitignore                       # Git ignore patterns
├── LICENSE                          # MIT License
├── package.json                     # Workspace root script runner
└── README.md                        # Documentation

🗺 Roadmap

Phase 1: Core Foundation ✅

• Full layer model (pixel, adjustment, text, group, fill)

• All 24 Photoshop blend modes with per-pixel math

• 40+ typed command definitions & single dispatcher

• High-performance brush engine (hardness, flow, spacing, eraser, clone stamp)

• 100-step undo/redo history with source attribution (Human / AI / MCP)

• GPU-accelerated canvas with smooth zoom-to-cursor and pan

• In-app AI Assistant panel (OpenAI, Anthropic, Ollama)

• Complete Model Context Protocol (MCP) server with 30+ tools

• Photoshop-standard keyboard shortcuts

Phase 2: Advanced Editing Tools 🚧

• Pressure-sensitive brush curves (Stylus & Apple Pencil / Wacom API)

• Magic Wand / Color Range selection engine

• Healing Brush & Patch tools

• Multi-stop Linear & Radial gradient fill tools

• Dodge, Burn, Sponge, Blur, and Sharpen brush tools

• Free Transform with bounding box handles and perspective warp

• Rich typography and path-following text engine

• Convolution filter pipeline (Gaussian Blur, Unsharp Mask, High Pass)

• WebSocket relay for bidirectional remote MCP clients

Phase 3: Enterprise & Pro Pipeline 🔮

• Vector Pen tool with cubic Bézier path math

• Smart Object non-destructive raster/vector containers

• Liquify and mesh warp engine

• PSD / TIFF import and export parser

• Vision-AI segmentation (one-click subject isolation, generative fill)

• Batch automation and script macro recorder

🤝 Contributing

Contributions are what make the open-source community an incredible place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'feat: Add AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

Crafted with care by Hunain Ahmed.

⭐ If you find PhotoCop inspiring or useful, please consider starring this repository!