Novamira
by damadorPL
README.md
# Warsztat WordCamp Wrocław 2026 – WordPress Playground + Novamira (MCP Server)
[](https://developer.wordpress.org/playground/)
[](https://github.com/use-novamira/novamira)
[](https://woocommerce.com/)
[](https://www.php.net/)
[](https://wordpress.org/)
[](./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>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues