YOURLS-MCP

Instructions

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
  );