npm package: @onesitatech/photoshop-fabric-mcp-server
Description: Professional MCP Server for Adobe Photoshop 2025+ with hyper-realistic fabric physics, advanced lighting, and 50+ professional transformation tools
Author: Onesita
Latest version: 2.0.0

# @onesitatech/photoshop-fabric-mcp-server

[![npm version](https://badge.fury.io/js/@onesitatech%2Fphotoshop-fabric-mcp-server.svg)](https://badge.fury.io/js/@onesitatech%2Fphotoshop-fabric-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**🚀 Version 2.0.0 - Complete Architecture Overhaul**

A professional-grade MCP (Model Context Protocol) server that provides Claude with direct control over Adobe Photoshop 2025+ for hyper-realistic fabric transformations, advanced physics simulation, and professional garment modifications.

## 🏗️ **Correct MCP Architecture (v2.0.0)**

```
Claude Desktop ↔ MCP Server (STDIO) ↔ File System ↔ UXP Plugin ↔ Photoshop 2025
```

✅ **Direct STDIO Communication** - Follows official MCP standards  
✅ **No Network Dependencies** - File-based UXP communication  
✅ **Zero HTTP Proxies** - Simplified, standards-compliant approach

## 🎯 **Version 2.0.0 Features**

### 🧬 **Hyper-Realistic Fabric Physics**
- **Advanced Physics Simulation**: 7 fabric types with material properties
  - Silk (elasticity: 0.9, flexibility: 0.95)
  - Cotton (elasticity: 0.6, flexibility: 0.7)  
  - Denim, Leather, Wool, Linen, Synthetic
- **Wind & Gravity Effects**: Realistic environmental simulation
- **Material-Specific Deformation**: Fabric behavior based on physical properties

### 💡 **Professional Lighting System**
- **5 Lighting Types**: Natural, Studio, Dramatic, Soft, Golden
- **Material-Based Light Interaction**: 
  - Silk: High reflectance (0.8), low roughness (0.1)
  - Cotton: Medium reflectance (0.4), higher roughness (0.6)
- **Advanced Effects**: Ambient occlusion, specular highlights, subsurface scattering

### 🎨 **Advanced Surface Systems**
- **Realistic Fiber Texturing**: Cotton, silk, wool, linen, denim, synthetic
- **Weave Pattern Engine**: Plain, twill, satin, herringbone, houndstooth, basket
- **Thread Count Control**: 50-500 threads per inch precision
- **Surface Aging**: Material wear and aging effects

### 🔬 **Professional Deformation Tools**
- **Liquify Fabric Deformation**: 5 fabric-specific modes
- **Wave Deformation**: Natural fabric flow and draping
- **Spherize Body Contours**: Realistic body curve mapping
- **Polar Coordinates**: Circular wrapping (sleeves, collars, cuffs)
- **Puppet Warp Enhanced**: Multi-pin professional deformation

### 🎯 **50+ Professional Tools**
- **Master Fabric Transformation**: Complete professional pipeline
- **Advanced Blending Modes**: Fabric-specific compositing
- **Luminosity Masking**: Precise tonal adjustments  
- **Smart Sharpening**: Fabric detail enhancement
- **Noise Reduction**: Texture-preserving cleanup

### 🔥 **Adobe Firefly Integration**
- **Generative Fill**: AI-powered content generation
- **Texture Matching**: Seamless fabric texture generation
- **Style Transfer**: Reference-based fabric adaptation

### 📊 **Quality & Performance**
- **4 Quality Levels**: Draft, High, Ultra, Professional
- **Multi-Iteration Processing**: 1-10 refinement passes
- **Batch Operations**: Multiple image processing
- **Real-time Monitoring**: UXP plugin status tracking

## 📦 **Installation (v2.0.0)**

### Prerequisites
- **Adobe Photoshop 2025** (26.0) or higher ⚠️ **REQUIRED**
- **UXP Developer Tool** for plugin loading
- **Node.js 18+** for MCP server
- **Windows/macOS/Linux** (file-based communication)

### Quick Start

```bash
# Install the MCP server
npm install -g @onesitatech/photoshop-fabric-mcp-server

# The server uses STDIO - no additional setup needed!
```

### Install from source

```bash
git clone https://github.com/sagarnabhoya/photoshop-mcp-server.git
cd photoshop-mcp-server
npm install
npm run build
```

## 🚀 Quick Start

### 1. Configure Adobe Photoshop
- Ensure Photoshop is installed in the default location
- Enable ExtendScript execution in Photoshop preferences
- Sign in to Adobe Creative Cloud for Firefly access

### 2. Configure Claude Desktop

Add to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "photoshop-fabric": {
      "command": "npx",
      "args": ["@onesitatech/photoshop-fabric-mcp-server"],
      "env": {
        "PHOTOSHOP_PATH": "C:/Program Files/Adobe/Adobe Photoshop 2025/Photoshop.exe"
      }
    }
  }
}
```

### 3. Start Using

```
Claude, I want to change the fabric of this shirt in my image. 
I have a model photo and want to apply a denim pattern.

1. Open my model image: "/path/to/model.jpg"
2. Load the denim patterns from my patterns folder
3. Apply hyper-realistic fabric transformation preserving all shadows and wrinkles
4. Export as high-quality PNG
```

## 🛠️ Available Tools

### Document Operations
- `create_document` - Create new Photoshop documents
- `open_document` - Open existing files (PSD, JPG, PNG, etc.)
- `save_document` - Save in multiple formats with quality options
- `get_document_info` - Get document properties and metadata

### Layer Management
- `create_layer` - Create layers with blend modes and opacity
- `duplicate_layer` - Duplicate existing layers
- `merge_layers` - Merge multiple layers intelligently
- `set_layer_visibility` - Show/hide layers
- `set_layer_blend_mode` - Change blend modes
- `set_layer_opacity` - Adjust layer transparency
- `list_layers` - Get all layer information
- `get_layer_info` - Detailed layer properties

### Selection Tools
- `make_selection` - All selection types (rectangular, elliptical, lasso, magic wand, color range)
- `modify_selection` - Expand, contract, feather, smooth selections
- `save_selection` - Save selections as alpha channels
- `load_selection` - Load saved selections

### Transformations
- `transform_layer` - Scale, rotate, skew, distort, perspective, flip
- `puppet_warp` - Advanced puppet warp with multiple pins and modes

### Fabric-Specific Tools
- `apply_fabric_pattern` - Apply patterns with realistic body mapping
- `extract_garment_lighting` - Extract lighting information from garments
- `create_displacement_map` - Generate displacement maps for 3D effects
- `hyper_realistic_fabric_swap` - Complete fabric transformation pipeline

### Advanced Fabric Tools
- `liquify_fabric_deformation` - Professional liquify deformation for fabric flow
- `wave_deformation_filter` - Natural fabric draping effects
- `fabric_fiber_texturing` - Add realistic fiber textures
- `fabric_weave_pattern` - Apply weave patterns (plain, twill, satin)
- `master_fabric_transformation` - Complete professional-grade pipeline

### Pattern Management
- `list_photoshop_patterns` - Show all patterns in Photoshop's built-in library
- `apply_photoshop_pattern` - Apply built-in Photoshop patterns to layers

### Batch Operations
- `batch_fabric_transformation` - Process multiple images automatically

## 📚 Usage Examples

### Basic Fabric Transformation

```javascript
await callTool('hyper_realistic_fabric_swap', {
  modelImage: '/path/to/model.jpg',
  newFabricPattern: 'denim_blue_001',
  preserveOriginalShading: true,
  preserveWrinkles: true,
  outputQuality: 'ultra',
  iterations: 5
});
```

### Advanced Pattern Application

```javascript
await callTool('apply_fabric_pattern', {
  modelLayerName: 'Model Layer',
  garmentSelection: 'Dress Selection',
  patternName: 'silk_floral_001',
  patternScale: 85,
  wrapIntensity: 70,
  blendMode: 'multiply'
});
```

### Batch Processing

```javascript
await callTool('batch_fabric_transformation', {
  inputDirectory: '/path/to/models/',
  outputDirectory: '/path/to/output/',
  fabricPattern: 'cotton_stripes_blue',
  settings: {
    preserveShading: true,
    outputFormat: 'PNG',
    quality: 'high'
  }
});
```

## 🎨 Supported Fabric Types

The system automatically categorizes fabric patterns:
- **Cotton**: Canvas, denim, chambray, poplin
- **Silk**: Satin, chiffon, crepe, dupioni  
- **Wool**: Tweed, herringbone, flannel, cashmere
- **Leather**: Smooth, textured, exotic skins
- **Synthetic**: Polyester, nylon, blends
- **Knits**: Jersey, ribbing, cable knit
- **Lace**: Floral, geometric, vintage patterns

## 🔧 Configuration

### Environment Variables

- `PHOTOSHOP_PATH` - Path to Photoshop executable
- `OUTPUT_QUALITY` - Default output quality (draft|high|ultra)
- `MAX_ITERATIONS` - Maximum refinement iterations

### Adding Patterns to Photoshop

1. **Open Photoshop**
2. **Go to Window > Patterns**
3. **Load pattern libraries** using the gear icon
4. **Patterns are now available** to the MCP server automatically

## 🐛 Troubleshooting

### Common Issues

1. **Photoshop Not Found**
   ```
   Error: Photoshop executable not found
   ```
   - Verify `PHOTOSHOP_PATH` in configuration
   - Ensure Photoshop 2024+ is installed

2. **ExtendScript Errors**
   ```
   Error: Script execution failed
   ```
   - Enable ExtendScript execution in Photoshop preferences
   - Check Windows/macOS security settings

3. **Pattern Not Found Issues**
   ```
   Error: Pattern 'fabric_001' not found
   ```
   - Use `list_photoshop_patterns` to see available patterns
   - Add patterns via Photoshop's Window > Patterns panel

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/sagarnabhoya/photoshop-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/sagarnabhoya/photoshop-mcp-server/discussions)
- **Documentation**: [Wiki](https://github.com/sagarnabhoya/photoshop-mcp-server/wiki)

## 🚀 Roadmap

- [ ] Support for more fabric types
- [ ] Real-time preview mode
- [ ] Integration with more design tools
- [ ] Cloud-based pattern library
- [ ] AI-powered fabric detection

---

**Note**: This MCP server requires Adobe Photoshop and Creative Cloud subscription. Firefly features require internet connection and may have usage limits based on your subscription tier.