Files

T

Fase 1: schemas de los 5 MCPs y script de generacion de replay

data/schemas/*.json: dump fiel de las tool definitions reales de
Penpot (4), Gitea (53), GitHub-personal (43), Docmost (17) y
Atlassian (37), obtenidas directo de las definiciones ya cargadas
en la sesion de Claude Code (no se escribio un cliente MCP nuevo,
para no arriesgar desviarse del esquema real).

PENPOT_DEPLOYMENT_NOTES.md: investigacion del codigo fuente oficial
de @penpot/mcp confirma que import_image y export_shape.filePath
estan ausentes porque este deployment corre en modo remoto/multi-
usuario (isFileSystemAccessEnabled() = !isRemoteMode()) -- documentado
tambien en una subpagina nueva de Docmost.

scripts/03_build_replay.py: genera ~700 ejemplos de replay (anti-
forgetting) contra el vLLM de produccion, 80 prompts semilla
(conversacion general/codigo/razonamiento) x 9 pasadas variando
temperatura. Mapea el campo "reasoning" de la API de vLLM a
"reasoning_content" para la convencion de chat template.

2026-07-28 05:34:55 +00:00

3.9 KiB

Raw Blame History

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.

3.9 KiB Raw Blame History