Servidor MCP para agentes de IA

Pyzed incluye un servidor MCP. Conéctalo a tu agente de IA (Claude Code, Claude Desktop, Cursor, VS Code, Zed…) y el agente deja de adivinar: consulta la firma exacta de cada widget y componente, lee esta documentación, sigue las buenas prácticas de Pyzed, genera apps, componentes y formularios del diseñador, comprueba el código que escribe e incluso mira una captura del resultado.

Instalación

El servidor es un extra opcional del paquete (necesita Python 3.10 o superior):

uv

Windows, macOS y Linux

uv add "pyzed-ui[mcp]"
uv run pyzed mcp                       # arranca el servidor por stdio (también python -m pyzed.mcp)

pip

Windows, macOS y Linux

pip install "pyzed-ui[mcp]"
pyzed mcp                       # arranca el servidor por stdio (también python -m pyzed.mcp)

python

macOS y Linux

python3 -m pip install "pyzed-ui[mcp]"
python3 -m pyzed mcp                       # arranca el servidor por stdio (también python -m pyzed.mcp)

Windows (PowerShell)

py -m pip install "pyzed-ui[mcp]"
py -m pyzed mcp                       # arranca el servidor por stdio (también python -m pyzed.mcp)

Casi nunca lo ejecutas tú: lo arranca el agente. Con uv el agente puede ejecutarlo sin instalar nada antes, con uvx --from "pyzed-ui[mcp]" pyzed mcp.

pyzed mcp --transport streamable-http lo sirve por HTTP en 127.0.0.1. Ahí cualquier programa de tu equipo puede usarlo sin iniciar sesión, así que screenshot y las herramientas de proyecto, que leen y escriben archivos y ejecutan código, se omiten salvo que añadas --allow-code.

Las herramientas de proyecto trabajan en la carpeta donde arrancó el servidor; pyzed mcp --root RUTA elige otra. Nunca salen de ella ni tocan archivos que puedan guardar secretos (.env, claves, .netrc…).

Conecta tu agente

Claude Code

claude mcp add pyzed -- uvx --from "pyzed-ui[mcp]" pyzed mcp

Dentro de un proyecto creado con pyzed new, usa el entorno del propio proyecto para que el servidor vea la misma versión de Pyzed y tus componentes: claude mcp add pyzed -- uv run pyzed mcp.

Claude Desktop, Cursor y otros clientes

La mayoría de clientes leen un JSON con la misma forma (claude_desktop_config.json, .cursor/mcp.json…):

{
  "mcpServers": {
    "pyzed": {
      "command": "uvx",
      "args": ["--from", "pyzed-ui[mcp]", "pyzed", "mcp"]
    }
  }
}

VS Code

En .vscode/mcp.json:

{
  "servers": {
    "pyzed": { "type": "stdio", "command": "uvx", "args": ["--from", "pyzed-ui[mcp]", "pyzed", "mcp"] }
  }
}

Si Pyzed ya está instalado en un entorno, "command": "pyzed", "args": ["mcp"] funciona en todos.

Qué recibe el agente

Herramientas

Herramienta	Qué hace
plan_app	Por dónde empezar una app o pantalla: los bloques y ejemplos más parecidos, los componentes y temas de guía que necesita, la documentación que leer y los pasos. Los agentes la llaman primero.
get_guide	Cómo funciona Pyzed ("overview"), sus reglas ("best-practices"), recetas ejecutables ("cookbook": estructura de una app, trabajo en segundo plano, formularios, listas virtuales, animación, shaders, juegos, marcos de ventana propios, layouts con anclas) o cualquier tema de list_guides ("games", "shaders", "performance", "integrations"…), en inglés o en español.
list_guides	Todos los temas que acepta get_guide.
list_components	Cada widget (pz.*), componente listo (pz.ui.*), tipo de la caja de herramientas del diseñador y clase pz.Component, con un resumen de una línea. Filtra por kind, query, category o role (el rol de color de los tipos del diseñador: layout, input, action, navigation, display, media, system, custom).
describe_component	La firma, la documentación y los parámetros de un widget o componente ("pz.column", "ui.button"), o las propiedades y eventos de un tipo del diseñador ("designer:button").
search_reference, read_reference	Buscan y leen la referencia de cada módulo, clase y función (pyzed.game, pyzed.updater, ui.virtual_list…).
editor_keymap	Los atajos por defecto del editor de código y cómo cambiarlos.
search_icons	Nombres de iconos Lucide para icon= y pz.icon.
list_themes	Los temas incluidos y los tokens de color que aceptan los estilos ("accent", "panel"…).
list_docs, read_docs	Las páginas de esta documentación, en inglés o en español.
list_examples, read_example	El código de los ejemplos, por kind: apps, bloques (pantallas completas para copiar), juegos, showcase (shaders, efectos), integraciones con backend (FastAPI, SQLAlchemy, SQLModel, Django), tutorial y diseñador.
new_app	Un script pz.App ejecutable: un punto de partida simple o un workspace estilo editor.
new_component	El esqueleto de un pz.Component con sus props, estado y eventos.
new_form	Un formulario del diseñador visual: el .pzform y su módulo de handlers.
validate_code	Revisa el código sin ejecutarlo: nombres que no existen en pz o pz.ui, argumentos que una función no acepta, apps sin view(), componentes sin render(), efectos secundarios en view(), lambdas en bucles que no capturan la variable y las comprobaciones de pyflakes de ruff si está instalado.
validate_form	Revisa un .pzform (tipos, propiedades, eventos, nombres, contenedores) y que su módulo de handlers defina cada handler.
screenshot	Dibuja el código fuera de pantalla (sin ventana ni GPU) y devuelve un PNG, para que el agente vea lo que construyó.
animation_properties, new_animation, check_animation	Animaciones en línea de tiempo: qué puede animar una pista, una biblioteca .pzanim nueva a partir de clips y pistas, y su revisión.
list_shader_nodes, new_shader, check_shader	Los nodos de los grafos de shaders, un .pzshad nuevo desde una plantilla y su compilación a WGSL con los errores por nodo.

Herramientas de proyecto

Con ellas el agente construye una app completa en una carpeta, desde el proyecto hasta una revisión limpia:

Herramienta	Qué hace
project_info	El proyecto: nombre, versión, entrada (su script o, si no, el formulario principal), formularios, componentes, shaders, paquete, dependencias, archivos y entorno (el .venv donde corre, el sistema, WSL).
list_files, read_file	Listan y leen los archivos de la carpeta.
write_files	Crea o reemplaza varios archivos a la vez y revisa cada archivo Python, formulario y grafo de shader que escribió.
create_project	Un proyecto uv nuevo, como pyzed new (pyzed-ui, ruff, ty, ui/main.pzform, src/<paquete>, git).
add_dependency	uv add en el proyecto.
check_project	Las comprobaciones de Pyzed en cada archivo, más ruff y ty.
run_tests	uv run pytest en el proyecto.
screenshot_project	Una captura de un script, formulario, componente o grafo de shader, en el entorno del propio proyecto; por defecto la entrada.
project_settings, set_project_settings	Los ajustes propios del proyecto: su renderizador (GPU o CPU, API gráfica, GPU, vsync, en [tool.pyzed.rendering]) y las preferencias del editor y del diseñador que comparte en .pyzed/settings.json (tabulación, cuadrícula…).
start_live_preview, live_preview_status, stop_live_preview	Abren la app en una ventana real con hot reload mientras el agente la construye: cada archivo que escribe actualiza la ventana al guardarse, así ves cómo toma forma. El estado devuelve lo que la app imprimió, trazas de error incluidas.

Recursos y prompts

Los clientes que admiten recursos pueden adjuntar pyzed://guide, pyzed://best-practices, pyzed://cookbook, pyzed://reference/{name}, pyzed://components, pyzed://themes, pyzed://docs, pyzed://component/{name} y pyzed://docs/{slug} (con -- en lugar de /, como guides--layout).

Los prompts create_app, create_component y create_form empiezan una tarea con los pasos correctos: leer las guías, buscar componentes existentes, generar, validar y previsualizar. build_project construye una app completa en la carpeta: lee las guías y ejemplos, crea el proyecto, lo escribe en pasos pequeños y luego lo revisa, lo prueba y lo mira hasta que todo esté limpio.

Ejemplo de sesión

Haz un componente de Pyzed que muestre una valoración con estrellas y deje cambiarla.

Una ejecución típica del agente con el servidor conectado:

1. get_guide("best-practices") y luego list_components(query="rating") para comprobar que no existe nada parecido.
2. new_component("star rating", props=[{"name": "value", "type": "int", "default": 0}], events={"change": "Se eligió una estrella."}, icon="star").
3. Completa render() con pz.row, pz.text(...).on(click=...) y self.emit("change", i), consultando describe_component("pz.text") para los parámetros.
4. validate_code(code) y screenshot(code + "def preview():\n return StarRating(value=3)") para verlo.

Cómo funciona

El servidor vive en el paquete (pyzed.mcp), así que lo que sabe coincide siempre con la versión instalada: las firmas y docstrings salen del propio código, las descripciones de esta referencia y la caja de herramientas del diseñador de su registro, incluidas tus propias clases pz.Component. Las páginas de la documentación y los ejemplos se leen del repositorio si trabajas desde el código fuente y, si no, se descargan de GitHub en el tag de la versión instalada.

screenshot ejecuta el código en un proceso aparte con un límite de 60 segundos y sustituye pz.run, así que no se abre ninguna ventana. Usa el mismo renderizador fuera de pantalla que tests y capturas.

pyzed.mcp.knowledge, pyzed.mcp.projects, pyzed.mcp.scaffold y pyzed.mcp.validate son Python normal y funcionan sin el SDK de MCP, por ejemplo desde tus propios scripts o tests.

Más sobre agentes de IA

La sección Agentes de IA reúne el resto: la guía de prompts con una sesión MCP real, llms.txt y reglas para editores con plantillas de AGENTS.md, Cursor y Copilot, y Crear apps con IA.