list_urls
Retrieve and manage a list of URLs with options to sort by clicks or timestamps, filter by search terms, and paginate results for streamlined URL analysis and organization.
Instructions
Get a list of URLs with sorting, pagination, and filtering options
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| perpage | No | Number of results per page | |
| search | No | Search term to filter results | |
| sortby | No | Field to sort by (e.g., "clicks", "timestamp") | |
| sortorder | No | Sort order ("asc" or "desc") |
Implementation Reference
- src/tools/listUrls.js:49-118 (handler)The execute function that implements the core logic of the 'list_urls' tool, including parameter validation, normalization, API call to yourlsClient.listUrls with fallback, and response formatting.execute: async ({ sortby, sortorder, offset, perpage, query, fields }) => { try { // Validate sortby const validSortFields = ['keyword', 'url', 'title', 'ip', 'timestamp', 'clicks']; if (sortby && !validSortFields.includes(sortby)) { throw new Error(`Invalid sortby value. Must be one of: ${validSortFields.join(', ')}`); } // Validate sortorder if (sortorder && !['ASC', 'DESC', 'asc', 'desc'].includes(sortorder)) { throw new Error('Invalid sortorder value. Must be ASC or DESC'); } // Validate numeric parameters if (offset !== undefined && (isNaN(Number(offset)) || Number(offset) < 0)) { throw new Error('Offset must be a non-negative number'); } if (perpage !== undefined && (isNaN(Number(perpage)) || Number(perpage) <= 0)) { throw new Error('Perpage must be a positive number'); } // Normalize fields if needed let normalizedFields = fields; if (typeof fields === 'string') { try { normalizedFields = JSON.parse(fields); } catch (e) { normalizedFields = fields.split(',').map(f => f.trim()); } } // Use the listUrls method with fallback enabled const result = await yourlsClient.listUrls({ sortby, sortorder, offset: offset !== undefined ? Number(offset) : undefined, perpage: perpage !== undefined ? Number(perpage) : undefined, query, fields: normalizedFields, useNativeFallback: true }); if (result.status === 'success') { const responseData = { total: result.total, page: result.page || 1, perpage: result.perpage, links: result.links || {}, results: result.result || [] }; // Add fallback information if applicable if (result.fallback_used) { responseData.fallback_used = true; if (result.fallback_limitations) { responseData.fallback_limitations = result.fallback_limitations; } } return createMcpResponse(true, responseData); } else { throw new Error(result.message || 'Unknown error'); } } catch (error) { return createMcpResponse(false, { message: error.message }); } }
- src/tools/listUrls.js:17-48 (schema)Input schema defining the parameters for the 'list_urls' tool, including sorting, pagination, filtering, and field selection options.inputSchema: { type: 'object', properties: { sortby: { type: 'string', description: 'Field to sort by (keyword, url, title, ip, timestamp, clicks)' }, sortorder: { type: 'string', description: 'Sort order (ASC or DESC)' }, offset: { type: 'number', description: 'Pagination offset' }, perpage: { type: 'number', description: 'Number of results per page' }, query: { type: 'string', description: 'Optional search query for filtering by keyword' }, fields: { type: 'array', items: { type: 'string' }, description: 'Fields to return (keyword, url, title, timestamp, ip, clicks)' } } },
- src/index.js:229-240 (registration)Registration of the 'list_urls' tool with the MCP server, providing name, description, Zod input schema, and the execute handler.server.tool( listUrlsTool.name, listUrlsTool.description, { sortby: z.string().optional().describe('Field to sort by (e.g., "clicks", "timestamp")'), sortorder: z.string().optional().describe('Sort order ("asc" or "desc")'), perpage: z.number().optional().describe('Number of results per page'), page: z.number().optional().describe('Page number'), search: z.string().optional().describe('Search term to filter results') }, listUrlsTool.execute );