wpnav_delete_media
Permanently delete WordPress media files by ID using the WP Navigator MCP server. Remove unwanted images, videos, or documents from your WordPress site.
Instructions
Delete a media item by ID. WARNING: This permanently deletes the file from the server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | WordPress media ID | |
| force | No | Force permanent deletion. Default: true for media |
Implementation Reference
- src/tools/content/index.ts:763-797 (handler)The core handler function implementing wpnav_delete_media. Validates ID, constructs DELETE request to WP REST API /wp/v2/media/{id} with force=true by default, returns success/error response.handler: async (args, context) => { try { validateRequired(args, ['id']); const id = validateId(args.id, 'Media'); const params = new URLSearchParams(); if (args.force !== false) { params.append('force', 'true'); } const result = await context.wpRequest(`/wp/v2/media/${id}?${params.toString()}`, { method: 'DELETE', }); return { content: [{ type: 'text', text: context.clampText(JSON.stringify({ id: result.id, message: 'Media item permanently deleted' }, null, 2)), }], }; } catch (error: any) { const errorMessage = error.message || 'Unknown error'; return { content: [{ type: 'text', text: JSON.stringify({ error: 'operation_failed', code: 'DELETE_FAILED', message: errorMessage, context: { resource_type: 'media', resource_id: args.id, suggestion: 'Use wpnav_get_media to verify media exists' }, }, null, 2), }], isError: true, }; }
- src/tools/content/index.ts:754-761 (schema)Input schema validating id (required number) and optional force boolean for the wpnav_delete_media tool.inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'WordPress media ID' }, force: { type: 'boolean', description: 'Force permanent deletion. Default: true for media', default: true }, }, required: ['id'], },
- src/tools/content/index.ts:750-800 (registration)Tool registration call that defines name, description, schema, handler, and category for wpnav_delete_media.toolRegistry.register({ definition: { name: 'wpnav_delete_media', description: 'Delete a media item by ID. WARNING: This permanently deletes the file from the server.', inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'WordPress media ID' }, force: { type: 'boolean', description: 'Force permanent deletion. Default: true for media', default: true }, }, required: ['id'], }, }, handler: async (args, context) => { try { validateRequired(args, ['id']); const id = validateId(args.id, 'Media'); const params = new URLSearchParams(); if (args.force !== false) { params.append('force', 'true'); } const result = await context.wpRequest(`/wp/v2/media/${id}?${params.toString()}`, { method: 'DELETE', }); return { content: [{ type: 'text', text: context.clampText(JSON.stringify({ id: result.id, message: 'Media item permanently deleted' }, null, 2)), }], }; } catch (error: any) { const errorMessage = error.message || 'Unknown error'; return { content: [{ type: 'text', text: JSON.stringify({ error: 'operation_failed', code: 'DELETE_FAILED', message: errorMessage, context: { resource_type: 'media', resource_id: args.id, suggestion: 'Use wpnav_get_media to verify media exists' }, }, null, 2), }], isError: true, }; } }, category: ToolCategory.CONTENT, });
- src/tool-registry/utils.ts:13-25 (helper)Helper function validateRequired used in the handler to ensure 'id' argument is provided.export function validateRequired(args: any, fields: string[]): void { const missing: string[] = []; for (const field of fields) { if (args[field] === undefined || args[field] === null || args[field] === '') { missing.push(field); } } if (missing.length > 0) { throw new Error(`Missing required fields: ${missing.join(', ')}`); } }
- src/tool-registry/utils.ts:152-160 (helper)Helper function validateId used in the handler to validate and parse the media ID as positive integer.export function validateId(id: any, entityName: string = 'Entity'): number { const numId = Number(id); if (isNaN(numId) || numId <= 0) { throw new Error(`${entityName} ID must be a positive integer`); } return numId; }