create_badge

Instructions

Implementation Reference

• src/index.ts:191-231 (handler)

  Core handler function that implements the badge creation logic: sends POST to '/badge/create' API endpoint, handles optional file upload for badge logo using FormData, or plain JSON payload.

  async createBadge(data: z.infer<typeof CreateBadgeSchema>): Promise<CreatedBadge> {
    const { badge_logo_path, ...badgeData } = data;
    
    if (badge_logo_path) {
      // Handle file upload
      const formData = new FormData();
      
      // Add file
      try {
        const fileBuffer = readFileSync(badge_logo_path);
        const fileName = badge_logo_path.split('/').pop() || 'badge_logo.png';
        formData.append('badge_logo', fileBuffer, {
          filename: fileName,
        });
      } catch (error) {
        throw new Error(`Failed to read badge logo file: ${error}`);
      }
      
      // Add other fields
      Object.entries(badgeData).forEach(([key, value]) => {
        if (value !== undefined) {
          if (key === 'custom_fields') {
            formData.append(key, JSON.stringify(value));
          } else {
            formData.append(key, String(value));
          }
        }
      });
  
      const response = await this.client.post('/badge/create', formData, {
        headers: {
          ...formData.getHeaders(),
        },
      });
      return response.data;
    } else {
      // JSON request without file
      const response = await this.client.post('/badge/create', badgeData);
      return response.data;
    }
  }

• src/index.ts:313-388 (registration)

  MCP tool registration defining the 'create_badge' tool with name, description, and detailed JSON schema for input validation.

  {
    name: 'create_badge',
    description: 'Create a new badge template with optional custom fields and branding. This badge can then be issued to recipients.',
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Badge name (e.g., "Web Development Certificate")',
        },
        description: {
          type: 'string',
          description: 'Badge description (e.g., "Awarded for completing the full-stack web development course")',
        },
        issuing_organization_name: {
          type: 'string',
          description: 'Name of the issuing organization (e.g., "Tech Academy")',
        },
        idempotency_key: {
          type: 'string',
          description: 'Unique key to prevent duplicate badge creation (e.g., "badge_webdev_2024_001")',
        },
        nickname: {
          type: 'string',
          description: 'Optional badge nickname or short name',
        },
        left_panel_description: {
          type: 'string',
          description: 'Additional description for the left panel of the certificate',
        },
        organization_id: {
          type: 'string',
          description: 'Existing organization ID (optional, will create new organization if not provided)',
        },
        comment: {
          type: 'string',
          description: 'Additional comments or notes about the badge',
        },
        expire_date: {
          type: 'string',
          pattern: '^\\d{4}-\\d{2}-\\d{2}$',
          description: 'Badge expiration date in YYYY-MM-DD format (optional)',
        },
        badge_logo_path: {
          type: 'string',
          description: 'Path to badge logo file (jpeg,png,jpg,gif,svg, max 2MB)',
        },
        custom_fields: {
          type: 'array',
          description: 'Custom fields for this badge (e.g., completion date, score, instructor)',
          items: {
            type: 'object',
            properties: {
              name: {
                type: 'string',
                description: 'Field name (e.g., "Completion Date")',
              },
              type: {
                type: 'string',
                enum: ['text', 'email', 'number', 'date'],
                description: 'Field type',
                default: 'text',
              },
              required: {
                type: 'boolean',
                description: 'Whether this field is required when issuing the badge',
                default: false,
              },
            },
            required: ['name'],
          },
        },
      },
      required: ['name', 'description', 'issuing_organization_name', 'idempotency_key'],
    },
  },

• src/index.ts:82-98 (schema)

  Zod validation schema used internally for parsing and validating arguments before calling the createBadge handler.

  const CreateBadgeSchema = z.object({
    name: z.string().describe('Badge name'),
    description: z.string().describe('Badge description'),
    issuing_organization_name: z.string().describe('Name of the issuing organization'),
    idempotency_key: z.string().describe('Unique key to prevent duplicate badge creation'),
    nickname: z.string().optional().describe('Optional badge nickname'),
    left_panel_description: z.string().optional().describe('Additional description for left panel'),
    organization_id: z.string().optional().describe('Existing organization ID'),
    comment: z.string().optional().describe('Additional comments'),
    expire_date: z.string().optional().describe('Badge expiration date (YYYY-MM-DD)'),
    badge_logo_path: z.string().optional().describe('Path to badge logo file'),
    custom_fields: z.array(z.object({
      name: z.string().describe('Field name'),
      type: z.enum(['text', 'email', 'number', 'date']).default('text').describe('Field type'),
      required: z.boolean().default(false).describe('Whether field is required'),
    })).optional().describe('Custom fields for this badge'),
  });

• src/index.ts:482-505 (handler)

  MCP server request handler switch case for 'create_badge': parses args with schema, invokes apiClient.createBadge, and returns formatted response content.

  case 'create_badge': {
    const validatedArgs = CreateBadgeSchema.parse(args);
    const result = await apiClient.createBadge(validatedArgs);
    
    if (result.success) {
      return {
        content: [
          {
            type: 'text',
            text: `✨ Badge Created Successfully!\n\n🏷️ Badge Name: ${validatedArgs.name}\n🆔 Badge ID: ${result.badgeId}\n🏢 Organization ID: ${result.organizationId}\n\nYou can now issue this badge to recipients using the badge ID.\n\n${JSON.stringify(result, null, 2)}`,
          },
        ],
      };
    }
    
    return {
      content: [
        {
          type: 'text',
          text: `🎨 Badge Creation Result:\n\n${JSON.stringify(result, null, 2)}`,
        },
      ],
    };
  }