🌌 FP-Background_Obliterator

An elite, state-of-the-art, and blazing-fast background removal, element isolation, and layer composition environment. Running entirely locally on your machine for maximum privacy, it combines advanced neural-network-based background removal (InSPyReNet) with OpenCV image processing.

It is designed to operate in two modes:

1. Interactive Desktop GUI: A rich PyQt6 desktop application featuring full layer management, opacity controls, rectangular selections, clipboard integrations (Cmd+C/Cmd+V), and real-time mask refinement sliders (Threshold, Edge Erosion/Dilation, Edge Blur).
2. Headless Model Context Protocol (MCP) Server: A high-performance, robust stdio-based server allowing external AI agents (like Claude Desktop, Cursor, Windsurf, or custom developer agents) to directly invoke local background removal, masking, image editing, and layer rendering capabilities.

---

🚀 Core Features

🧠 Advanced AI-Powered Masking

• InSPyReNet Core: Incorporates the Intelligent Search and Parse Network, achieving professional-grade background cutouts in seconds.
• Edge Refinement Sliders: Real-time non-destructive controls including:
  • Threshold: Hard transparency cutoff (0-255).
  • Shift Edge: Erode (shrink) or Dilate (grow) the mask borders (-20 to +20 pixels).
  • Blur Edge: Soften cutout borders with adjustable Gaussian blur radius (0-20) for incredibly natural compositions.

🎨 Layer & Composition Management

• Hierarchical Layer System: Stack, reorder, group (folders), toggle visibility, and adjust individual opacities.
• Selection & Clipboard Integration: Select rectangular regions, deep copy, and paste-in-place or merge directly into selected layers.
• Multi-Format Support: Reads JPG, PNG, WEBP; exports to transparent PNG or white/colored background JPG.

🌐 High-Performance Headless MCP Server

• Standard stdio transport implementation using Python's FastMCP framework.
• Secure local execution; no data ever leaves your machine.

---

💻 Hardware & GPU Acceleration

FP-Background_Obliterator is optimized for cross-platform hardware acceleration:

• Apple Silicon macOS (M1/M2/M3): Automatically utilizes Apple Metal Performance Shaders (MPS) via mps:0 for super-fast neural execution.
• Windows & Linux (NVIDIA): Automatically binds to CUDA GPU acceleration if an NVIDIA GPU and compatible PyTorch runtime are present.
• CPU Fallback: Gracefully falls back to high-performance CPU processing if no compatible GPU is detected.

---

🛠️ Automated Setup & Launch

We provide cross-platform automated scripts that will set up an isolated virtual environment (venv), install all pip requirements, and launch the application.

🍎 macOS & 🐧 Linux

Launch Headless MCP Server (Headless/Agents)

Ensure you are in the project folder and run:

./launch_headless.sh

This script automatically checks for Python 3, creates venv if missing, installs dependencies, and boots the stdio MCP server.

Launch Interactive GUI (PyQt6 Desktop)

To open the graphical interface:

./launch_ui.sh

---

🪟 Windows

We provide native Command Prompt scripts (.bat) for Windows environments.

Launch Headless MCP Server (Headless/Agents)

Double-click launch_headless.bat or run in CMD:

launch_headless.bat

Launch Interactive GUI (PyQt6 Desktop)

Double-click launch_ui.bat or run in CMD:

launch_ui.bat

---

🤖 Headless MCP Server Integration Guide

By connecting this local MCP server, you give your developer AI agents (e.g., Claude, Cursor, Windsurf) direct superpowers to manipulate images in your workspace.

1. Integration with Claude Desktop

Add the following configuration block under mcpServers in your Claude Desktop configuration file:

• macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows Path: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "FP-Background_Obliterator": {
      "command": "/Volumes/Test1/Works/FP-Background_Obliterator/launch_headless.sh"
    }
  }
}

(On Windows, replace command path with "C:\\path\\to\\FP-Background_Obliterator\\launch_headless.bat").

---

2. Integration with Cursor IDE

1. Open Cursor settings (Cmd+, or Ctrl+,).
2. Navigate to Features -> MCP.
3. Click + Add New MCP Server.
4. Set the fields:
   • Name: FP-Background_Obliterator
   • Type: command
   • Command: /Volumes/Test1/Works/FP-Background_Obliterator/launch_headless.sh (or the Windows absolute bat path)
5. Click Save and click Refresh on the server status.

---

3. Integration with Windsurf IDE

Add the configuration to your user-level or workspace-level mcp_config.json file:

{
  "mcpServers": {
    "FP-Background_Obliterator": {
      "command": "/Volumes/Test1/Works/FP-Background_Obliterator/launch_headless.sh"
    }
  }
}

---

📊 Exposed MCP Agent Tools

When an agent connects to the server, the following five powerful tools are dynamically injected into its cognitive space:

1. remove_background

Remove the background of an image and save it as a transparent PNG.

• Arguments:
  • input_path (string, required): Absolute path to the source image.
  • output_path (string, optional): Absolute path to save the cutout. Defaults to <input_name>_no_bg.png in the source directory.
  • mode (string, optional): Speed/quality core. 'fast' (recommended) or 'base' (ultra precision).
  • threshold (integer, optional): Cutoff threshold (0-255). Default is 128.
  • shift (integer, optional): Erode (negative) or Dilate (positive) mask boundaries in pixels (-20 to +20). Default is 0.
  • blur (integer, optional): Soften mask edge radius (0-20). Default is 0.

2. get_mask

Generate and save the raw grayscale alpha mask (transparency map) for a local image.

• Arguments:
  • input_path (string, required): Absolute path to the source image.
  • output_path (string, optional): Absolute path to save the grayscale mask PNG.
  • mode (string, optional): 'fast' or 'base'.

3. apply_mask

Apply a grayscale mask image to an RGB image to create a transparent PNG, with optional edge refinement.

• Arguments:
  • input_path (string, required): Absolute path to source RGB image.
  • mask_path (string, required): Absolute path to grayscale mask.
  • output_path (string, required): Absolute path to save output transparent PNG.
  • threshold / shift / blur (optional): Same refinement controls as above.

4. edit_image

Perform basic image adjustments (brightness, contrast, resizing, rotating, and cropping) in one call.

• Arguments:
  • input_path (string, required): Source path.
  • output_path (string, required): Destination path.
  • brightness (number, optional): Brightness multiplier (e.g. 1.2 for brightening).
  • contrast (number, optional): Contrast multiplier.
  • width (integer, optional): Target resize width (maintains aspect ratio if height omitted).
  • height (integer, optional): Target resize height.
  • rotate_angle (number, optional): Counter-clockwise rotation angle.
  • crop_box (array of 4 integers, optional): Crop boundaries [left, top, right, bottom].

5. composite_layers

Composite multiple image layers together on a single canvas, supporting transparency, custom position coordinates, and layer opacity.

• Arguments:
  • output_path (string, required): Path to save the composite PNG.
  • canvas_width (integer, required): Target width.
  • canvas_height (integer, required): Target height.
  • layers (array of objects, required): Ordered list from top to bottom (first element is top-most layer). Each object:
    • image_path (string, required): Absolute path to the layer image.
    • position (array of 2 integers, optional): [x, y] coordinates. Default is [0, 0].
    • opacity (number, optional): Opacity from 0.0 to 1.0. Default is 1.0.
    • visible (boolean, optional): Default true.
  • background_color (array of 4 integers, optional): Canvas fill [R, G, B, A]. Default is [0, 0, 0, 0] (transparent).

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details. All model weights downloaded by InSPyReNet are subject to their respective creators' licensing terms.