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; } });