Transparent PNG

MCP server que substitueix un color per transparència (canal alpha) en arxius PNG.

Instal·lació

Requereix uv i Python 3.13+.

git clone <repo-url>
cd mcp-transparent-png
uv sync

Execució

MCP Inspector (desenvolupament)

uv run mcp dev main.py

Obre l'Inspector a http://localhost:5173 per provar les eines interactivament.

Claude Code

claude mcp add transparent-png -- uv run --directory /path/to/mcp-transparent-png python main.py

Claude Desktop

Afegeix al fitxer de configuració de Claude Desktop (~/.claude/claude_desktop_config.json en macOS, %APPDATA%/Claude/claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "transparent-png": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-transparent-png", "python", "main.py"]
    }
  }
}

Eines

make_transparent

Substitueix un color per transparència en un o més arxius PNG. Els arxius es modifiquen in-place.

Paràmetres:

Paràmetre	Tipus	Per defecte	Descripció
file_paths	list[str]	(requerit)	Rutes als arxius PNG
color	str	#00FF00	Color a substituir, format #RRGGBB
tolerance	int	30	Tolerància per canal RGB (0-255). 0 = coincidència exacta
match_mode	str	auto	auto activa chroma key si el color objectiu és verd, rgb força coincidència canal a canal i greenscreen força to/saturació/dominància del verd
hue_tolerance	int	35	Distància màxima de to en graus quan match_mode=greenscreen
min_saturation	float	0.15	Saturació mínima quan match_mode=greenscreen
green_dominance	int	20	Quant ha de sobresortir el verd respecte a vermell i blau

Exemple (verd amb mode automàtic per defecte):

{
  "file_paths": ["/path/to/image.png"],
  "color": "#00FF00",
  "tolerance": 30
}

Exemple recomanat per chroma verd irregular:

{
  "file_paths": ["/path/to/image.png"],
  "color": "#00FF00",
  "match_mode": "greenscreen",
  "hue_tolerance": 35,
  "min_saturation": 0.15,
  "green_dominance": 20
}

Exemple (blau exacte, sense tolerància):

{
  "file_paths": ["/path/to/a.png", "/path/to/b.png"],
  "color": "#0000FF",
  "tolerance": 0
}

make_transparent_from_sample

Extreu el color d'un píxel concret d'una imatge mostral i el fa transparent als arxius indicats.

Paràmetres:

Paràmetre	Tipus	Per defecte	Descripció
file_paths	list[str]	(requerit)	Rutes als arxius PNG a processar
sample_file	str	(requerit)	Arxiu PNG d'on extreure el color
x	int	(requerit)	Coordenada X del píxel mostral
y	int	(requerit)	Coordenada Y del píxel mostral
tolerance	int	30	Tolerància per canal RGB (0-255)
match_mode	str	auto	auto activa chroma key si el color mostrat és verd, rgb força coincidència canal a canal i greenscreen força to/saturació/dominància del verd
hue_tolerance	int	35	Distància màxima de to en graus quan match_mode=greenscreen
min_saturation	float	0.15	Saturació mínima quan match_mode=greenscreen
green_dominance	int	20	Quant ha de sobresortir el verd respecte a vermell i blau

Exemple:

{
  "file_paths": ["/path/to/photo.png"],
  "sample_file": "/path/to/photo.png",
  "x": 0,
  "y": 0,
  "match_mode": "greenscreen",
  "hue_tolerance": 25,
  "min_saturation": 0.2,
  "green_dominance": 18
}

Proves manuals

Crear imatges de test

uv run python -c "
from PIL import Image

# Imatge amb fons verd i quadrat vermell al centre
img = Image.new('RGBA', (200, 200), (0, 255, 0, 255))
for x in range(80, 120):
    for y in range(80, 120):
        img.putpixel((x, y), (255, 0, 0, 255))
img.save('/tmp/test_green.png')

# Imatge amb fons blau
img2 = Image.new('RGBA', (100, 100), (0, 0, 255, 255))
img2.save('/tmp/test_blue.png')

print('Imatges creades: /tmp/test_green.png, /tmp/test_blue.png')
"

Provar make_transparent

uv run python -c "
import json
from main import make_transparent

result = make_transparent(
  ['/tmp/test_green.png'],
  color='#00FF00',
  match_mode='greenscreen',
  hue_tolerance=35,
  min_saturation=0.15,
  green_dominance=20,
)
print(json.dumps(result, indent=2))
"

Sortida esperada:

{
  "color": "#00FF00",
  "tolerance": 30,
  "match_mode": "greenscreen",
  "hue_tolerance": 35,
  "min_saturation": 0.15,
  "green_dominance": 20,
  "files": [
    {
      "filename": "test_green.png",
      "pixels_changed": 39200,
      "total_pixels": 40000,
      "status": "ok"
    }
  ]
}

Provar make_transparent_from_sample

uv run python -c "
import json
from main import make_transparent_from_sample

# Recrear la imatge primer
from PIL import Image
img = Image.new('RGBA', (200, 200), (0, 255, 0, 255))
for x in range(80, 120):
    for y in range(80, 120):
        img.putpixel((x, y), (255, 0, 0, 255))
img.save('/tmp/test_sample.png')
img.save('/tmp/test_target.png')

result = make_transparent_from_sample(
    file_paths=['/tmp/test_target.png'],
    sample_file='/tmp/test_sample.png',
  x=0,
  y=0,
  match_mode='greenscreen',
  hue_tolerance=25,
  min_saturation=0.2,
  green_dominance=18,
)
print(json.dumps(result, indent=2))
"

Sortida esperada:

{
  "sampled_color": "#00FF00",
  "sample_coordinates": { "x": 0, "y": 0 },
  "tolerance": 30,
  "match_mode": "greenscreen",
  "hue_tolerance": 25,
  "min_saturation": 0.2,
  "green_dominance": 18,
  "files": [
    {
      "filename": "test_target.png",
      "pixels_changed": 39200,
      "total_pixels": 40000,
      "status": "ok"
    }
  ]
}

Verificar els píxels

uv run python -c "
from PIL import Image
img = Image.open('/tmp/test_green.png')
print('Pixel verd (0,0):', img.getpixel((0, 0)))   # alpha = 0 (transparent)
print('Pixel vermell (90,90):', img.getpixel((90, 90)))  # alpha = 255 (opac)
"

Provar amb MCP Inspector

uv run mcp dev main.py

A l'Inspector, prova les eines amb aquests paràmetres:

1. make_transparent: file_paths=["/tmp/test_green.png"], color="#00FF00", match_mode="auto", tolerance=30
2. make_transparent_from_sample: file_paths=["/tmp/test_target.png"], sample_file="/tmp/test_sample.png", x=0, y=0, match_mode="auto", tolerance=10

Sistema recomanat per al verd

Per a fons tipus chroma, el sistema recomanat és usar match_mode="auto" com a default, o match_mode="greenscreen" si vols forçar explícitament el classificador de chroma.

Quan s'activa la via de chroma, el sistema no compara només la distància RGB. Fa tres comprovacions:

1. El to del píxel ha d'estar prou a prop del to objectiu (hue_tolerance).
2. El píxel ha de tenir prou saturació (min_saturation) perquè grisos, blancs o ombres no entrin per error.
3. El canal verd ha de dominar clarament respecte a vermell i blau (green_dominance).

És millor que una tolerància RGB molt alta perquè permet capturar verds clars, foscos o lleugerament desplaçats sense començar a menjar grocs, grisos o zones de pell.

Modes de coincidència

rgb

Manté el comportament original. Un píxel es fa transparent si tots tres canals estan dins la tolerància del color objectiu:

|pixel.R - target.R| <= tolerance
|pixel.G - target.G| <= tolerance
|pixel.B - target.B| <= tolerance

greenscreen

Pensat específicament per a fons verds irregulars. Fa servir el to del color, la saturació i la dominància del canal verd.

auto

És el mode per defecte. Si el color objectiu és prou verd, activa el classificador greenscreen; si no, fa servir rgb. Això evita haver de recordar canviar de mode en el cas habitual del chroma verd i manté el comportament clàssic per a colors no verds.

Paràmetre	Efecte
hue_tolerance	Amplia o tanca el rang de tons verds admesos
min_saturation	Evita capturar píxels desaturats o grisos
green_dominance	Exigeix que el verd sobresurti davant del vermell i el blau

Configuració inicial recomanada:

Escenari	Configuració
Chroma ben il·luminat	hue_tolerance=25, min_saturation=0.2, green_dominance=20
Chroma amb ombres suaus	hue_tolerance=35, min_saturation=0.15, green_dominance=18
Fons molt desigual	hue_tolerance=45, min_saturation=0.1, green_dominance=12

Llicència

MIT