quickchart-mcp-server

Instructions

Implementation Reference

• src/tools/barcode.ts:235-341 (handler)

  Main tool handler that validates inputs, builds QuickChart URL, fetches barcode image as PNG, embeds base64 image in response, generates URL, and optionally saves to file using getDownloadPath.

  export async function handleBarcodeTool(args: any): Promise<any> {
    const type = args.type as string;
    const text = args.text as string;
    const action = args.action as string;
    
    validateBarcodeType(type);
    validateText(text);
    validateAction(action);
    validateOutputPath(args.outputPath, action);
    validateDimensions(args.width, args.height);
    validateScale(args.scale);
    validateRotation(args.rotate);
  
    const params = buildBarcodeParams(type, text, {
      width: args.width as number,
      height: args.height as number,
      scale: args.scale as number,
      includeText: args.includeText as boolean,
      rotate: args.rotate as string,
    });
    const chartUrl = buildBarcodeUrl(type, text);
  
    const result: any = {
      content: [
        {
          type: "text",
          text: "Below is the barcode URL:",
        },
        {
          type: "text",
          text: chartUrl,
        },
      ],
      metadata: {
        chartType: "barcode",
        generatedAt: new Date().toISOString(),
        chartUrl: chartUrl,
      },
    };
  
    try {
      const pngData = await fetchBarcodeContent(params, "png");
      const pngBase64 = Buffer.from(pngData).toString("base64");
  
      result.content.push(
        {
          type: "text",
          text: "Below is the PNG image:",
        },
        {
          type: "image",
          data: pngBase64,
          mimeType: "image/png",
        }
      );
      result.metadata.pngBase64 = pngBase64;
    } catch (error) {
      result.content.unshift({
        type: "text",
        text: "⚠️ Failed to fetch barcode image",
      });
      result.content.push({
        type: "text",
        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
      });
      result.metadata.error =
        error instanceof Error ? error.message : String(error);
    }
  
    if (action === "get_url") {
      return result;
    }
  
    const format = "png";
    const outputPath = getDownloadPath(
      args.outputPath as string | undefined,
      format
    );
  
    try {
      const dir = path.dirname(outputPath);
      if (!fs.existsSync(dir)) {
        fs.mkdirSync(dir, { recursive: true });
      }
  
      const data = await fetchBarcodeContent(params, format);
      fs.writeFileSync(outputPath, data);
  
      result.metadata.savedPath = outputPath;
      result.content.push({
        type: "text",
        text: "Below is the saved file path:",
      });
      result.content.push({
        type: "text",
        text: outputPath,
      });
      return result;
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to save barcode: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

• src/tools/barcode.ts:11-62 (schema)

  Input schema and metadata definition for the create-barcode tool, including required parameters (action, type, text) and optional formatting options.

  export const CREATE_BARCODE_TOOL: Tool = {
    name: "create-barcode",
    description:
      "Create barcodes using QuickChart - get barcode image URL or save barcode image to file",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["get_url", "save_file"],
          description: "Whether to get barcode URL or save as file",
        },
        outputPath: {
          type: "string",
          description:
            "Path where to save the file (only used with action=save_file)",
        },
        type: {
          type: "string",
          description:
            "Barcode type (e.g., qr, code128, ean13, datamatrix, upca, etc.)",
        },
        text: {
          type: "string",
          description: "Data to encode in the barcode",
        },
        width: {
          type: "integer",
          description: "Barcode width",
        },
        height: {
          type: "integer",
          description: "Barcode height",
        },
        scale: {
          type: "integer",
          description: "Scale factor",
        },
        includeText: {
          type: "boolean",
          description: "Include human-readable text below barcode",
        },
        rotate: {
          type: "string",
          enum: ["N", "R", "L", "I"],
          description:
            "Rotation: N=Normal, R=Right 90°, L=Left 90°, I=Inverted 180°",
        },
      },
      required: ["action", "type", "text"],
    },
  };

• src/tools/index.ts:88-88 (registration)

  Maps the tool name 'create-barcode' to its handler function handleBarcodeTool and associates it with ToolNames.BARCODE in the ALL_TOOL_HANDLERS object.

  "create-barcode": { handler: handleBarcodeTool, toolName: ToolNames.BARCODE },

• src/tools/index.ts:43-43 (registration)

  Registers the CREATE_BARCODE_TOOL schema in the ALL_TOOLS array with its ToolNames.BARCODE identifier.

  { tool: CREATE_BARCODE_TOOL, name: ToolNames.BARCODE },

• src/tools/help.ts:286-329 (helper)

  Documentation and usage examples for the create-barcode tool provided in the help tool data.

  "create-barcode": {
    name: "create-barcode",
    description:
      "Generate barcodes and QR codes - get barcode image URL or save barcode image to file",
    documentation: "https://quickchart.io/documentation/barcode-api/",
    additionalResources: {
      apiReference: "https://quickchart.io/documentation/barcode-api/",
      supportedFormats: "https://github.com/bwipp/postscriptbarcode/wiki",
    },
    supportedBarcodeTypes: [
      "QR Code: High-density 2D barcode for URLs, text, and data",
      "Code 128: Versatile 1D barcode for alphanumeric content",
      "EAN-13/UPC-A: Standard retail product identification",
      "Data Matrix: Compact 2D barcode for small items",
      "PDF417: High-capacity 2D barcode for documents",
      "Aztec: Compact 2D barcode with built-in error correction",
    ],
    whatYouCanCreate: [
      "Product Management: UPC-A and EAN-13 codes for retail products",
      "Inventory Management: Code 128 barcodes for warehouse tracking",
      "Shipping Labels: Generate tracking codes for logistics",
      "Document Encoding: PDF417 codes for storing large amounts of data",
      "Asset Tracking: Data Matrix codes for equipment and tools",
      "Mobile Applications: QR codes for app downloads and links",
      "Contact Information: QR codes containing vCard data",
      "Event Tickets: Secure barcodes for entry validation",
      "Payment Processing: QR codes for mobile payments",
      "Location Sharing: QR codes with GPS coordinates",
      "WiFi Access: QR codes for network credentials",
      "Promotional Campaigns: QR codes linking to special offers",
    ],
    promptExamples: [
      'Inventory Management: "Generate product barcodes for warehouse system"',
      'Retail Operations: "Create UPC codes for new product lines"',
      'Asset Tracking: "Generate Code128 barcodes for equipment tracking"',
    ],
    usageExample: {
      action: "get_url",
      type: "code128",
      text: "ABC123456789",
      width: 300,
      height: 100,
    },
  },