Media Library

Manage attachments already in the WordPress Media Library, built on core attachment functions (wp_get_attachment_metadata, wp_update_post, wp_delete_attachment, …). To pull an external image into the library, use sideload-image; to search existing uploads use list-media.

get-media, update-media, and upload-media are enabled by default. delete-media ships disabled-by-default.

emcp-tools/upload-media

New in v3.12.1. Uploads a file’s bytes straight from the client machine into the Media Library, the companion to sideload-image (which only fetches a URL the server can already reach) — this is how an agent adds an image from your own computer.

Input: filename and data (both required) — data is base64, an optional data:<mime>;base64, prefix is stripped automatically. filename must include a real extension. Optional: alt, title, caption, description, post_id (attaches to a post), convert_webp (default true; set false to skip optimization for this upload).

Returns: { id, title, url, mime_type, filesize, alt, width, height }.

Only WordPress-allowed file types are accepted, executable types are refused. Capped at 32 MB decoded (filterable via emcp_tools_upload_media_max_bytes). Runs through the same optimize/WebP pipeline as the other media tools.

Capability: upload_files.

emcp-tools/get-media

Full detail for one attachment: every registered image size (URL + dimensions), mime type, filesize, alt text, caption, description, and the raw attachment metadata.

Input: attachment_id.

Returns: { id, title, url, mime_type, filesize, alt, caption, description, sizes: { ... }, metadata: { ... } }.

Capability: edit_posts. Read-only.

emcp-tools/update-media

Edits an attachment’s title, alt text, caption, and/or description. Only the fields you pass change, a one-call accessibility/SEO fix for library images.

Input: attachment_id plus any of title, alt, caption, description.

Returns: { id, updated: [...] }.

Capability: edit_post on the attachment.

emcp-tools/delete-media

Deletes an attachment. Destructive and effectively permanent: WordPress bypasses Trash for media unless the MEDIA_TRASH constant is defined, so on most sites the file and its database record are gone for good.

A three-way gate protects this tool:

1. It is disabled-by-default. An admin must enable it on EMCP Tools → Tools.
2. The caller needs delete_post on the attachment.
3. The input must include an explicit confirm: true.

Pass force: true to skip Trash even when MEDIA_TRASH is on.

Input: attachment_id, confirm (must be true), force (optional).

Returns: { id, deleted: true, forced }.

Capability: delete_post on the attachment. Destructive.