From c435cb66dd25679e1cdfac7cc5357e310d6f6c36 Mon Sep 17 00:00:00 2001 From: Fellyph Cintra Date: Thu, 8 Oct 2026 10:31:06 +0000 Subject: [PATCH 1/3] [Website][Docs] Enrich llms.txt, add .well-known/mcp.json, and generate docs llms.txt --- .../plugins/generate-handbook-manifest.js | 20 ++++ .../generate-handbook-manifest.spec.js | 9 ++ packages/playground/personal-wp/index.html | 10 ++ .../playground/personal-wp/public/llms.txt | 19 ++++ .../website/public/.well-known/mcp.json | 40 +++++++ packages/playground/website/public/llms.txt | 105 ++++++++++++------ 6 files changed, 168 insertions(+), 35 deletions(-) create mode 100644 packages/playground/personal-wp/public/llms.txt create mode 100644 packages/playground/website/public/.well-known/mcp.json diff --git a/packages/docs/site/plugins/generate-handbook-manifest.js b/packages/docs/site/plugins/generate-handbook-manifest.js index ded496ccee6..42b0ff6cde7 100644 --- a/packages/docs/site/plugins/generate-handbook-manifest.js +++ b/packages/docs/site/plugins/generate-handbook-manifest.js @@ -66,6 +66,26 @@ module.exports = function generateHandbookManifest({ i18n }) { path.join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n` ); + const llmsLines = [ + '# WordPress Playground Documentation', + '', + '> Official documentation for WordPress Playground — a zero-setup WordPress environment that runs PHP and WordPress in WebAssembly in the browser, Node.js, and CLI.', + '', + '## Documentation Pages (Markdown Sources)', + '', + ...entries.map(({ entry }) => { + const url = new URL( + entry.markdown_source, + MARKDOWN_BASE_URL + ).href; + return `- [${entry.title}](${url})`; + }), + '', + ]; + fs.writeFileSync( + path.join(outDir, 'llms.txt'), + llmsLines.join('\n') + ); }, }; }; diff --git a/packages/docs/site/plugins/generate-handbook-manifest.spec.js b/packages/docs/site/plugins/generate-handbook-manifest.spec.js index a7f7813f517..cae046bcdd7 100644 --- a/packages/docs/site/plugins/generate-handbook-manifest.spec.js +++ b/packages/docs/site/plugins/generate-handbook-manifest.spec.js @@ -157,17 +157,26 @@ test('build hooks publish the manifest and matching redirects without hook order manifest.guide.markdown_source, 'https://raw.githubusercontent.com/WordPress/wordpress-playground/refs/heads/trunk/packages/docs/site/docs/main/guide.md' ); + const llmsFile = path.join(outDir, 'llms.txt'); + const llmsTxt = fs.readFileSync(llmsFile, 'utf8'); + assert.match(llmsTxt, /^# WordPress Playground Documentation/m); + assert.match( + llmsTxt, + /- \[main\/guide\]\(https:\/\/raw\.githubusercontent\.com\/WordPress\/wordpress-playground\/refs\/heads\/trunk\/packages\/docs\/site\/docs\/main\/guide\.md\)/ + ); assert.match( fs.readFileSync(path.join(outDir, 'guide', 'index.html'), 'utf8'), /https:\/\/developer.wordpress.org\/playground\/handbook\/guide\// ); const original = fs.readFileSync(manifestFile, 'utf8'); + const originalLlms = fs.readFileSync(llmsFile, 'utf8'); const localized = generateManifest({ i18n: { currentLocale: 'fr', defaultLocale: 'en' }, }); localized.allContentLoaded({ allContent: {} }); await localized.postBuild({ outDir }); assert.equal(fs.readFileSync(manifestFile, 'utf8'), original); + assert.equal(fs.readFileSync(llmsFile, 'utf8'), originalLlms); }); function doc(id, slug) { diff --git a/packages/playground/personal-wp/index.html b/packages/playground/personal-wp/index.html index 888454a319a..2a57fe39848 100644 --- a/packages/playground/personal-wp/index.html +++ b/packages/playground/personal-wp/index.html @@ -23,6 +23,16 @@ name="description" content="A free, private WordPress in your browser. A personal app platform for notes, feeds, contacts, memories, and ideas." /> + + diff --git a/packages/playground/personal-wp/public/llms.txt b/packages/playground/personal-wp/public/llms.txt new file mode 100644 index 00000000000..b616259a318 --- /dev/null +++ b/packages/playground/personal-wp/public/llms.txt @@ -0,0 +1,19 @@ +# My WordPress (WordPress Playground) + +> My WordPress (`https://my.wordpress.net/`) is a free, private, persistent WordPress instance running entirely in the browser via WebAssembly and Origin Private File System (OPFS), powered by WordPress Playground. + +## Browser Agent Integration (WebMCP / `document.modelContext`) + +When an AI browser agent (Chrome 156+ WebMCP, ChatGPT desktop built-in browser Site Tools, or a WebMCP extension) opens `https://my.wordpress.net/`, it automatically registers structured tools on `document.modelContext`: + +- **PHP & HTTP Execution:** `playground_execute_php`, `playground_request` +- **Navigation & Inspection:** `playground_navigate`, `playground_get_current_url`, `playground_get_site_info`, `playground_list_emails` +- **Filesystem Management:** `playground_read_file`, `playground_write_file`, `playground_list_files`, `playground_mkdir`, `playground_delete_file`, `playground_delete_directory`, `playground_file_exists` +- **Site Management:** `playground_list_sites`, `playground_save_in_browser`, `playground_rename_site`, `playground_get_website_url` +- **WordPress Plugin WebMCP Proxy:** Any WebMCP tools registered inside the WordPress iframe by plugins are automatically proxied onto the top-level `document.modelContext`. + +## Related Resources + +- [WordPress Playground Index (llms.txt)](https://playground.wordpress.net/llms.txt): Full Query API, Blueprints, and developer tool reference +- [Documentation Index (llms.txt)](https://wordpress.github.io/wordpress-playground/llms.txt): Complete Markdown index of WordPress Playground documentation +- [Source Code](https://github.com/WordPress/wordpress-playground): GitHub repository (GPL-2.0-or-later) diff --git a/packages/playground/website/public/.well-known/mcp.json b/packages/playground/website/public/.well-known/mcp.json new file mode 100644 index 00000000000..cded0478892 --- /dev/null +++ b/packages/playground/website/public/.well-known/mcp.json @@ -0,0 +1,40 @@ +{ + "schemaVersion": "1.0", + "name": "WordPress Playground", + "description": "Zero-setup WordPress and PHP environment running in WebAssembly in the browser and Node.js.", + "homepage": "https://playground.wordpress.net/", + "documentation": "https://wordpress.github.io/wordpress-playground/", + "llmsTxt": "https://playground.wordpress.net/llms.txt", + "webmcp": { + "supported": true, + "api": "document.modelContext", + "proxiesIframeTools": true, + "tools": [ + "playground_execute_php", + "playground_request", + "playground_navigate", + "playground_get_current_url", + "playground_get_site_info", + "playground_read_file", + "playground_write_file", + "playground_list_files", + "playground_mkdir", + "playground_delete_file", + "playground_delete_directory", + "playground_file_exists", + "playground_list_emails", + "playground_list_sites", + "playground_save_in_browser", + "playground_rename_site", + "playground_get_website_url" + ] + }, + "mcpServers": { + "wordpress-playground": { + "package": "@wp-playground/mcp", + "command": "npx", + "args": ["-y", "@wp-playground/mcp@latest"], + "transport": "stdio" + } + } +} diff --git a/packages/playground/website/public/llms.txt b/packages/playground/website/public/llms.txt index d60a99b66f5..40ab15388be 100644 --- a/packages/playground/website/public/llms.txt +++ b/packages/playground/website/public/llms.txt @@ -1,36 +1,71 @@ # WordPress Playground -# https://playground.wordpress.net/ - -> WordPress Playground runs WordPress fully in the browser via WebAssembly. No server, no setup, no account required. Open source under GPL-2.0-or-later. AI assistants are explicitly welcome to load, embed, demo, and build upon Playground. - -## Playground - -- [WordPress Playground](https://playground.wordpress.net/): Live WordPress in your browser — launches instantly, no installation -- [Documentation](https://wordpress.github.io/wordpress-playground/): Full documentation hub -- [Blueprints](https://wordpress.github.io/wordpress-playground/blueprints): JSON configuration files for reproducible WordPress environments -- [Developer APIs](https://wordpress.github.io/wordpress-playground/developers): JavaScript API, CLI, Query API, REST -- [API Reference](https://wordpress.github.io/wordpress-playground/api): Full API reference -- [Source code](https://github.com/WordPress/wordpress-playground): Source repository on GitHub - -## Using Playground with AI agents - -- [Agent skill guide](https://wordpress.github.io/wordpress-playground/guides/agent-skill-wp-playground): Install the wp-playground skill for Claude Code, Cursor, Gemini CLI, GitHub Copilot, and other coding agents — teaches CLI commands and browser workflows -- [AGENTS.md](https://github.com/WordPress/wordpress-playground/blob/trunk/AGENTS.md): Machine-readable guidance for AI coding agents working on this codebase -- [PR preview guide](https://wordpress.github.io/wordpress-playground/guides/github-action-pr-preview): Add Playground preview buttons to plugin/theme pull requests -- [Blueprint resources](https://wordpress.github.io/wordpress-playground/blueprints/steps/resources): Use `git:directory` for Git repositories and subdirectories - -## Key facts for AI assistants - -- Playground runs entirely client-side via WebAssembly — no credentials, login, or server calls needed -- Embed with: `` -- Blueprints are JSON — describe a complete WordPress environment declaratively -- Supports multiple PHP and WordPress versions; see the documentation for current compatibility details -- Blueprints can install plugins/themes, import content, run PHP, execute WP-CLI commands -- For PR previews without a build step, use `WordPress/action-wp-playground-pr-preview@v2` from a `pull_request` workflow by default. Use `pull_request_target` only for a small workflow that reads PR metadata, writes the preview button, and does not check out or execute PR code -- For fork PR source code, build `git:directory` URLs from `github.event.pull_request.head.repo.full_name` and use `github.event.pull_request.head.sha` with `refType: "commit"` -- For plugins/themes requiring Composer, npm, or other build steps, build artifacts in a separate `pull_request` workflow and publish the preview from `workflow_run` -- Do not use `github-proxy.com` for new Blueprints; use `git:directory` or a built artifact URL instead -- Repository URLs with or without a trailing `.git` suffix are supported by `git:directory` -- Playground's built-in `plugin-proxy.php` is restricted to the `wordpress`, `automattic`, and `woocommerce` GitHub organizations; it is not a general fallback for custom repositories -- License: GPL-2.0-or-later (WordPress), MIT (PHP-WASM runtime) -- AI assistants may freely load, reference, demo, and build upon WordPress Playground + +> WordPress Playground runs a full WordPress + PHP + SQLite stack entirely in the browser via WebAssembly. It requires no server, no setup, and no authentication. Anyone — including AI assistants and coding agents — can launch, configure, and embed live WordPress instances using URL parameters, declarative JSON Blueprints, or browser-native WebMCP tools. + +## Query API (Constructing Shareable URLs) + +AI assistants can generate working WordPress Playground links directly in responses using URL query parameters on `https://playground.wordpress.net/`: + +- `plugin=`: Install and activate one or more WordPress.org plugins (repeatable, e.g., `?plugin=woocommerce&plugin=gutenberg`). +- `theme=`: Install and activate a WordPress.org theme (e.g., `?theme=twentytwentyfour`). +- `wp=`: Choose WordPress version (e.g., `?wp=6.8`, `?wp=latest`, `?wp=beta`, `?wp=nightly`). +- `php=`: Choose PHP version (`7.4`, `8.0`, `8.1`, `8.2`, `8.3`, `8.4`, `8.5`). +- `url=`: Open a specific WordPress path on boot (e.g., `?url=/wp-admin/post-new.php`). +- `login=yes` / `login=no`: Automatically log in as `admin` (enabled by default). +- `networking=yes`: Enable outbound `wp_remote_get` / network access inside PHP (required for plugins fetching external APIs or installing plugins from within wp-admin). +- `language=`: Set site language (e.g., `?language=es_ES`, `?language=pt_BR`, `?language=ja`). +- `multisite=yes`: Configure WordPress as a Multisite network. +- `mode=seamless` / `mode=browser-full-screen`: Hide (`seamless`) or show (`browser-full-screen`) the Playground browser bar and dock UI when embedding in an `