# inkscape-mcp

Servidor MCP local, por `stdio`, para controlar Inkscape headless de forma
acotada. Gestiona documentos SVG/Inkscape, diseño vectorial tipado, recursos
locales y exportaciones verificadas a PNG, PDF y SVG.

## Lo que funciona hoy

- Descubrimiento de Inkscape, incluido el paquete MSIX de Windows, y
  `--doctor` con evidencia de capacidades.
- Workspaces autorizados con rutas relativas seguras, revisiones SHA-256,
  locks, backups y commits atomicos.
- Crear, inspeccionar y redimensionar documentos SVG con semántica
  `page_only`, medidas custom o presets A3/A4/Letter, y páginas iniciales.
- Paginas explicitas de Inkscape 1.4: listar, agregar, actualizar, borrar y
  reordenar con IDs estables.
- Ajustes tipados de pagina: color/opacidad de pagina, color de escritorio y
  color/opacidad del borde.
- Diseño vectorial tipado: formas, capas, grupos, orden Z, transformaciones,
  alineación/distribución, paths seleccionados, texto/tspans, metadatos,
  gradientes, patrones, marcadores, filtros, clips, máscaras, símbolos,
  clones, guías y cuadrículas.
- Imágenes locales PNG/JPEG/GIF/WebP con enlace o embed, relink/extract, crop
  no destructivo, DPI efectivo, recursos remotos y diagnósticos básicos de
  accesibilidad.
- Importación saneada de SVG/SVGZ con manifiesto SHA-256 y límites contra
  expansión gzip; el catálogo de importadores nativos se consulta en runtime.
- Lotes de exportación verificados, artefactos, jobs y presets `icon-pack`,
  `web-asset-pack`, `print-pdf-300dpi`, `plain-svg` y entregables individuales.

No acepta XML, comandos de shell ni rutas absolutas libres desde el cliente.
Consulta el [plan maestro](./PLAN_IMPLEMENTACION.md) para formatos y funciones
avanzadas que aún están pendientes.

## Requisitos

- Node.js 24.x y npm 11.x.
- Inkscape 1.4.4 o compatible. En Windows se detectan instalaciones PATH,
  App Paths, registro y MSIX; confirma la detección con `--doctor`.

Consulta [Inkscape en Windows](./docs/windows-inkscape.md) para diferencias
entre Microsoft Store/MSIX e instaladores convencionales, y cómo configurar un
binario local sólo cuando el diagnóstico lo requiera.

Consulta la [guía de tamaños y exportación](./docs/design-size-guide.md) para
trabajar con milímetros, `viewBox`, DPI, áreas PNG y páginas sin recortes ni
deformaciones inesperadas.

Consulta la [guía de formatos de exportación](./docs/export-guide.md) para
elegir PNG, PDF o SVG, conocer las pérdidas por formato y verificar cada
entregable.

Consulta la [guía de seguridad y workspaces](./docs/security-workspace-guide.md)
antes de automatizar: la versión actual protege rutas y publicaciones, pero no
es un sandbox para documentos de origen hostil.

El HTTP local experimental se documenta por separado en la
[guía de seguridad HTTP](./docs/http-security.md); `stdio` continúa siendo el
transporte recomendado y predeterminado.

La [matriz de compatibilidad](./docs/compatibility-matrix.md) separa el baseline
Windows/Inkscape 1.4.4 probado de formatos, plataformas y capacidades aún no
anunciadas.

Para añadir el servidor a Codex CLI o VS Code sin confundirlo con una receta de
exportación, sigue la [guía de configuración de clientes](./docs/client-configuration.md).

La [referencia de tools](./docs/tool-reference.md) cubre las 82 tools
registradas, sus flujos, errores y la forma de obtener el schema MCP exacto
mediante `tools/list`.

Si una exportación, fuente, capability o receta falla, consulta el
[troubleshooting de Windows](./docs/troubleshooting-windows.md) antes de
reintentar o ampliar permisos.

Para crear un tarball local con SBOM, provenance y hashes antes de cualquier
publicación, sigue la [guía de evidencia de release](./docs/release-evidence.md).

## Ejecutar localmente

Clona el repositorio, instala exactamente las dependencias fijadas y genera el
servidor antes de configurar tu cliente MCP:

```powershell
git clone https://github.com/Berrio/inkscape-mcp.git
cd inkscape-mcp
npm ci
npm run build
node dist/cli.js --doctor --json
```

Para verificar la instalación completa contra Inkscape, ejecuta además:

```powershell
npm run check
npm run test:mcp
```

Después inicia el servidor para el workspace autorizado:

```powershell
node dist/cli.js --workspace-root C:\ruta\a\tus\disenos
```

El último comando mantiene el protocolo MCP exclusivamente en stdout. Configura
tu cliente MCP para iniciarlo con `node`, argumento `dist/cli.js`, y uno o más
argumentos `--workspace-root`; solo esos directorios serán visibles para las
tools. Usa rutas de Windows entre comillas si contienen espacios.

Ejemplo de configuración stdio para un cliente MCP:

```json
{
  "mcpServers": {
    "inkscape": {
      "command": "node",
      "args": [
        "C:\\ruta\\a\\InKscape-MCP\\dist\\cli.js",
        "--workspace-root",
        "C:\\ruta\\a\\mis-disenos"
      ]
    }
  }
}
```

Primero llama `workspace_list`, después `document_inspect` para obtener la
revisión, y envíala como `expectedRevision` en cada mutación. Nunca reutilices
una revisión después de que otra operación haya cambiado el documento.

## Exportar sin un cliente de IA

La CLI `export` abre un servidor MCP local temporal y usa exclusivamente sus
tools públicas: obtiene la revisión vigente del SVG, hace preflight del preset
y publica el lote de forma atómica. No acepta shell, XML ni rutas de documento
fuera del workspace. Por tanto se puede usar directamente desde PowerShell,
incluso cuando no haya una sesión de Codex o de otro modelo activa:

```powershell
inkscape-mcp export `
  --source etiquetas.svg `
  --preset print-pdf-300dpi `
  --output-directory entregables `
  --workspace-root C:\ruta\a\tus\disenos
```

Los presets admitidos son `print-a4-pdf`, `print-pdf-300dpi`, `web-png`,
`web-asset-pack`, `plain-svg` e `icon-pack`. Añade `--dry-run` para obtener
JSON con las rutas, digest y vencimiento del plan sin crear directorios ni
publicar archivos. Si se configuran varios workspaces, selecciona uno por su
índice estable de la sesión con `--workspace-index 0` a `31`.

Para varios pasos, guarda una receta JSON cerrada y ejecútala sin IA:

```json
{
  "schema": "inkscape-mcp-recipe/v1",
  "source": "etiquetas.svg",
  "operations": [
    { "kind": "inspect" },
    {
      "kind": "preflight",
      "preset": "print-pdf-300dpi",
      "outputDirectory": "entregables"
    },
    {
      "kind": "export",
      "preset": "web-asset-pack",
      "outputDirectory": "web"
    }
  ]
}
```

```powershell
inkscape-mcp run .\exportaciones.json --workspace-root C:\ruta\a\tus\disenos
```

`run` devuelve un recibo JSON `inkscape-mcp-recipe-receipt/v1`; redirígelo a
un archivo si deseas conservarlo. Sus códigos de salida son `0` (éxito), `2`
(receta inválida) y `3` (fallo de ejecución). Se validan esquema, fuente,
capabilities, rutas y colisiones entre outputs previstos antes de publicar el
primer export; cada export se publica mediante su lote atómico habitual.

Para no perder un lote si termina una sesión de IA, la cola durable guarda una
receta validada y su recibo bajo `.inkscape-mcp\recipe-queue` del workspace.
Un worker se ejecuta explícitamente (por ejemplo, desde el Programador de
tareas); sólo un worker local puede reclamar la cola y una receta interrumpida
queda como fallida hasta que decidas reintentarla:

```powershell
$job = inkscape-mcp queue enqueue .\exportaciones.json --workspace-root C:\ruta\a\tus\disenos | ConvertFrom-Json
inkscape-mcp queue work --workspace-root C:\ruta\a\tus\disenos
inkscape-mcp queue list --status failed --workspace-root C:\ruta\a\tus\disenos
inkscape-mcp queue get $job.id --workspace-root C:\ruta\a\tus\disenos
inkscape-mcp queue retry $job.id --workspace-root C:\ruta\a\tus\disenos
```

`queue cancel` cancela inmediatamente una receta aún en espera. Si ya fue
reclamada, registra una cancelación cooperativa: deja terminar el batch atómico
en curso y detiene los pasos restantes de la receta; no mata Inkscape a ciegas
ni presenta un resultado parcial como entrega completa.

`queue list` recupera los IDs después de reiniciar o cerrar la conversación;
devuelve sólo metadatos compactos (estado, fuente, pasos y error), nunca el
cuerpo de la receta ni recibos. Admite `--status queued|running|completed|failed|cancelled`
y `--limit 1` a `100`.

### Automatización de Windows

El paquete incluye los scripts PowerShell
`scripts\windows\Invoke-InkscapeMcpRecipe.ps1` y
`scripts\windows\Register-InkscapeMcpDailyTask.ps1` para una receta, y
`scripts\windows\Invoke-InkscapeMcpQueue.ps1` y
`scripts\windows\Register-InkscapeMcpQueueDailyTask.ps1` para la cola durable.
El runner de receta deja un log, sin abrir GUI ni solicitar credenciales:

```powershell
& .\scripts\windows\Invoke-InkscapeMcpRecipe.ps1 `
  -RecipePath C:\disenos\exportaciones.json `
  -WorkspaceRoot C:\disenos `
  -LogPath C:\disenos\logs\exportaciones.log `
  -NonInteractive
```

Para procesar trabajos previamente encolados, incluso después de cerrar Codex,
programa o ejecuta el worker de cola:

```powershell
& .\scripts\windows\Invoke-InkscapeMcpQueue.ps1 `
  -WorkspaceRoot C:\disenos `
  -LogPath C:\disenos\logs\queue.log `
  -MaxJobs 20 `
  -NonInteractive
```

Los scripts `Register-*` **sólo cuando tú los ejecutes** registran una tarea
diaria para el usuario actual en modo `Interactive`, sin contraseña almacenada;
por tanto se ejecutan mientras ese usuario haya iniciado sesión. Antes puedes
inspeccionar el de receta con `-WhatIf`:

```powershell
& .\scripts\windows\Register-InkscapeMcpDailyTask.ps1 `
  -TaskName "Inkscape MCP - etiquetas" `
  -RecipePath C:\disenos\exportaciones.json `
  -WorkspaceRoot C:\disenos `
  -LogPath C:\disenos\logs\exportaciones.log `
  -DailyAt "02:00" -WhatIf
```

El registro equivalente para la cola ejecuta todos los trabajos en espera hasta
`-MaxJobs`, sin crear una receta nueva:

```powershell
& .\scripts\windows\Register-InkscapeMcpQueueDailyTask.ps1 `
  -TaskName "Inkscape MCP - cola" `
  -WorkspaceRoot C:\disenos `
  -LogPath C:\disenos\logs\queue.log `
  -DailyAt "02:15" -MaxJobs 20 -WhatIf
```

Después de verificar la salida, elimina `-WhatIf` para registrar la tarea.
El script no añade privilegios, no expone HTTP y no guarda credenciales.

## Tools MCP actuales

| Grupo              | Tools principales                                                                                                                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Estado y archivos  | `inkscape_status`, `workspace_list`, `workspace_list_documents`, `document_snapshot`, `document_restore`                                                                                                                                                                                                                                         |
| Documento          | `document_create`, `document_inspect`, `document_resize`, `document_fit_page`, `document_page_adjust`, `document_pages`, `document_page_validate`, `document_settings`, `document_preflight`, `document_render_preview`                                                                                                                          |
| Diseño             | `elements_create`, `connector_create`, `connector_retarget`, `connector_route`, `elements_query`, `elements_update`, `elements_delete`, `elements_transform`, `elements_flatten_transform`, `elements_arrange`, `elements_group`, `elements_duplicate`, `elements_reparent`, `elements_align`, `elements_distribute`, `elements_remove_overlaps` |
| Texto y paths      | `text_manage`, `text_path_manage`, `flowed_text_inspect`, `flowed_text_convert`, `text_to_paths`, `paths_combine`, `paths_boolean`, `path_modify`, `path_break_apart`, `path_reverse`, `path_node_move`, `path_node_edit`, `path_effects_inspect`, `path_effects_manage`                                                                         |
| Recursos SVG       | `gradients_manage`, `mesh_gradients_inspect`, `palette_inspect`, `palette_apply`, `color_management_inspect`, `patterns_manage`, `markers_manage`, `filters_manage`, `clips_manage`, `masks_manage`, `defs_vacuum`, `symbols_manage`, `guides_grids_manage`, `metadata_manage`                                                                   |
| Imágenes y calidad | `images_manage`, `images_crop`, `images_inspect_dpi`, `resources_inspect_remote`, `accessibility_inspect`, `fonts_list`, `fonts_preflight`                                                                                                                                                                                                       |
| Importación        | `document_import`, `document_import_raster`, `document_import_pdf`, `document_import_postscript`, `document_import_capabilities`, `document_import_svg`, `assets_package`, `document_normalize_ids`                                                                                                                                              |
| Exportación        | `document_export`, `document_export_preset_plan`, `document_export_batch`, `export_png`, `export_pdf`, `export_pdf_pages`, `export_svg`, `job_get`, `job_cancel`                                                                                                                                                                                 |

Las mutaciones y exportaciones exigen `expectedRevision`. Si un archivo cambia
entre la lectura y el commit, la operación falla en lugar de sobrescribir una
revisión ajena. Toda exportación entrega a Inkscape una copia verificada del
SVG en staging, nunca la ruta viva del workspace.

## Seguridad y estado

El proyecto no promete aislar vulnerabilidades desconocidas de parsers nativos.
Limita rutas, XML, argumentos, procesos, tamaños y sobrescrituras; la política
actual de input nativo es `trusted-local-only`. La exportación rechaza SVG con
contenido activo o recursos remotos antes de iniciar Inkscape; las mutaciones
de resize aplican la misma regla.

Las instrucciones de contribución y los invariantes se encuentran en
[AGENTS.md](./AGENTS.md). El paquete sigue siendo privado: publicarlo en npm o
en un registry requerira autorizacion explicita separada.

## Licencia

[MIT](./LICENSE) Copyright 2026 Berrio.