YOURLS-MCP

Instructions

Implementation Reference

• src/tools/generateQrCode.js:43-115 (handler)

  The main handler function (execute) for the generate_qr_code MCP tool. Validates inputs, calls yourlsClient.generateQrCode, and formats the MCP response.

  execute: async ({ shorturl, size, border, ecc, format }) => {
    try {
      // Validate size if provided
      if (size !== undefined) {
        const sizeNum = Number(size);
        if (isNaN(sizeNum) || sizeNum <= 0) {
          throw new Error('Size must be a positive number');
        }
        
        // Add upper limit check for QR code size
        if (sizeNum > 1000) {
          throw new Error('QR code size cannot exceed 1000 pixels for performance reasons');
        }
      }
      
      // Validate border if provided
      if (border !== undefined) {
        const borderNum = Number(border);
        if (isNaN(borderNum) || borderNum < 0) {
          throw new Error('Border must be a non-negative number');
        }
      }
      
      // Validate ecc if provided
      if (ecc && !['L', 'M', 'Q', 'H'].includes(ecc.toUpperCase())) {
        throw new Error(`Error correction level '${ecc}' is not supported. Must be one of: L (low), M (medium), Q (quartile), or H (high)`);
      }
      
      // Normalize ecc to uppercase
      if (ecc) {
        ecc = ecc.toUpperCase();
      }
      
      // Validate format if provided
      if (format && !['png', 'jpg', 'jpeg', 'gif', 'svg'].includes(format.toLowerCase())) {
        throw new Error(`Format '${format}' is not supported. Must be one of: png, jpg, jpeg, gif, svg`);
      }
      
      // Define MIME type mapping to ensure consistency
      const formatToMimeType = {
        'png': 'image/png',
        'jpg': 'image/jpeg',
        'jpeg': 'image/jpeg',
        'svg': 'image/svg+xml',
        'gif': 'image/gif'
      };
      
      // Generate QR code
      const result = await yourlsClient.generateQrCode(shorturl, {
        size: size !== undefined ? Number(size) : undefined,
        border: border !== undefined ? Number(border) : undefined,
        ecc,
        format
      });
      
      if (result.status === 'success') {
        return createMcpResponse(true, {
          shorturl: shorturl,
          data: result.data,
          contentType: result.contentType,
          url: result.url,
          config: result.config
        });
      } else {
        throw new Error(result.message || 'Unknown error');
      }
    } catch (error) {
      return createMcpResponse(false, {
        message: error.message,
        shorturl: shorturl
      });
    }
  }

• src/tools/generateQrCode.js:17-42 (schema)

  Input schema definition for the generate_qr_code tool, defining parameters and validation rules.

  inputSchema: {
    type: 'object',
    properties: {
      shorturl: {
        type: 'string',
        description: 'The short URL or keyword to generate a QR code for'
      },
      size: {
        type: 'number',
        description: 'QR code size in pixels (default: depends on plugin configuration)'
      },
      border: {
        type: 'number',
        description: 'Border width around the QR code (default: depends on plugin configuration)'
      },
      ecc: {
        type: 'string',
        description: 'Error correction level: L (low), M (medium), Q (quartile), or H (high)'
      },
      format: {
        type: 'string',
        description: 'Image format (e.g., png, jpg, svg)'
      }
    },
    required: ['shorturl']
  },

• src/index.js:242-252 (registration)

  Registration of the generate_qr_code tool on the MCP server in the main entry point.

  server.tool(
    generateQrCodeTool.name,
    generateQrCodeTool.description,
    {
      shorturl: z.string().describe('The short URL to generate a QR code for'),
      size: z.number().optional().describe('Size of the QR code in pixels'),
      format: z.string().optional().describe('Image format (png, svg, etc.)'),
      margin: z.number().optional().describe('Margin size')
    },
    generateQrCodeTool.execute
  );

• src/api.js:1194-1304 (helper)

  Underlying YOURLS API client method that generates the QR code image by calling the YOURLS-IQRCodes plugin endpoint.

  async generateQrCode(shorturl, { size, border, ecc, format } = {}) {
    // Define MIME type mapping to ensure consistency
    const formatToMimeType = {
      'png': 'image/png',
      'jpg': 'image/jpeg',
      'jpeg': 'image/jpeg',
      'svg': 'image/svg+xml',
      'gif': 'image/gif'
    };
    
    try {
      // First check if the shorturl exists
      await this.expand(shorturl);
      
      // Construct the QR code URL (YOURLS-IQRCodes plugin appends .qr to the shorturl)
      const baseUrl = this.api_url.replace('yourls-api.php', '');
      let qrUrl = `${baseUrl}${shorturl}.qr`;
      
      // Validate and normalize the parameters
      let normalizedSize, normalizedBorder, normalizedEcc, normalizedFormat;
      
      // Validate size
      if (size !== undefined) {
        normalizedSize = Number(size);
        if (isNaN(normalizedSize) || normalizedSize <= 0) {
          throw new Error('Size must be a positive number');
        }
        if (normalizedSize > 1000) {
          throw new Error('QR code size cannot exceed 1000 pixels for performance reasons');
        }
      }
      
      // Validate border
      if (border !== undefined) {
        normalizedBorder = Number(border);
        if (isNaN(normalizedBorder) || normalizedBorder < 0) {
          throw new Error('Border must be a non-negative number');
        }
      }
      
      // Validate and normalize ECC
      if (ecc !== undefined) {
        if (!['L', 'M', 'Q', 'H', 'l', 'm', 'q', 'h'].includes(ecc)) {
          throw new Error(`Error correction level '${ecc}' is not supported. Must be one of: L, M, Q, H`);
        }
        normalizedEcc = ecc.toUpperCase();
      }
      
      // Validate and normalize format
      if (format !== undefined) {
        normalizedFormat = format.toLowerCase();
        if (!Object.keys(formatToMimeType).includes(normalizedFormat)) {
          throw new Error(`Format '${format}' is not supported. Must be one of: png, jpg, jpeg, gif, svg`);
        }
      }
      
      // Add query parameters if provided
      const params = new URLSearchParams();
      if (normalizedSize !== undefined) params.append('size', normalizedSize);
      if (normalizedBorder !== undefined) params.append('border', normalizedBorder);
      if (normalizedEcc !== undefined) params.append('ecc', normalizedEcc);
      if (normalizedFormat !== undefined) params.append('format', normalizedFormat);
      
      const queryString = params.toString();
      if (queryString) {
        qrUrl += `?${queryString}`;
      }
      
      // Fetch the QR code image
      const response = await axios.get(qrUrl, {
        responseType: 'arraybuffer'
      });
      
      // Convert to base64
      const base64Image = Buffer.from(response.data, 'binary').toString('base64');
      
      // Determine MIME type - use our mapping if we know the format, otherwise use server-provided
      const contentType = normalizedFormat ? 
        formatToMimeType[normalizedFormat] : 
        (response.headers['content-type'] || 'image/png');
      
      return {
        status: 'success',
        data: base64Image,
        contentType: contentType,
        url: qrUrl,
        config: {
          size: normalizedSize,
          border: normalizedBorder,
          ecc: normalizedEcc,
          format: normalizedFormat
        }
      };
    } catch (error) {
      // If the error is from the expand method (meaning the shorturl doesn't exist)
      if (error.response && error.response.status === 404) {
        throw new Error(`The short URL or keyword '${shorturl}' was not found in the database.`);
      }
      
      // If the error is from fetching the QR code (meaning the IQRCodes plugin isn't installed)
      if (error.response && 
          (error.response.status === 404 || 
           error.response.status === 500 || 
           error.response.status === 501)) {
        throw new Error('QR code generation is not available. Please install the YOURLS-IQRCodes plugin.');
      }
      
      // For other errors, just throw them
      throw error;
    }
  }

• src/tools/index.js:196-206 (registration)

  Alternative registration of the tool in the tools index module (not used in main entry).

  server.tool(
    generateQrCodeTool.name,
    generateQrCodeTool.description,
    {
      shorturl: z.string().describe('The short URL to generate a QR code for'),
      size: z.number().optional().describe('Size of the QR code in pixels'),
      format: z.string().optional().describe('Image format (png, svg, etc.)'),
      margin: z.number().optional().describe('Margin size')
    },
    generateQrCodeTool.execute
  );