aleleba
b2aa855a70
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.
50 lines
3.9 KiB
Markdown
50 lines
3.9 KiB
Markdown
# 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.
|