Bucketeer MCP Server

Instructions

Implementation Reference

• src/tools/create-flag.ts:115-213 (handler)

  The handler function that executes the createFeatureFlag tool logic: validates input with Zod schema, checks variation indices, creates BucketeerClient, sends createFeature request to API, logs success/error, returns MCP-formatted response.

  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.issues,
  							},
  							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-37 (schema)

  Zod schema (createFlagSchema) used internally by the handler for input validation of the createFeatureFlag tool.

  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:44-114 (schema)

  JSON Schema (inputSchema) defining the input structure for the 'createFeatureFlag' tool, exposed to the MCP client.

  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)

  Registration of the createFlagTool (named 'createFeatureFlag') in the central tools array, imported into the MCP server.

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

• src/server.ts:8-65 (registration)

  MCP server setup in BucketeerMCPServer: imports tools array and registers ListTools and CallTool request handlers that use the tools list to expose and execute 'createFeatureFlag'.

  import { tools } from "./tools/index.js";
  
  export class BucketeerMCPServer {
  	private server: Server;
  
  	constructor() {
  		this.server = new Server(
  			{
  				name: "bucketeer-mcp-server",
  				version: "1.0.0",
  			},
  			{
  				capabilities: {
  					tools: {},
  				},
  			},
  		);
  
  		this.setupHandlers();
  		this.setupErrorHandling();
  	}
  
  	private setupHandlers() {
  		// Handle list tools request
  		this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  			logger.debug("Listing available tools");
  
  			return {
  				tools: tools.map((tool) => ({
  					name: tool.name,
  					description: tool.description,
  					inputSchema: tool.inputSchema,
  				})),
  			};
  		});
  
  		// Handle tool calls
  		this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
  			const { name, arguments: args } = request.params;
  
  			logger.info(`Tool called: ${name}`, { arguments: args });
  
  			const tool = tools.find((t) => t.name === name);
  
  			if (!tool) {
  				logger.error(`Tool not found: ${name}`);
  				throw new Error(`Tool not found: ${name}`);
  			}
  
  			try {
  				const result = await tool.handler(args);
  				logger.info(`Tool ${name} executed successfully`);
  				return result;
  			} catch (error) {
  				logger.error(`Tool ${name} execution failed`, error);
  				throw error;
  			}
  		});