Skip to main content
Glama
README.md
# Warsztat WordCamp Wrocław 2026 – WordPress Playground + Novamira (MCP Server)

[![WordPress Playground](https://img.shields.io/badge/WordPress-Playground-3858e9?logo=wordpress&logoColor=white)](https://developer.wordpress.org/playground/)
[![Novamira MCP](https://img.shields.io/badge/Plugin-Novamira_v1.12.7-blue?logo=anthropic)](https://github.com/use-novamira/novamira)
[![WooCommerce Latest](https://img.shields.io/badge/WooCommerce-Latest-96588a?logo=woocommerce&logoColor=white)](https://woocommerce.com/)
[![PHP 8.3](https://img.shields.io/badge/PHP-8.3-777bb4?logo=php&logoColor=white)](https://www.php.net/)
[![WordPress Latest](https://img.shields.io/badge/WordPress-Latest-21759b?logo=wordpress)](https://wordpress.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)

> Gotowe środowisko **WordPress Playground** z automatycznie zainstalowaną i skonfigurowaną wtyczką **[Novamira](https://github.com/use-novamira/novamira)** (serwer MCP) oraz najnowszą wersją **WooCommerce** z zaimportowanymi przykładowymi produktami i mediami. Przygotowane z myślą o uczestnikach warsztatów na **WordCamp Wrocław 2026**.

---

## 🚀 Błyskawiczny start lokalny (One-Liner bez klonowania repo)

Nie musisz klonować tego repozytorium ani pobierać żadnych plików. Jeśli masz zainstalowane środowisko **Node.js (LTS)**, wystarczy uruchomić w terminalu (PowerShell / Terminal macOS / Linux) jedno polecenie:

```bash
npx -y @wp-playground/cli server --blueprint="https://raw.githubusercontent.com/damadorPL/warsztat-wordcamp-wroclaw-2026/main/blueprint.json" --port=9400
```

> [!TIP]
> **Pełna automatyzacja i dane dostępowe (Zero Configuration):**  
> Polecenie pobierze najświeższy blueprint bezpośrednio z GitHuba, uruchomi WordPress Playground z serwerem **Novamira MCP**, sklepem **WooCommerce** i automatycznie skonfiguruje konto administratora oraz hasło aplikacji:
> 
> | Parametr | Wartość | Zastosowanie |
> | :--- | :--- | :--- |
> | **Adres sklepu** | `http://127.0.0.1:9400` | Strona główna WordPress + WooCommerce |
> | **Kokpit WordPress** | `http://127.0.0.1:9400/wp-admin/` | Panel logowania i administracji |
> | **Panel Novamira MCP** | `http://127.0.0.1:9400/wp-admin/admin.php?page=novamira-connect` | Diagnostyka i status wtyczki MCP |
> | **Login** | `admin` | Nazwa konta administratora |
> | **Hasło logowania** | `admin` | Hasło logowania w formularzu wp-login.php |
> | **Hasło Aplikacji dla MCP** | `novamira-secret-pass-2026` | Hasło autoryzacji agenta AI (`WP_API_PASSWORD`) |
> | **REST API / MCP Endpoint** | `http://127.0.0.1:9400/wp-json/mcp/novamira` | Punkt końcowy API dla proxy MCP (`WP_API_URL`) |

---

## 📖 Czym jest ten projekt?

Ten projekt zawiera definicję **WordPress Playground Blueprint** ([`blueprint.json`](./blueprint.json)), która automatyzuje proces konfiguracji środowiska WordPress z wtyczką **Novamira**.

### Co to jest Novamira?

[Novamira](https://github.com/use-novamira/novamira) to otwartoźródłowa wtyczka do WordPressa pełniąca rolę serwera **Model Context Protocol (MCP)**. Pozwala asystentom i agentom AI (np. **Claude Desktop**, **Cursor**, **Windsurf**, **VS Code**, **Google Antigravity**) na bezpośrednią komunikację ze środowiskiem WordPress:

- 🛠️ **Wykonywanie kodu PHP** w kontekście WordPressa z dostępem do `$wpdb`, wbudowanych funkcji i załadowanych wtyczek.
- 💻 **Wykonywanie poleceń WP-CLI** (w tym w tle).
- 📁 **Inspekcję i edycję plików motywów i wtyczek** oraz pracę w bezpiecznym sandboxie (`wp-content/novamira-sandbox`).
- 📊 **Zarządzanie treściami, wpisami i blokami Gutenberga** w czasie rzeczywistym.

---

## 📦 Wymagania wstępne i instalacja (Node.js & mcp-wordpress-remote)

Do pracy ze środowiskiem warsztatowym na własnym komputerze (lokalny serwer Playground oraz integracja z agentami AI poprzez MCP) zalecane jest środowisko **Node.js** oraz pakiet **`@automattic/mcp-wordpress-remote`**.

### 1. Instalacja środowiska Node.js

Wymagana wersja: **Node.js LTS (v20+ lub nowszy)**.

- **Windows (PowerShell / winget):**
  ```powershell
  winget install OpenJS.NodeJS.LTS
  ```
  _(lub pobierz instalator `.msi` z oficjalnej strony [nodejs.org](https://nodejs.org))_
- **macOS (Homebrew):**
  ```bash
  brew install node
  ```
- **Linux (Ubuntu/Debian):**
  ```bash
  curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
  sudo apt-get install -y nodejs
  ```
- **Weryfikacja instalacji:**
  ```bash
  node -v   # np. v22.x lub v24.x
  npm -v    # np. 10.x lub 12.x
  ```

---

### 2. Instalacja zależności w tym katalogu (`package.json`)

W tym repozytorium znajduje się skonfigurowany plik [`package.json`](./package.json). Aby zainstalować wszystkie wymagane pakiety lokalnie, przejdź do katalogu projektu i wykonaj:

```bash
npm install
```

W katalogu `node_modules` zostaną zainstalowane:

- **`@automattic/mcp-wordpress-remote`** – oficjalny serwer proxy MCP firmy Automattic (polecenie `mcp-wordpress-remote`), łączący klienty AI ze zdalnymi i lokalnymi instancjami WordPressa z wtyczką Novamira.
- **`@wordpress/block-serialization-default-parser`** – oficjalny parser bloków Gutenberga używany przez silnik walidacji layoutu.
- **`@wp-playground/cli`** – oficjalne narzędzie WP Playground CLI do uruchamiania WordPressa lokalnie w Node.js (WebAssembly) bez Dockera czy MySQL.

#### Dostępne skrypty npm:

- `npm run start` (lub `npm run playground`) – uruchamia lokalny serwer WordPress Playground z lokalnym plikiem blueprintu na porcie `9400`:
  ```bash
  npm run start
  ```
- `npm run start:remote` – uruchamia serwer pobierając najświeższą wersję blueprintu bezpośrednio z GitHuba:
  ```bash
  npm run start:remote
  ```
- `npm run test:blueprint` – uruchamia blueprint weryfikacyjnie w trybie headless:
  ```bash
  npm run test:blueprint
  ```
- `npm run test:layout` – uruchamia walidator na przykładowym layoucie strony lądowania:
  ```bash
  npm run test:layout
  ```
- `npm run validate:layout -- <plik>` – waliduje dowolny kod bloków lub plik HTML pod kątem poprawności składni i hierarchii:
  ```bash
  npm run validate:layout -- dane/przykladowy-layout.html
  ```
- `npm run mcp` – uruchamia lokalne proxy MCP `mcp-wordpress-remote`.

---

### 3. Instalacja globalna `mcp-wordpress-remote` (opcjonalnie)

Możesz również zainstalować proxy globalnie w systemie, aby polecenie `mcp-wordpress-remote` było dostępne w dowolnej ścieżce:

```bash
npm install -g @automattic/mcp-wordpress-remote
```

---

## 🛠️ Sposoby uruchomienia Blueprintu

Możesz uruchomić środowisko warsztatowe na kilka sposobów, w zależności od preferencji i narzędzi:

> [!IMPORTANT]
> **Wymóg uruchomienia z CLI (Serwer MCP nie działa w przeglądarce WebAssembly):**  
> Serwer **Novamira MCP** oraz proxy `mcp-wordpress-remote` wymagają lokalnego połączenia sieciowego HTTP/REST API (`http://127.0.0.1:9400`). WordPress Playground uruchomiony bezpośrednio w przeglądarce (WebAssembly) działa w izolowanym środowisku sandbox przeglądarki i **nie udostępnia portu TCP na komputerze**, w wyniku czego agenci i narzędzia AI (np. Claude Desktop, Cursor, Windsurf, VS Code, Goose) nie mają możliwości nawiązania z nim połączenia.  
> **Dlatego do poprawnego działania serwera MCP na komputerze wymagane jest uruchomienie Playgroundu lokalnie z poziomu CLI (Sposób 1 lub Sposób 2).**

### 🔑 Zestawienie danych dostępowych (dla wszystkich metod serwerowych)

Po uruchomieniu środowiska lokalnego WordPress oraz serwer Novamira MCP są wstępnie skonfigurowane z poniższymi parametrami:

| Parametr | Wartość | Zastosowanie |
| :--- | :--- | :--- |
| **Adres sklepu** | `http://127.0.0.1:9400` | Strona główna WordPress + WooCommerce |
| **Panel administracyjny** | `http://127.0.0.1:9400/wp-admin/` | Logowanie do Kokpitu WordPress |
| **Panel Novamira MCP** | `http://127.0.0.1:9400/wp-admin/admin.php?page=novamira-connect` | Diagnostyka i status wtyczki MCP |
| **Login użytkownika** | `admin` | Nazwa konta administratora |
| **Hasło logowania** | `admin` | Hasło logowania w formularzu wp-login.php |
| **Hasło Aplikacji dla MCP** | `novamira-secret-pass-2026` | Hasło autoryzacji agenta AI (`WP_API_PASSWORD`) |
| **REST API / MCP Endpoint** | `http://127.0.0.1:9400/wp-json/mcp/novamira` | Punkt końcowy API dla proxy MCP (`WP_API_URL`) |

---

### Sposób 1: Błyskawiczny start lokalny one-linerem (bez klonowania repozytorium)

Jeśli masz zainstalowane środowisko **Node.js (LTS)**, nie musisz klonować repozytorium ani instalować dodatkowych pakietów:

```bash
npx -y @wp-playground/cli server --blueprint="https://raw.githubusercontent.com/damadorPL/warsztat-wordcamp-wroclaw-2026/main/blueprint.json" --port=9400
```

- Pobiera najświeższy plik `blueprint.json` bezpośrednio z gałęzi `main` repozytorium na GitHubie.
- Uruchamia serwer WordPress Playground na porcie `9400`.
- Automatycznie instaluje wtyczkę **Novamira MCP v1.12.7**, konfiguruje sklep **WooCommerce** z przykładowymi produktami oraz tworzy konto `admin` z hasłem aplikacji `novamira-secret-pass-2026`.

---

### Sposób 2: Lokalnie ze sklonowanego repozytorium (skrypty npm)

Gdy sklonowałeś to repozytorium i zainstalowałeś zależności (`npm install`):

1. **Uruchomienie serwera z lokalnym plikiem `blueprint.json`:**
   ```bash
   npm run start
   # lub:
   npm run playground
   # lub bezpośrednio npx:
   npx -y @wp-playground/cli server --blueprint=blueprint.json --port=9400
   ```
2. **Uruchomienie serwera ze świeżym blueprintem pobieranym z GitHuba:**
   ```bash
   npm run start:remote
   ```
3. **Weryfikacja poprawności blueprintu (tryb headless bez serwera www):**
   ```bash
   npm run test:blueprint
   # lub:
   npx -y @wp-playground/cli run-blueprint --blueprint=blueprint.json
   ```

---

### Sposób 3: W aplikacji WordPress Studio (Automattic)

1. Pobierz lub otwórz [WordPress Studio](https://developer.wordpress.com/studio/).
2. Utwórz nową witrynę lub wybierz opcję importu Blueprintu.
3. Wskaż plik [`blueprint.json`](./blueprint.json).
4. Kliknij **Create Site**.

---

## 🧱 Baza referencyjna bloków i walidacja layoutu (WordPress Core & WooCommerce)

Podczas generowania stron przez agentów AI najczęstszym problemem są **halucynacje znaczników blokowych Gutenberga** (niepoprawne nazwy atrybutów, błędna hierarchia zagnieżdżania lub wstawianie statycznego HTML do bloków dynamicznych). W edytorze WordPress skutkuje to żółtym ostrzeżeniem **„Ten blok zawiera nieprawidłową lub nieobsługiwaną treść” (Attempt Block Recovery)**.

W katalogu [`dane/`](./dane/) przygotowano kompletną bazę wiedzy i narzędzia walidacyjne oparte na oficjalnym kodzie źródłowym WordPressa i WooCommerce:

### 📁 Zasoby w katalogu `dane/`:

- **[`dane/core-blocks.json`](./dane/core-blocks.json)** – pełne schematy **116 oficjalnych bloków WordPress Core** (typy, atrybuty, wspierane funkcje `supports`, reguły zagnieżdżania `parent`/`ancestor`, gotowe przykłady markup'u).
- **[`dane/woocommerce-blocks.json`](./dane/woocommerce-blocks.json)** – schematy **174 bloków WooCommerce v11.1.2** (kolekcje produktów `product-collection`, szablony `product-template`, koszyk `cart`, kasa `checkout`, filtry).
- **[`dane/blocks-reference.json`](./dane/blocks-reference.json)** – zunifikowany skorowidz z wyodrębnionymi zestawami bloków układu i e-commerce.
- **[`dane/BLOCKS-REFERENCE.md`](./dane/BLOCKS-REFERENCE.md)** – kompendium wiedzy dla promptów systemowych agenta AI (reguły delimiterów, klasy CSS, layouty `constrained`/`flex`/`grid`, tokeny kolorów i odstępów, gotowe wzorce).
- **[`dane/validate-layout.js`](./dane/validate-layout.js)** – silnik walidacji w Node.js wykorzystujący oficjalny parser `@wordpress/block-serialization-default-parser`.
- **[`dane/przykladowy-layout.html`](./dane/przykladowy-layout.html)** – w 100% zweryfikowany szablon landing page łączący sekcję Hero, 3 kolumny korzyści oraz kolekcję produktów WooCommerce.

### 🧪 Jak uruchomić walidację layoutu:

```bash
# 1. Przetestowanie przykładowego layoutu:
npm run test:layout

# 2. Walidacja dowolnego pliku HTML z blokami:
npm run validate:layout -- dane/przykladowy-layout.html

# 3. Walidacja bezpośrednio z przekazanego ciągu znaków:
node dane/validate-layout.js "<!-- wp:columns -->...<!-- /wp:columns -->"
```

### 🤖 Wykorzystanie przez Agenta AI w workflow:

1. **Analiza schematu:** Agent odczytuje definicję bloku z `dane/core-blocks.json` lub `dane/woocommerce-blocks.json`.
2. **Generowanie kodu:** Tworzy markup Gutenberga zgodnie z regułami opisanymi w `dane/BLOCKS-REFERENCE.md`.
3. **Automatyczna weryfikacja:** Uruchamia `validate-layout.js` w celu eliminacji błędów hierarchii i atrybutów.
4. **Publikacja:** Bezpiecznie publikuje wpis/stronę w WordPressie za pośrednictwem serwera Novamira MCP lub REST API.

---

## 🎓 Scenariusz warsztatowy – WordCamp Wrocław 2026

Podczas warsztatu przechodzimy przez następujące etapy:

### Krok 1: Uruchomienie lokalnego serwera Playground (CLI)

Uczestnicy uruchamiają serwer lokalnie za pomocą polecenia `npm run start` (lub One-Linera `npx`).

> [!IMPORTANT]
> Do komunikacji z agentami AI poprzez MCP wymagane jest uruchomienie serwera lokalnie w terminalu (CLI). Instancja uruchomiona bezpośrednio w przeglądarce (WebAssembly) nie udostępnia portu TCP dla proxy MCP.

Po załadowaniu środowiska przejdź do panelu **Novamira → Connect**:
- **Adres URL:** `http://127.0.0.1:9400/wp-admin/admin.php?page=novamira-connect`
- **Login:** `admin`
- **Hasło:** `admin`
- **Hasło Aplikacji dla MCP:** `novamira-secret-pass-2026`

### Krok 2: Konfiguracja połączenia w agencie AI

Do połączenia agenta AI z WordPressem używamy serwera proxy **`mcp-wordpress-remote`** (z oficjalnego pakietu `@automattic/mcp-wordpress-remote`).

#### ⚡ Rola gotowego pliku `mcp.json` w głównym katalogu projektu

W katalogu głównym repozytorium znajduje się plik [`mcp.json`](./mcp.json), który pełni dwie kluczowe role:

1. **Automatyczne ładowanie per-projekt (Project-Level MCP):**  
   Narzędzia wspierające standard lokalnej konfiguracji MCP projektu (m.in. **Claude Code CLI**, a także projekty otwierane w narzędziach zgodnych ze specyfikacją MCP) automatycznie wykrywają i wczytują serwer `novamira-playground` bezpośrednio z tego pliku po otwarciu repozytorium. Nie ma potrzeby ręcznego wprowadzania konfiguracji w ustawieniach globalnych!
2. **Gotowy szablon Zero-Configuration do skopiowania:**  
   Zawiera już wszystkie uzupełnione parametry tego warsztatu – gotowy do skopiowania do globalnych plików konfiguracyjnych (np. w Cursor, Windsurf, Claude Desktop, VS Code):

```json
{
  "mcpServers": {
    "novamira-playground": {
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "http://127.0.0.1:9400/wp-json/mcp/novamira",
        "WP_API_USERNAME": "admin",
        "WP_API_PASSWORD": "novamira-secret-pass-2026"
      }
    }
  }
}
```

Jeśli Twoje narzędzie AI wymaga wpisu w pliku globalnym (np. `%APPDATA%\Claude\claude_desktop_config.json` lub `.cursor/mcp.json`), możesz skorzystać z powyższej definicji lub wybrać wariant:

- **Wywołanie przez `npx` (zalecane):** `"command": "npx"`, `"args": ["-y", "@automattic/mcp-wordpress-remote@latest"]` – nie wymaga wcześniejszej globalnej instalacji.
- **Wywołanie globalne:** `"command": "mcp-wordpress-remote"`, `"args": []` – jeśli pakiet zainstalowano globalnie poleceniem `npm install -g @automattic/mcp-wordpress-remote`.

> 📖 **Kompletne instrukcje i szablony konfiguracji dla wszystkich środowisk AI:**  
> Szczegółowe przewodniki konfiguracji MCP w edytorach (Cursor, Windsurf, VS Code, Zed), aplikacjach desktopowych (Claude Desktop, Goose, LibreChat, LM Studio) oraz frameworkach (Claude Code CLI, LangChain, LangGraph, Aider i wiele innych) znajdziesz w katalogu [`konfiguracja/`](./konfiguracja/README.md).

### Krok 3: Przykładowe zadania warsztatowe

> 💡 **Gotowe prompty warsztatowe:** Kompletne szablony promptów (zarówno w wersji jednozdaniowej, jak i rozszerzonej technicznej) oraz gotowy System Prompt znajdziesz w katalogu [`prompty/`](./prompty/README.md).

Po sparowaniu klienta AI z Playgroundem możemy wydawać agentowi polecenia w języku naturalnym:

1. **Audyt środowiska:** ([`prompty/01-audyt-srodowiska.md`](./prompty/01-audyt-srodowiska.md))
   > _"Sprawdź jakie wtyczki i motywy są aktywne w tym WordPressie i wyświetl podstawowe informacje o konfiguracji bazy danych."_
2. **Generowanie treści:** ([`prompty/02-generowanie-tresci.md`](./prompty/02-generowanie-tresci.md))
   > _"Stwórz nowy wpis na blogu pod tytułem 'Witaj WordCamp Wrocław 2026', dodaj do niego 3 akapity o przyszłości AI w WordPressie i oznacz kategorią 'Konferencje'."_
3. **Modyfikacja kodu / Sandbox:** ([`prompty/03-modyfikacja-kodu-sandbox.md`](./prompty/03-modyfikacja-kodu-sandbox.md))
   > _"Napisz mini-wtyczkę w katalogu novamira-sandbox, która dodaje powitanie w panelu administracyjnym i przetestuj jej działanie."_
4. **Diagnostyka bazy:** ([`prompty/04-diagnostyka-bazy-danych.md`](./prompty/04-diagnostyka-bazy-danych.md))
   > _"Wylistuj ostatnie 5 wpisów bezpośrednio z bazy danych za pomocą zapytania SQL przez mechanizm novamira."_
5. **Tworzenie i walidacja layoutu z blokami WooCommerce:** ([`prompty/05-tworzenie-i-walidacja-layoutu.md`](./prompty/05-tworzenie-i-walidacja-layoutu.md))
   > _"Na podstawie dokumentacji w pliku dane/BLOCKS-REFERENCE.md wygeneruj stronę główną z sekcją Hero, dwoma kolumnami i kolekcją produktów WooCommerce, a następnie zweryfikuj jej poprawność poprzez walidację layoutu."_

---

## 🔒 Bezpieczeństwo

- Wtyczka Novamira daje agentowi AI **pełne uprawnienia** do wykonywania kodu PHP, bazy danych oraz edycji plików.
- **WordPress Playground to środowisko izolowane (Sandbox):** Wszystkie operacje wykonywane są lokalnie w przeglądarce lub w kontenerze CLI i nie zagrażają danym produkcyjnym.
- Nigdy nie używaj takich uprawnień na serwerach produkcyjnych bez restrykcyjnego uwierzytelniania i bieżących kopii zapasowych!

---

## 📚 Przydatne źródła

- [Repozytorium wtyczki Novamira na GitHubie](https://github.com/use-novamira/novamira) – wtyczka serwera MCP dla WordPressa.
- [Dokumentacja oficjalna Novamira.ai](https://novamira.ai) – oficjalna dokumentacja projektu Novamira.
- [wp-blockmarkup-mcp (Pluginslab)](https://github.com/pluginslab/wp-blockmarkup-mcp) – dedykowany serwer MCP udostępniający agentom AI bazę schematów bloków Gutenberga (Core i WooCommerce).
- [Oficjalna strona WordCamp Wrocław 2026](https://wroclaw.wordcamp.org/) – strona konferencji.

---

## 📱 Kod QR repozytorium

Zeskanuj poniższy kod QR, aby przejść bezpośrednio do tego repozytorium na GitHubie:

<p align="center">
  <a href="https://github.com/damadorPL/warsztat-wordcamp-wroclaw-2026">
    <img src="./qrcode.png" alt="QR Code - Warsztat WordCamp Wrocław 2026" width="220" />
  </a>
  <br />
  <sub><a href="https://github.com/damadorPL/warsztat-wordcamp-wroclaw-2026">https://github.com/damadorPL/warsztat-wordcamp-wroclaw-2026</a></sub>
</p>