Add WordPress.com REST API support for remote sites in AI command

[youknowriad]

Related issues

• Related to remote site support in the AI command

How AI was used in this PR

AI-assisted implementation. All code reviewed and tested manually.

Proposed Changes

• When a remote WordPress.com site is selected in the AI command, the agent now gets a wpcom_request tool that can call any WordPress.com REST API endpoint, instead of using local Studio tools
• The wpcom_request tool is a generic REST API client — it takes a method, path, query, and body, and the agent determines the right endpoints based on its knowledge of the WordPress REST API
• Defaults to the WordPress REST API (wp/v2) for standard resources (posts, pages, templates, template parts, navigation, global styles, etc.), with fallback to WP.com REST API v1.1 for WP.com-specific endpoints (plugins, theme switching, site settings)
• Local sites continue using WP-CLI and file operations as before (no behavior change)
• System prompt is now fully site-aware with separate content/design guidelines for local vs remote:
  • Local: custom CSS, animations, scroll effects, theme files (unchanged)
  • Remote (free WP.com): informs users that design customizations require a paid plan, documents what's possible on free plans
• The take_screenshot tool is available for remote sites (works with any URL)
• wpcomSiteId is preserved through SiteInfo, prompt enrichment, and session recording
• Includes hints for non-obvious API patterns (e.g., discovering the global styles ID from the active theme's _links)

Testing Instructions

• Select a local site in studio ai → verify it works as before (WP-CLI, file ops, Studio tools)
• Select a remote WordPress.com site → verify the agent uses mcp__studio__wpcom_request and can manage content, templates, and take screenshots
• Ask the agent to modify a block theme template on a remote site → verify it uses wp/v2 endpoints
• Ask the agent for design changes on a free WP.com site → verify it explains the paid plan limitation
• Verify the system prompt documents wp/v2 and v1.1 endpoints when a remote site is active

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 6cf7672 vs trunk

app-size

Metric	trunk	6cf7672	Diff	Change
App Size (Mac)	1252.02 MB	1252.03 MB	+0.01 MB	⚪ 0.0%

site-editor

Metric	trunk	6cf7672	Diff	Change
load	1883 ms	1893 ms	+10 ms	⚪ 0.0%

site-startup

Metric	trunk	6cf7672	Diff	Change
siteCreation	9131 ms	8126 ms	1005 ms	🟢 -11.0%
siteStartup	4165 ms	4169 ms	+4 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[youknowriad]

System prompt is now site-aware: shared design/content guidelines with conditional intro sections for local vs remote workflows

I'm not sure entirely about this, I think this produces better results but there's an alternative where the conditions are expressed with a common system prompt.

[sejas]

Works pretty good in general. I tested it by running npm run cli:build && node apps/cli/dist/cli/main.mjs ai

I left a comment about the mismatch where the title and description mention https://public-api.wordpress.com/wpcom/v2/mcp/v1, but it seems we’ve actually built a custom MCP for dotcom inside Studio AI.

For some reason listing plugins and themes didn't work. I tried them with a couple of sites. Get site info worked although it said Error: result (96,079 characters) exceeds maximum allowed tokens. and used a file to split the response.

The screenshot action worked good.

[sejas]

The PR title and description say this PR connects to the WP.com MCP server https://public-api.wordpress.com/wpcom/v2/mcp/v1

Use WP.com MCP for remote WordPress.com sites in AI command

• When a remote WordPress.com site is selected in the AI command, the agent now connects to the WP.com MCP server (https://public-api.wordpress.com/wpcom/v2/mcp/v1) via HTTP transport with Bearer auth, instead of using local Studio tools

But apps/cli/ai/wpcom-tools.ts actually wraps direct WP.com REST API calls (wpcomFactory → /sites/{id}/posts, /plugins, etc.) inside a local SDK MCP server. The agent sees MCP tools implemented locally through REST endpoints.

Should we update the title and description to match the actual code, or try to use https://wordpress.com/me/mcp if possible?

[youknowriad]

I started with the MCP but it was way too limiting IMO so I switched to a custom MCP over the REST API which achieves better results. (I updated the PR description and title)

Error: result (96,079 characters) exceeds maximum allowed tokens.

I also had this error multiple times, I think our proxy endpoint is imposing extra limits on top of what the LLMS impose. My thinking is that we should track this in its own ticket, either remove that limitation entirely (defer to the llm) or override it somehow.

[mtias]

I've run into that too while working on the Figma connection.

[sejas]

Error: result (96,079 characters) exceeds maximum allowed tokens.

I also had this error multiple times, I think our proxy endpoint is imposing extra limits on top of what the LLMS impose. My thinking is that we should track this in its own ticket, either remove that limitation entirely (defer to the llm) or override it somehow.

I created a separate issue STU-1524

[lezama]

Hey Riad! I was testing the remote site flow and noticed the plan check (GET / on v1.1) returns ~103K chars which exceeds the agent's token limit — it spills to a file and the agent has to grep through it.

I pushed a small commit (ff2e207b) that adds a wpcom_site_info tool which requests only fields=ID,name,description,URL,plan, keeping the response compact. The system prompt now points to it as the mandatory first step.

Happy to revert if you'd prefer a different approach — just wanted to share what I found while testing. 🙂

[epeicher]

Hi @youknowriad, @lezama, after the latest changes in commit ff2e207 I was still getting errors due to the big size of the plan field returned by the GET v1.1/sites/<siteId>?fields=ID,name,description,URL,plan so I have created a PR based on this branch #3005 that can be merged to this branch if required (or to trunk when this one is merged) which is based on those changes. I am not getting the error anymore:

Before	After

[youknowriad]

Hey Riad! I was testing the remote site flow and noticed the plan check (GET / on v1.1) returns ~103K chars which exceeds the agent's token limit — it spills to a file and the agent has to grep through it.

See the discussion here #2992 (comment) The token limit is a broader issue that is not specific to a given endpoint. I'm not sure adding a tool for each endpoint is the right call. So It seems the best path is to avoid this tool and try to find a generic solution like maybe @epeicher's approach could work here.

[youknowriad]

I reverted that commit for now, should we try to land this PR while we work on the token limit fix? Any approval?

[sejas]

The plan sounds good. I'm taking a final look.

[epeicher]

Thanks for the changes @youknowriad! I have tested it, and it works as expected, I have verified:

• Select a local site in studio ai → verify it works as before (WP-CLI, file ops, Studio tools)
• Select a remote WordPress.com site → verify the agent uses mcp__studio__wpcom_request and can manage content, templates, and take screenshots
• Ask the agent to modify a block theme template on a remote site → verify it uses wp/v2 endpoints
• Ask the agent for design changes on a free WP.com site → verify it explains the paid plan limitation
• Verify the system prompt documents wp/v2 and v1.1 endpoints when a remote site is active

Session

[sejas]

Looks good. Thanks for creating the WPCOM REST API MCP. Everything worked quite good.
I see sometimes the agent uses the wrong API namespace, but it recovers by trying another one. See the /plugins example. I'll create a follow-up issue to improve the buildRemoteIntro system prompt or tools definition to be more specific.

[youknowriad]

There's a balance to be found between building specific tools and keeping the number of tools very small which makes the agent efficient. I think what could work well, is a tool to discover the right endpoint, and a tool to call the endpoint (to avoid having to specify every tool in the system prompt)