Skip to content

Adding reference to webMCP at Playground Skill - #105

Merged
bgrgicak merged 16 commits into
trunkfrom
adding-refence-to-webmcp
Sep 23, 2026
Merged

bgrgicak merged 16 commits into
trunkfrom
adding-refence-to-webmcp

Conversation

@fellyph

@fellyph fellyph commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Updates the wp-playground skill to prefer WebMCP site tools for supported browser operations when they are available.

The skill still respects an explicitly requested connection method and falls back to Playground MCP or browser APIs when WebMCP is unavailable or does not expose the required operation.

Changes

  • Adds WebMCP site tools to the wp-playground routing guidance.
  • Documents how agents should discover and inspect available WebMCP tools.
  • Clarifies that WebMCP does not require the local Playground MCP server, WebSocket bridge, or mcp=yes.
  • Preserves the active Playground site when switching between connection methods.
  • Adds representative WebMCP tools for site management, PHP execution, requests, navigation, and filesystem operations.
  • Documents Playground MCP and browser API fallback behavior.
  • Adds evaluation scenarios covering:
    • WebMCP and Playground MCP both being available.
    • WebMCP being unavailable.
    • The user explicitly requesting Playground MCP.
    • WebMCP missing a required operation.

Expected behavior

When working with an open WordPress Playground site, agents should:

  1. Respect any connection method explicitly requested by the user.
  2. Otherwise, discover and prefer WebMCP tools for supported operations.
  3. Inspect the discovered tool descriptions and schemas before calling them.
  4. Fall back to Playground MCP or browser APIs when necessary.
  5. Verify that changes were applied to the intended active site.

Testing

  • Ran node eval/harness/run.mjs.
  • Validated all new evaluation scenario JSON files and required fields.
  • Ran git diff --check.

All checks passed.

Reference

WordPress Playground and WebMCP: bringing AI agents into your browser workflow

Add WebMCP site tools to the wp-playground routing surface. Prefer available WebMCP tools for supported browser operations while preserving explicit connection choices and MCP or browser API fallbacks.
Explain how agents should discover and prefer WebMCP site tools, distinguish WebMCP from the Playground MCP bridge, and preserve the active site when falling back. Add representative tool groups, browser API fallback guidance, and connection verification requirements.
Add an evaluation scenario where WebMCP and Playground MCP are both available. Require the agent to choose WebMCP, inspect discovered schemas, verify the target site, and preserve active browser state.
Add an evaluation scenario for browser sessions that expose no callable WebMCP tools. Require reuse of the existing Playground MCP connection without replacing or reloading the active site.
Add an evaluation scenario confirming that an explicit request for Playground MCP overrides the default WebMCP preference. Require schema inspection, target-site confirmation, and state verification.
Add an evaluation scenario where WebMCP can list sites but cannot switch them. Require WebMCP for supported discovery and the site-manager browser API only for the missing operation, followed by active-site verification.
@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: fellyph <fellyph@git.wordpress.org>
Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@fellyph fellyph changed the title Adding refence to webmcp Adding reference to webMCP at Playground Skill Sep 18, 2026
@bgrgicak
bgrgicak requested a review from a team September 22, 2026 05:09
Comment on lines +49 to +55
| Share a quick reviewer/demo site | Build a `https://playground.wordpress.net/?...` URL with Query API parameters. |
| Share a multi-step setup | Use the `blueprint` skill to create/review the Blueprint, then pass it as a URL fragment or `?blueprint-url=`. |
| Create a blank temporary site from the browser | Open `playground.wordpress.net`, then call `playgroundSites.createNewTemporarySite()`. |
| Keep a temporary site after reload | Call `playgroundSites.saveInBrowser()` for OPFS persistence. |
| Switch between saved browser sites | Call `playgroundSites.list()` and `playgroundSites.setActiveSite(slug)`. |
| Keep a temporary site after reload | Prefer the discovered `playground_save_in_browser` tool; otherwise call `playgroundSites.saveInBrowser()` for OPFS persistence. |
| Switch between saved browser sites | Prefer `playground_list_sites` for discovery; use `playgroundSites.setActiveSite(slug)` to switch if no discovered tool supports switching. Fall back to `playgroundSites.list()` for discovery. |
| Change PHP version or networking on an existing saved site | Save it first, then call `setPhpVersion()` or `setNetworking()`. |
| Inspect or modify WordPress files/content | Get the active client with `playgroundSites.getClient()` or `window.playground`, then use client file/PHP/request methods. |
| Inspect or modify WordPress files/content | Prefer discovered WebMCP file/PHP/request tools. Otherwise use available Playground MCP tools or get the active client with `playgroundSites.getClient()` or `window.playground` and use its file/PHP/request methods. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These instructions are for the sites API, we shouldn't mix Site API and WebMCP instuctions


WebMCP exposes tools through the open webpage. It does not require the local Playground MCP server, its WebSocket bridge, or `mcp=yes`. Those belong to the separate Playground MCP connection path; do not recommend that setup as a prerequisite for WebMCP. Keep URL/Blueprint setup and local CLI workflows routed according to the task.

Examples to look for during discovery include:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of mixing connection method instructions and WebMCP instructions, can we split WebMCP into a separata section similartly to Manage browser sites with window.playgroundSites and Create or open a site with a URL.

## Working model for agents

`playground.wordpress.net` gives the agent three useful control surfaces:
### Choose the connection method

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We now have Decide what to do and Choose the connection method can we have only one section?

@bgrgicak

Copy link
Copy Markdown
Contributor

Thanks for adding WebMCP instructions! I agree with the suggested approach of making WebMCP the default for the Playground website.

This PR surfaces one issue with the website reference, it's a mess due to all the ways agents can interact with the website.
We should clearly split the information into sections and not mix different approaches like WebMCP and Sites API.
Ideally, the website.md file would become a setup (Query API, Blueprints) + router file that points to separate reference files for Sites API, MCP, and WebMCP so we avoid confusing the model with various options.

@bgrgicak
bgrgicak requested a review from a team September 22, 2026 05:43
@fellyph

fellyph commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

Addressed the reference organization feedback in #105 (comment) with one commit per changed file.

  • website.md now covers Query API and Blueprint URL setup, browser limitations, and routing to the appropriate interaction reference.
  • Added separate webmcp.md, mcp.md, and sites-api.md references, each with its own operational and verification guidance.
  • Updated SKILL.md to direct agents through that router and load only the selected method. WebMCP remains the default for supported operations, explicit user choices take precedence, and fallbacks preserve the intended site.
  • Updated five evaluation scenarios to cover focused reference loading for WebMCP, explicit MCP, fallback operations, and share URL setup.

Validation: the repository harness (node eval/harness/run.mjs), scenario JSON/required-field checks, local reference link/anchor checks, and git diff --check passed. The generic skill validator rejects the existing compatibility frontmatter field, which the repository validator requires; that field is unchanged. These checks validate structure, not live browser execution of the scenarios.

The ten commits run from a2f60b6 through 7cf819f and are pushed to this PR.

@bgrgicak bgrgicak left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for splitting website.md into separate references!

@bgrgicak
bgrgicak merged commit e9c58d5 into trunk Sep 23, 2026
4 checks passed
@bgrgicak
bgrgicak deleted the adding-refence-to-webmcp branch September 23, 2026 05:35
henryperkins added a commit to henryperkins/agent-skills that referenced this pull request Sep 27, 2026
… security

Merges the six commits WordPress/agent-skills trunk was ahead by:

- ac16175 Add wp-env skill for local WordPress development (WordPress#38)
- ad58e37 Add plugin security guidance for escaping and AJAX (WordPress#63)
- f2f6af2 Fix Plugin/Theme header detection in PHP docblocks (WordPress#103)
- e9c58d5 Adding reference to webMCP at Playground Skill (WordPress#105)
- 9f4a603 chore: refresh upstream indices (WordPress#92)
- f1bac1f Add repository-wide CODEOWNERS for agent-skills maintainers (WordPress#108)

Conflict resolutions:

shared/references/wordpress-core-versions.json
  Kept ours. api.wordpress.org/core/version-check/1.7 reports 7.1.2
  (checked 2026-09-27); upstream's WordPress#92 snapshot stops at 7.1.1. The
  Gutenberg index merged cleanly: both sides already carry v24.0.0, and
  v24.1.0 is still at rc.1.

skills/wp-project-triage/scripts/detect_wp_project.mjs
  Kept ours. The fork already fixed WordPress#103's bug with `^[\s*#]*`, which
  matches every header line upstream's `^\s*\*?\s*` does, plus `#`-led
  lines. The detect_plugins.mjs half of WordPress#103 merged cleanly; the fork had
  not fixed that file. Both detectors now report docblock, bare, and
  non-plugin fixtures correctly.

skills/wp-playground/SKILL.md
  Kept the fork's frontmatter (Use-when opener, 6.9 floor, GPL license)
  and folded WordPress#105's "WebMCP site tools" into the description. Took WordPress#105's
  browser-workflow routing bullet in the fork's markdown-link style; it
  also drops the "Blueprint Editor" claim, which website.md never covered.

Clean merges: website.md now routes existing-site work to the new
webmcp.md, mcp.md, and sites-api.md references (the WebMCP tool names
match packages/playground/mcp in WordPress/wordpress-playground);
security.md gains escaping contexts and AJAX handler rules. wp-env
arrives exactly as upstream wrote it and is conformed and corrected in
the next commit. CODEOWNERS names @WordPress/agent-skills-maintainers,
which does not resolve in this fork; kept for tree parity with upstream.

The harness is not expected to pass at this commit: wp-env is not yet in
the skill inventory and skills/ changed without a version bump. The
follow-up commits close both.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
henryperkins added a commit to henryperkins/agent-skills that referenced this pull request Sep 27, 2026
…16.0 and route to it

Upstream's wp-env skill (WordPress#38) follows the @wordpress/env README, which
lags the package code in several places. Checked against the 11.16.0
tarball (published 2026-09-23) and, where behavior mattered, run:

- `composer` is not a `wp-env run` container. The package removed it
  (and `phpunit`), and validate-run-container.js throws on both. The
  list is now mysql, wordpress, cli, phpmyadmin (only when enabled), plus
  the tests-* containers.
- `wp-env run cli "wp rewrite structure /%postname%/"` fails. run()
  hands argv to `docker compose exec` with no shell, so the quoted string
  is looked up as one executable name ("executable file not found in
  $PATH", reproduced with docker exec). The command is now unquoted, with
  a short explanation.
- `wp-env run mysql mysql ...` fails: the database service is
  mariadb:lts (12.3.3 today), which ships `mariadb` and no `mysql`.
- `npx wp-env` resolves the unscoped `wp-env` npm package when the local
  install is missing (a third-party "Security PoC" package), and npm
  assumes --yes in a non-interactive shell. Replaced with the README's
  own `npm exec --no -- wp-env`.
- `cleanup` and `destroy` block on a confirmation prompt unless
  `--force`; the skill now says to get the user's go-ahead and pass it.
- Override files merge `config`, `mappings`, and `lifecycleScripts`
  (merge-configs.js), not only the first two.
- The invalid-source error is `Invalid or unrecognized source: "<value>"`,
  and a relative path without a leading `.` is parsed as a GitHub repo.
- The tests environment still starts by default on 8889 but is
  deprecated with a startup warning; the skill names the
  `"testsEnvironment": false` opt-out and the `--config` replacement.
- `--auto-port` is ignored when CI is set.

Fork conventions: the 6.9 floor per docs/compatibility-policy.md (wp-env
covers no 7.0-only API), the license field, a wp-playground boundary in
the description, and "verified against @wordpress/env 11.16.0" in prose.
@wordpress/env is not a drift-registry upstream, so it carries no
`verified through:` marker.

Registration: docs/skill-set-v1.md lists 22 skills. The router sends
wp-env / .wp-env.json requests to wp-env (upstream still routes wp-env
to the planned wp-testing skill) and WordPress#105's WebMCP / Playground MCP
terms to wp-playground's website.md. wp-playground's escalation now
names the wp-env skill.

assertWpEnvPrecision pins the corrections and the fork-only router
entry. It fails on upstream's original SKILL.md, and each of its six
exclusions matches a line in that original.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
henryperkins added a commit to henryperkins/agent-skills that referenced this pull request Sep 27, 2026
Ships the upstream merge and the corrections that followed it: the new
wp-env skill (upstream WordPress#38), checked against @wordpress/env 11.16.0 and
routed from wordpress-router; WebMCP, Playground MCP, and Sites API
routing for wp-playground (WordPress#105); plugin escaping and AJAX guidance (WordPress#63);
and the docblock plugin-header fix in detect_plugins.mjs (WordPress#103).

The release-conformance gate requires a bump whenever skills/ changes after
the last version change, and nine skill files changed since 1.11.0. A new
skill makes this a minor release. The manifests now list wp-env.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants