Bucketeer MCP Server

Instructions

Implementation Reference

• src/tools/create-flag.ts:97-169 (handler)

  The async handler function that parses and validates input with Zod schema, creates a BucketeerClient instance, constructs the CreateFeatureRequest, calls the createFeature API method, logs the result, and returns structured success or error content.

  handler: async (input: unknown) => {
    try {
      // Validate input
      const params = createFlagSchema.parse(input);
      
      // Validate variation indices
      if (params.defaultOnVariationIndex >= params.variations.length) {
        throw new Error(`defaultOnVariationIndex ${params.defaultOnVariationIndex} is out of bounds. Must be less than ${params.variations.length}`);
      }
      if (params.defaultOffVariationIndex >= params.variations.length) {
        throw new Error(`defaultOffVariationIndex ${params.defaultOffVariationIndex} is out of bounds. Must be less than ${params.variations.length}`);
      }
      
      logger.debug('Creating feature flag', params);
      
      // Create API client
      const client = new BucketeerClient(config.bucketeerHost, config.bucketeerApiKey);
      
      // Prepare request
      const request: CreateFeatureRequest = {
        id: params.id,
        name: params.name,
        description: params.description,
        environmentId: getEnvironmentId(params.environmentId),
        variations: params.variations,
        tags: params.tags,
        defaultOnVariationIndex: params.defaultOnVariationIndex,
        defaultOffVariationIndex: params.defaultOffVariationIndex,
        variationType: params.variationType,
      };
      
      // Make API call
      const response = await client.createFeature(request);
      
      logger.info(`Successfully created feature flag: ${response.feature.id}`);
      
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            success: true,
            feature: response.feature,
          }, null, 2),
        }],
      };
    } catch (error) {
      logger.error('Failed to create feature flag', error);
      
      if (error instanceof z.ZodError) {
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              success: false,
              error: 'Invalid input parameters',
              details: error.errors,
            }, null, 2),
          }],
          isError: true,
        };
      }
      
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            success: false,
            error: error instanceof Error ? error.message : 'Unknown error',
          }, null, 2),
        }],
        isError: true,
      };
    }

• src/tools/create-flag.ts:16-28 (schema)

  Zod schema used for runtime input validation within the handler, defining properties like id, name, variations, indices, and variationType.

  export const createFlagSchema = z.object({
    id: z.string()
      .min(1, 'Feature flag ID is required')
      .regex(/^[a-zA-Z0-9-_]+$/, 'ID must contain only alphanumeric characters, hyphens, and underscores'),
    name: z.string().min(1, 'Feature flag name is required'),
    description: z.string().optional().default(''),
    environmentId: z.string().optional(),
    variations: z.array(variationSchema).min(2, 'At least 2 variations are required'),
    tags: z.array(z.string()).optional(),
    defaultOnVariationIndex: z.number().min(0),
    defaultOffVariationIndex: z.number().min(0),
    variationType: z.nativeEnum(VariationType).optional().default(VariationType.STRING),
  });

• src/tools/create-flag.ts:35-96 (schema)

  JSON Schema object defined within the tool for MCP protocol input validation and documentation.

  inputSchema: {
    type: 'object' as const,
    properties: {
      id: {
        type: 'string',
        description: 'Unique identifier for the feature flag (alphanumeric, hyphens, underscores)',
      },
      name: {
        type: 'string',
        description: 'Human-readable name for the feature flag',
      },
      description: {
        type: 'string',
        description: 'Description of the feature flag',
      },
      environmentId: {
        type: 'string',
        description: 'Environment ID (uses default if not provided)',
      },
      variations: {
        type: 'array',
        description: 'List of variations (at least 2 required)',
        items: {
          type: 'object',
          properties: {
            value: {
              type: 'string',
              description: 'The value returned when this variation is served',
            },
            name: {
              type: 'string',
              description: 'Name of the variation',
            },
            description: {
              type: 'string',
              description: 'Description of the variation',
            },
          },
          required: ['value', 'name'],
        },
      },
      tags: {
        type: 'array',
        items: { type: 'string' },
        description: 'Tags for the feature flag',
      },
      defaultOnVariationIndex: {
        type: 'number',
        description: 'Index of the variation to serve when flag is on (0-based)',
      },
      defaultOffVariationIndex: {
        type: 'number',
        description: 'Index of the variation to serve when flag is off (0-based)',
      },
      variationType: {
        type: 'string',
        enum: ['STRING', 'BOOLEAN', 'NUMBER', 'JSON'],
        description: 'Type of the variation values (default: STRING)',
      },
    },
    required: ['id', 'name', 'variations', 'defaultOnVariationIndex', 'defaultOffVariationIndex'],
  },

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

  The tools array registers createFlagTool alongside other flag management tools, likely used for MCP server toolset initialization.

  export const tools = [
    listFlagsTool,
    createFlagTool,
    getFlagTool,
    updateFlagTool,
    archiveFlagTool,
  ];