WP Navigator MCP

Instructions

Implementation Reference

• src/tools/content/index.ts:690-718 (handler)

  Core handler implementation for wpnav_list_media: validates pagination, builds query string, fetches media from WP REST API /wp/v2/media, extracts summary fields, returns formatted JSON response.
  toolRegistry.register({ definition: { name: 'wpnav_list_media', description: 'List WordPress media library items. Returns media ID, title, URL, and mime type.', inputSchema: { type: 'object', properties: { page: { type: 'number', description: 'Page number for pagination (default: 1)' }, per_page: { type: 'number', description: 'Number of media items to return (default: 10, max: 100)' }, media_type: { type: 'string', description: 'Filter by media type: image, video, application, etc.' }, search: { type: 'string', description: 'Search term to filter media by title or filename' }, }, required: [], }, }, handler: async (args, context) => { const { page, per_page } = validatePagination(args); const qs = buildQueryString({ page, per_page, media_type: args.media_type, search: args.search }); const media = await context.wpRequest(`/wp/v2/media?${qs}`); const summary = media.map((item: any) => extractSummary(item, ['id', 'title.rendered', 'source_url', 'mime_type', 'modified'])); return { content: [{ type: 'text', text: context.clampText(JSON.stringify(summary, null, 2)) }], }; }, category: ToolCategory.CONTENT, });
• src/tools.ts:306-333 (schema)

  Input schema definition for wpnav_list_media tool, exported for MCP tool discovery.
  { name: 'wpnav_list_media', description: 'List WordPress media library items. Returns media ID, title, URL, and mime type.', inputSchema: { type: 'object' as const, properties: { per_page: { type: 'number' as const, description: 'Number of media items to return (default: 10, max: 100)', default: 10, }, page: { type: 'number' as const, description: 'Page number for pagination (default: 1)', default: 1, }, media_type: { type: 'string' as const, description: 'Filter by media type: image, video, application, etc.', }, search: { type: 'string' as const, description: 'Search term to filter media by title or filename', }, }, required: [], },
• src/tool-registry/utils.ts:88-99 (helper)

  Helper function validatePagination: normalizes page (min 1) and per_page (1-250, default 10) from args.
  /** * Validate pagination parameters */ export function validatePagination(args: { page?: number; per_page?: number; }): { page: number; per_page: number } { const page = Math.max(1, args.page ?? 1); const per_page = Math.min(250, Math.max(1, args.per_page ?? 10)); return { page, per_page }; }
• src/tool-registry/utils.ts:27-40 (helper)

  Helper function buildQueryString: constructs URLSearchParams from object, skipping null/undefined.
  /** * Build query string from parameters */ export function buildQueryString(params: Record<string, any>): string { const searchParams = new URLSearchParams(); for (const [key, value] of Object.entries(params)) { if (value !== undefined && value !== null) { searchParams.append(key, String(value)); } } return searchParams.toString(); }
• src/tool-registry/utils.ts:42-66 (helper)

  Helper function extractSummary: extracts specified fields from WP objects, supports nested paths like 'title.rendered'.
  /** * Extract summary fields from WordPress object */ export function extractSummary<T extends Record<string, any>>( obj: T, fields: string[] ): Record<string, any> { const summary: Record<string, any> = {}; for (const field of fields) { if (field.includes('.')) { // Handle nested fields (e.g., 'title.rendered') const parts = field.split('.'); let value: any = obj; for (const part of parts) { value = value?.[part]; } summary[field] = value; } else { summary[field] = obj[field]; } } return summary; }