@respira/wordpress-mcp-server 8.3.5 → 8.3.7

package/dist/server.js

@@ -2350,7 +2350,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_create_theme_builder_template',
-                description: 'Create a Divi global header, footer, or body Theme Builder template, with optional page assignments. Snapshot-protected (reversible within a session). Pass structure as a Divi 4 shortcode string, or a Divi 5 block/node array. Works on Divi 4 and Divi 5.',
+                description: 'Create a Divi global header, footer, or body Theme Builder template. WHERE IT APPLIES IS NEVER GUESSED: omit `assignments` and the template is created UNASSIGNED, so nothing on the site renders it until someone assigns it (in Divi > Theme Builder, or by re-sending with assignments). Site-wide happens only when you pass {"all_pages": true}, and if that would fill an empty slot on the site\'s existing default Theme Builder template the first call is refused with respira_tb_default_slot_confirmation_required until you re-send with confirm_live_edit=true. The response states `scope` (unassigned / conditional / site_wide) and returns rollback.snapshot_uuid for restore_snapshot. Pass structure as a Divi 4 shortcode string, or a Divi 5 block/node array. Works on Divi 4 and Divi 5.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2358,9 +2358,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         name: { type: 'string', description: 'Template name.' },
                         assignments: {
                             type: 'object',
-                            description: 'Where it applies. {"all_pages": true} for site-wide, or {"post_types": ["page"], "excluded_ids": [12, 34]}.',
+                            description: 'Where it applies. Omit for unassigned (safe: renders nowhere). {"all_pages": true} for site-wide. {"post_types": ["page"], "excluded_ids": [12, 34]} for conditional. Those three keys are the whole vocabulary; anything else is refused by name. Divi\'s Theme Builder UI also supports taxonomy and post-type archive conditions, author/date/search archives and singular ids, which this tool cannot express yet: set those by hand in Divi > Theme Builder, then fill the layout with wordpress_update_theme_builder_template using the layout_id from wordpress_list_theme_builder_templates.',
                         },
                         structure: { description: 'Divi 4 shortcode string, or a Divi 5 block/node array.' },
+                        confirm_live_edit: {
+                            type: 'boolean',
+                            description: 'Only needed for a site-wide assignment that fills an empty slot on the site\'s existing default Theme Builder template. Set true to acknowledge that every page on the site starts rendering this layout immediately (for kind "body", instead of its own content). Tell the user what is about to change before setting it.',
+                        },
                     },
                     required: ['kind', 'name'],
                 },
@@ -2521,7 +2525,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_delete_post',
-                description: 'Delete a post. IMPORTANT: By default, this only works on Respira-created duplicates. The force parameter only works if "Allow Direct Editing" is enabled in Respira settings (disabled by default for safety).\n\nApproval flow: destructive — the first call may return `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to complete the delete.',
+                description: 'Delete a post. IMPORTANT: By default, this only works on Respira-created duplicates. To delete an original: pass `force=true` AND `confirm_live_edit=true`. The "Allow Direct Editing" setting in Respira must also be enabled (disabled by default for safety).\n\nApproval flow: destructive — the FIRST call returns `code: respira_approval_required` with `data.approval_request.approval_token`, and deletes nothing. Pass that exact token back via the `approval_token` param on the next call to complete the delete. Deleting a Respira-created duplicate still takes both calls; the approval gate runs before the duplicate check.\n\nFixed in 8.3.7 (ticket 429299b5): this tool used to discard the response body, so the approval token, the refusal reason and the success flag were all invisible and every call looked like an empty response. It now always returns the site\'s answer.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2531,11 +2535,15 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                         force: {
                             type: 'boolean',
-                            description: 'Force delete even if not a duplicate',
+                            description: 'Force delete even if not a duplicate. Requires confirm_live_edit=true.',
+                        },
+                        confirm_live_edit: {
+                            type: 'boolean',
+                            description: 'Operator confirmation that a force-delete of an original post is intended. The plugin has always required this alongside force=true; before 8.3.7 the delete_post schema did not expose it, and the error asking for it was thrown away with the rest of the response body.',
                         },
                         approval_token: {
                             type: 'string',
-                            description: 'One-time token from a prior respira_approval_required response. Omit on the first call; the tool will reject with a token if approval is required, then re-call with this parameter set to that token to confirm and execute.',
+                            description: 'Approval token from a prior respira_approval_required response (data.approval_request.approval_token). Omit on the first call; re-call with this parameter set to that exact token to confirm and execute. The token is bound to this tool and expires after 10 minutes.',
                         },
                     },
                     required: ['id'],
@@ -3514,7 +3522,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                                 properties: {
                                     identifier: {
                                         type: 'object',
-                                        description: 'Element identifier. Provide exactly one of id / admin_label / path / type. match_content disambiguates duplicates of the same type.',
+                                        description: 'Element identifier. Provide exactly one of id / admin_label / path / type. match_content disambiguates duplicates of the same type. `path` accepts both dialects: the index form respira_find_element emits ("1.0.1") and the key-interleaved form ("1.children.0.children.1"). They name the same element.',
                                         properties: {
                                             id: { type: 'string', description: 'Builder element ID (Divi 5 _nodeId, Elementor element id, Bricks id, etc).' },
                                             admin_label: { type: 'string', description: 'Admin label / navigator label.' },
@@ -7576,6 +7584,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     name: args.name,
                     assignments: args.assignments ?? null,
                     structure: args.structure ?? null,
+                    // Same three spellings the plugin normalises for the update tool.
+                    confirm_live_edit: args.confirm_live_edit ?? args.confirmLiveEdit ?? args.confirmed,
                 });
             case 'wordpress_update_theme_builder_template':
                 return await client.updateThemeBuilderTemplate({
@@ -7616,7 +7626,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 };
             }
             case 'wordpress_delete_post':
-                return await client.deletePost(args.id, args.force, args.approval_token);
+                // Ticket 429299b5: `deletePost` used to be `Promise<void>`, so this
+                // `return` handed `undefined` to withSiteContext and the agent got a
+                // bare `{"site":{...}}` — approval token, refusal reason and success
+                // flag all thrown away. The client now returns the plugin body.
+                return await client.deletePost(args.id, args.force, args.approval_token, args.confirm_live_edit);
             case 'wordpress_list_media':
                 return await client.listMedia(args);
             case 'wordpress_upload_media': {
@@ -7996,7 +8010,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_update_media_batch':
                 return await client.updateMediaBatch(args.items);
             case 'wordpress_delete_media':
-                return await client.deleteMedia(args.id);
+                // Ticket 429299b5 (second defect): this line used to be
+                // `client.deleteMedia(args.id)`. The schema advertises `force` and
+                // `approval_token`, the client method forwards both, but the token
+                // died here — so the plugin saw a fresh first call every time and
+                // minted a new token forever. Ticket 927aa7ed fixed the client method
+                // and tested the client method; the dispatcher was the broken link.
+                return await client.deleteMedia(args.id, args.force, args.approval_token);
             // Menu Management
             case 'wordpress_list_menus':
                 return await client.listMenus();
@@ -8580,13 +8600,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         post_id: { type: 'number', description: 'Page/post ID' },
                         identifier_type: {
                             type: 'string',
-                            description: 'How to find the element',
-                            enum: ['id', 'type', 'class', 'content', 'uncode_shortcode_id'],
+                            description: 'How to find the element. "path" takes an index path such as "1.0.1" (the `path_string` this tool returns) and names exactly one element.',
+                            enum: ['id', 'type', 'admin_label', 'class', 'content', 'text', 'path', 'uncode_shortcode_id'],
                         },
                         identifier_value: { type: 'string', description: 'Value to search for' },
                         match_content: {
                             type: 'string',
-                            description: 'Optional text content to narrow results when searching by type/class',
+                            description: 'Optional text to narrow the result set to elements whose own text or attribute values contain it. Works for every identifier_type. It separates siblings; it cannot separate an element from an ancestor that contains it, so use identifier_type "path" when you need certainty.',
                         },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value'],
@@ -8602,7 +8622,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         post_id: { type: 'number', description: 'Page/post ID' },
                         identifier_type: {
                             type: 'string',
-                            enum: ['id', 'type', 'class', 'content', 'uncode_shortcode_id'],
+                            enum: ['id', 'type', 'admin_label', 'class', 'content', 'text', 'path', 'uncode_shortcode_id'],
+                            description: 'How to locate the element. Accepts everything respira_find_element accepts, so any identifier it returns works here as-is. "path" takes a find_element `path_string` (e.g. "1.0.1"), names exactly one element, and is the reliable answer to a 422 respira_ambiguous_target.',
                         },
                         identifier_value: { type: 'string', description: 'Value to match' },
                         updates: {
@@ -8616,6 +8637,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                                 },
                             },
                         },
+                        match_content: {
+                            type: 'string',
+                            description: 'Narrows a set of elements sharing identifier_type/identifier_value down to the ones whose own text or attribute values contain this string (e.g. two buttons of the same type, one saying "Buy"). It separates siblings; it cannot separate an element from an ancestor, since an ancestor contains its children\'s text. For that case use identifier_type "path".',
+                        },
                         edit_target: {
                             type: 'string',
                             enum: ['live', 'duplicate'],
@@ -8633,7 +8658,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         on_ambiguous_match: {
                             type: 'string',
                             enum: ['reject', 'first'],
-                            description: 'What to do when identifier_type/identifier_value match more than one element and match_content does not narrow it to exactly one. Default "reject" refuses the write with a 422 respira_ambiguous_target error and a candidate list, because guessing has silently edited the wrong element before. Pass "first" only when that is genuinely what you want: it means accepting whichever matching element comes first in document order, with no further confirmation.',
+                            description: 'What to do when identifier_type/identifier_value match more than one element and match_content does not narrow it to exactly one. Default "reject" refuses the write with a 422 respira_ambiguous_target error and a candidate list, because guessing has silently edited the wrong element before. "first" accepts whichever element respira_find_element resolves for this identifier. It does NOT mean the outermost match: for content and text lookups the resolver deliberately returns the DEEPEST (innermost) match, so the edit lands on the leaf module, not the section wrapping it; for other identifier types it is the first in document order. The 422 also returns `candidate_paths` — re-sending with identifier_type "path" and one of those values picks an exact element instead of accepting a default.',
                         },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value', 'updates'],
@@ -8728,13 +8753,17 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         post_id: { type: 'number', description: 'Page/post ID' },
                         identifier_type: {
                             type: 'string',
-                            enum: ['id', 'css_class', 'text', 'widget_type', 'global_id'],
-                            description: 'How to locate the element: "id" (element ID), "css_class" (CSS class name), "text" (visible text content), "widget_type" (widget/module type), or "global_id" (cross-page global element ID).',
+                            enum: ['id', 'css_class', 'text', 'widget_type', 'global_id', 'type', 'admin_label', 'content', 'class', 'path'],
+                            description: 'How to locate the element: "id" (element ID), "css_class"/"class" (CSS class name), "text"/"content" (visible text content), "widget_type"/"type" (widget/module type), "admin_label", "global_id" (cross-page global element ID), or "path" (the `path_string` respira_find_element returns, e.g. "1.0.1", which names exactly one element and is the reliable answer to a 422 respira_ambiguous_target).',
                         },
                         identifier_value: {
                             type: 'string',
                             description: 'Value matching the chosen identifier_type (e.g. the element ID, the class name, the text to match).',
                         },
+                        match_content: {
+                            type: 'string',
+                            description: 'Narrows a set of elements sharing identifier_type/identifier_value down to the ones whose own text or attribute values contain this string. It separates siblings; it cannot separate an element from an ancestor that contains it. For that case use identifier_type "path".',
+                        },
                         edit_target: {
                             type: 'string',
                             enum: ['live', 'duplicate'],
@@ -8752,7 +8781,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         on_ambiguous_match: {
                             type: 'string',
                             enum: ['reject', 'first'],
-                            description: 'What to do when identifier_type/identifier_value match more than one element and match_content does not narrow it to exactly one. Default "reject" refuses the removal with a 422 respira_ambiguous_target error and a candidate list, because guessing has silently deleted the wrong element before. Pass "first" only when that is genuinely what you want: it means removing whichever matching element comes first in document order, with no further confirmation.',
+                            description: 'What to do when identifier_type/identifier_value match more than one element and match_content does not narrow it to exactly one. Default "reject" refuses the removal with a 422 respira_ambiguous_target error and a candidate list, because guessing has silently deleted the wrong element before. "first" removes whichever element respira_find_element resolves for this identifier. It does NOT mean the outermost match: for content and text lookups the resolver deliberately returns the DEEPEST (innermost) match, so the removal takes the leaf module, not the section wrapping it; for other identifier types it is the first in document order. The 422 also returns `candidate_paths` — re-sending with identifier_type "path" and one of those values picks an exact element instead of accepting a default.',
                         },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value'],
@@ -8886,7 +8915,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_bulk_pages_operation',
-                description: 'Apply an operation across up to 100 pages. Supports strip_inline_styles, find_and_replace, and custom operations. Each page gets a snapshot for rollback. Rate limited to 3/hr.\n\nApproval flow: destructive — the first call may return `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to complete the operation.',
+                description: 'Apply an operation across up to 100 pages. Supports strip_inline_styles, find_and_replace, and custom operations. Each page gets a snapshot for rollback.\n\nRate limit: 20 write runs per hour per API key. Dry runs (`options.dry_run: true`) are NOT counted, so preview freely. find_and_replace also accepts an ARRAY of needles in one call — `find: ["a","b"], replace: ["x","y"]` (paired) or `find: ["a","b"], replace: "x"` (one replacement for all) — so a batch of rewrites costs one run instead of one each.\n\nApproval flow: destructive — the first call may return `code: respira_approval_required` with `data.approval_request.approval_token`. Pass that token back via the `approval_token` param on the next call to complete the operation.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -8897,11 +8926,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         },
                         operation: {
                             type: 'object',
-                            description: 'Operation to apply: {type: "strip_inline_styles"|"find_and_replace"|"custom", options: {...}}',
+                            description: 'Operation to apply: {type: "strip_inline_styles"|"find_and_replace"|"custom", options: {...}}. For find_and_replace: options.find is a string OR an array of strings; options.replace is a string (applied to every needle) OR an array of the same length as find; options.regex treats every find entry as a pattern. A mismatched pair, an object, or a non-string entry is refused with a 400 before any page is touched.',
                         },
                         options: {
                             type: 'object',
-                            description: 'Execution options: {dry_run: boolean}',
+                            description: 'Execution options: {dry_run: boolean}. dry_run previews every page without writing, without taking a snapshot, and without spending a rate-limited run.',
                         },
                         approval_token: {
                             type: 'string',