sdnext-mcp

Servidor del Model Context Protocol (MCP) para SD.Next (Stable Diffusion Next) WebUI.

Envuelve la API REST de SD.Next (/sdapi/v1/* + /sdapi/v2/civitai/*) como 125 herramientas MCP para que un host LLM (Claude Desktop, DSH, etc.) pueda controlar todos los escenarios de uso de SD.Next: texto a imagen, imagen a imagen, generación guiada por control, escalado, detailer, LoRA, scripts, subtitulado/etiquetado/VQA, gestión de modelos y opciones, introspección del servidor, archivos/galería y CivitAI.

Esto es un cliente HTTP ligero. No incluye Python ni lanza el WebUI. Debes ejecutar SD.Next tú mismo con --api --listen; el servidor MCP solo se comunica con él a través de HTTP.

La razón principal de su existencia: los parámetros de solicitud de SD.Next difieren de A1111 (guía modular, lienzo predeterminado de 1024, detailer YOLO integrado, schedulers como eje separado, UNet/DiT, etc.), por lo que el código MCP de A1111 no funciona con él. Cada herramienta aquí está modelada según los campos de solicitud pydantic reales de SD.Next.

Requisitos

• Node.js ≥ 18 (usa fetch global, FormData, AbortSignal.timeout)

• Una instancia de SD.Next en ejecución iniciada con --api --listen (añade --api-auth user:pass para habilitar la autenticación)

Related MCP server: sd-neo-mcp

Instalación

cd sdnext_mcp
npm install          # installs @modelcontextprotocol/sdk + zod

Ejecución

El transporte predeterminado es stdio (iniciado por tu host MCP):

# in your MCP host config
{
  "mcpServers": {
    "sdnext": {
      "command": "node",
      "args": ["/abs/path/to/sdnext_mcp/src/index.js"],
      "env": {
        "SDNEXT_BASE_URL": "http://127.0.0.1:7860",
        "SDNEXT_USERNAME": "user",
        "SDNEXT_PASSWORD": "pass"
      }
    }
  }
}

O ejecuta el transporte HTTP Streamable directamente:

SDNEXT_MCP_TRANSPORT=http SDNEXT_MCP_PORT=8787 node src/index.js
# → http://127.0.0.1:8787/mcp

Configuración (variables de entorno)

Familias de herramientas (125 en total)

• Generación — sdnext_txt2img, sdnext_img2img, sdnext_control, sdnext_process_image, sdnext_process_batch, sdnext_detail, sdnext_prompt_enhance

• Enumeradores — sdnext_list_samplers … sdnext_list_masking (29 herramientas de listado)

• Comprensión de imágenes — sdnext_caption, sdnext_caption_dispatch, sdnext_tagger, sdnext_vqa, sdnext_analyze

• Modelos/opciones — actualizar/seleccionar/cargar checkpoint, VAE, UNet, LoRA; sdnext_get_options/sdnext_set_options

• Servidor — sdnext_status, sdnext_progress, interrumpir/saltar, reiniciar/apagar, registro, historial, almacenamiento, GPU

• Archivos/Galería — sdnext_upload, sdnext_file, eliminar-, explorador/, sdnext_png_info

• Procesamiento de control — sdnext_preprocess, sdnext_mask, sdnext_detect

• Moderación — sdnext_nudenet, sdnext_prompt_lang, sdnext_image_guard, sdnext_prompt_banned

• CivitAI — búsqueda, modelo/versión, cola de descargas, ajustes, marcadores, bloqueados, historial (27 herramientas)

• Meta — sdnext_list_tools, sdnext_call_api (passthrough genérico), gestión de archivos de autocompletado

Ejecuta sdnext_list_tools en tiempo de ejecución para ver el catálogo completo, o node scripts/dump_tools.mjs.

Flujo de trabajo típico

sdnext_list_checkpoints   → pick a model
sdnext_list_samplers      → pick a sampler
sdnext_txt2img { prompt, sd_model_checkpoint, sampler_name, width:1024, height:1024, steps:20 }
sdnext_progress           → poll while it runs
sdnext_caption / sdnext_tagger → understand a result

Las imágenes son PNG base64 en bruto de entrada y salida (sin prefijo data:); se aceptan referencias "upload:<id>" cuando una imagen es una entrada. Pasa save_dir en cualquier herramienta de generación para también escribir el resultado en disco.

Scripts

npm run check          # syntax-check the entry
node scripts/smoke.mjs # DRY_RUN stdio smoke test (no live server needed)
node scripts/dump_tools.mjs  # export the tool catalog

Estructura

Consulta ../framework/ para la documentación de arquitectura (datos de la API en 01-sdnext-api/, decisiones de diseño en 02-mcp-design/). Código fuente en src/: config.js, client.js, image.js, registry.js, index.js y tools/ (un archivo por dominio).