# Penpot MCP — notas de este deployment

Investigado a fondo en la Fase 1 (código fuente oficial + docs), para saber exactamente qué tools/parámetros existen realmente en este deployment y cuáles hay que excluir del dataset de entrenamiento.

## Identificación del proyecto

- Repo oficial: `github.com/penpot/penpot/tree/develop/mcp` (antes `penpot/penpot-mcp`, ahora archivado y fusionado al monorepo principal).
- Paquete npm: `@penpot/mcp` (se ejecuta vía `npx -y @penpot/mcp@latest`).
- Monorepo con 4 paquetes: `packages/common` (tipos compartidos), `packages/server` (servidor MCP), `packages/plugin` (plugin de Penpot vía WebSocket), `types-generator`.
- Confirmado con 100% de coincidencia contra el código fuente (`mcp/packages/server/src/tools/*.ts`) comparando las descripciones exactas de las 4 tools (incluida la frase gramaticalmente atípica "You have access two main objects" en `execute_code`).

## Tools registradas en el código, por condición de gating

- **Siempre registradas** (presentes en nuestro deployment): `execute_code`, `high_level_overview`, `penpot_api_info`, `export_shape`.
- **`import_image`** — registrada solo si `mcpServer.isFileSystemAccessEnabled()` es `true`. **Ausente en nuestro deployment.**
- **Solo en modo devenv interno de Penpot** (`PENPOT_MCP_DEVENV=true`, para el equipo core, no para diseñadores): `CljsReplTool`, `ImportPenpotFileTool`, `CljsCompilerOutputTool`, `CljCheckParentheses`, `ReadTaigaIssueTool` (Clojure REPL y Taiga — no relevante para el dataset de diseño).

## Lógica exacta del gating (`PenpotMcpServer.ts`)

```
isRemoteMode() = isMultiUserMode() || (PENPOT_MCP_REMOTE_MODE === "true")
isFileSystemAccessEnabled() = !isRemoteMode()
```

`import_image` solo se registra si `isFileSystemAccessEnabled()` es verdadero.

## `export_shape` y `filePath`

El schema oficial SÍ define un parámetro opcional `filePath` (para guardar el export a disco), pero el constructor de `ExportShapeTool` hace `delete schema.filePath` cuando `!isFileSystemAccessEnabled()`. La descripción también agrega condicionalmente la frase "Alternatively, you can save it to a file." solo cuando el filesystem está habilitado.

**En nuestro deployment, `export_shape` NO tiene `filePath`** (ver `penpot.json`) — señal inequívoca de que este deployment corre en modo remoto/multi-usuario con acceso a filesystem deshabilitado, la misma condición que oculta `import_image`.

## Estructura de la Penpot Plugin API (accesible desde `execute_code`)

El objeto global `penpot` (tipo `Penpot`, ver docs oficiales en https://help.penpot.app/plugins/ y https://doc.plugins.penpot.app/, tipos vía npm `@penpot/plugin-types`) expone:

- `ui`, `utils` (`ContextUtils`), `root`/`currentFile`/`currentPage`/`viewport`, `library`, `fonts`, `currentUser`/`activeUsers`, `theme`, `localStorage`, `selection`.
- Métodos de creación: `createRectangle`, `createBoard`, etc.
- Árbol de diseño: `Page` → `Board`/`Group` → shapes de bajo nivel (`Rectangle`, `Path`, `Text`, `Ellipse`, `Image`, `Boolean`, `SvgRaw`), todos derivando de `ShapeBase`/`Shape`.

**Importante**: `penpotUtils` (visto en la descripción de `execute_code`) **no es API oficial de Penpot** — es una capa de conveniencia propia del plugin MCP (`mcp/packages/plugin/src/PenpotUtils.ts`), con helpers como `findShapeById`, `exportImage`, `importImage`, `setParentXY`. No confundir con la API oficial `penpot`.

## Implicación para el dataset de entrenamiento (Fase 2)

El bucket de Penpot debe reflejar que, en deployments remotos/multi-usuario (como este), `import_image` y `export_shape(filePath)` no existen. El modelo debe aprender a:

- Nunca intentar llamar `import_image` (no existe como tool).
- Nunca pasar `filePath` a `export_shape` (el parámetro no está en el schema; si el modelo lo inventa, la llamada fallará con un error de parámetro no reconocido).
- Devolver imágenes por respuesta directa (base64/PNG vía `export_shape`) en vez de asumir escritura a disco.