# Servidor MCP para agentes de IA

> Conecta agentes de IA (Cursor, VS Code, Zed y otros clientes MCP) al servidor MCP de Pyzed para que conozcan su API y generen y comprueben código.

Source: https://albakore.github.io/pyzed/es/guides/mcp/

Pyzed incluye un servidor [MCP](https://modelcontextprotocol.io). 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):

Casi nunca lo ejecutas tú: lo arranca el agente. Con [uv](https://docs.astral.sh/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

```bash
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`...):

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

### VS Code

En `.vscode/mcp.json`:

```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](https://albakore.github.io/pyzed/es/reference/) 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](https://albakore.github.io/pyzed/es/animation/timeline/): 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](https://albakore.github.io/pyzed/es/shading/shader-graphs/), 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](https://albakore.github.io/pyzed/es/editor/settings/#renderizado) (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](https://albakore.github.io/pyzed/es/guides/testing/).

`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](https://albakore.github.io/pyzed/es/ai/) reúne el resto: la [guía de prompts](https://albakore.github.io/pyzed/es/ai/prompting/) con una
sesión MCP real, [llms.txt y reglas para editores](https://albakore.github.io/pyzed/es/ai/llms-txt/) con plantillas de `AGENTS.md`, Cursor y
Copilot, y [Crear apps con IA](https://albakore.github.io/pyzed/es/ai/ai-apps/).