IssueBadge MCP Server

Instructions

Implementation Reference

• src/index.ts:457-480 (handler)

  MCP request handler case for 'issue_badge' tool: parses input with schema, calls IssueBadgeClient.issueBadge, handles success/error response formatting.

  case 'issue_badge': {
    const validatedArgs = IssueBadgeSchema.parse(args);
    const result = await apiClient.issueBadge(validatedArgs);
    
    if (result.success) {
      return {
        content: [
          {
            type: 'text',
            text: `🎉 Badge Issued Successfully!\n\n📧 Recipient: ${validatedArgs.name}\n🆔 Issue ID: ${result.IssueId}\n🔗 Verification URL: ${result.publicUrl}\n\n${JSON.stringify(result, null, 2)}`,
          },
        ],
      };
    }
    
    return {
      content: [
        {
          type: 'text',
          text: `📜 Badge Issuance Result:\n\n${JSON.stringify(result, null, 2)}`,
        },
      ],
    };
  }

• src/index.ts:186-189 (handler)

  Core handler logic in IssueBadgeClient: sends POST request to IssueBadge API /issue/create endpoint with provided data.

  async issueBadge(data: z.infer<typeof IssueBadgeSchema>): Promise<IssuedBadge> {
    const response = await this.client.post('/issue/create', data);
    return response.data;
  }

• src/index.ts:73-80 (schema)

  Zod schema defining input validation for issue_badge tool parameters.

  const IssueBadgeSchema = z.object({
    badge_id: z.string().describe('Encrypted badge ID from badge creation'),
    name: z.string().describe('Recipient full name'),
    email: z.string().email().optional().describe('Recipient email address'),
    phone: z.string().optional().describe('Recipient phone number'),
    idempotency_key: z.string().describe('Unique key to prevent duplicate issuance'),
    metadata: z.record(z.any()).optional().describe('Custom field values and additional metadata'),
  });

• src/index.ts:277-312 (registration)

  Tool registration object defining name, description, and JSON inputSchema for the MCP 'issue_badge' tool.

  {
    name: 'issue_badge',
    description: 'Issue a badge to a recipient. This creates a digital certificate and sends notification email with verification URL.',
    inputSchema: {
      type: 'object',
      properties: {
        badge_id: {
          type: 'string',
          description: 'Encrypted badge ID from badge creation (get this from get_all_badges or create_badge)',
        },
        name: {
          type: 'string',
          description: 'Recipient\'s full name (will appear on the certificate)',
        },
        email: {
          type: 'string',
          format: 'email',
          description: 'Recipient\'s email address (optional, but recommended for notifications)',
        },
        phone: {
          type: 'string',
          description: 'Recipient\'s phone number (optional)',
        },
        idempotency_key: {
          type: 'string',
          description: 'Unique key to prevent duplicate issuance (e.g., "issue_john_doe_2024_001")',
        },
        metadata: {
          type: 'object',
          description: 'Custom field values and additional metadata (e.g., completion_date, score, etc.)',
          additionalProperties: true,
        },
      },
      required: ['badge_id', 'name', 'idempotency_key'],
    },
  },

• src/index.ts:113-117 (schema)

  TypeScript interface for the IssuedBadge response from the issue_badge API call.

  interface IssuedBadge {
    success: boolean;
    IssueId: string;
    publicUrl: string;
  }