Bucketeer MCP Server

A Model Context Protocol (MCP) server for managing feature flags in Bucketeer, an open-source feature flag management platform.

Features

This MCP server provides tools for basic CRUD operations on Bucketeer feature flags:

• listFeatureFlags - List all feature flags with filtering and pagination

• createFeatureFlag - Create a new feature flag

• getFeatureFlag - Get a specific feature flag by ID

• updateFeatureFlag - Update an existing feature flag

• archiveFeatureFlag - Archive a feature flag (make it inactive)

Related MCP server: MCP Clusters API Server

Prerequisites

• Node.js 18 or higher

• A Bucketeer instance with API access

• An API key with appropriate permissions (READ, WRITE, or ADMIN)

Installation

1. Clone this repository:

2. Install dependencies:

3. Build the project:

4. Create a .env file based on .env.example:

5. Configure your environment variables in .env:

Usage

Running the Server

Start the MCP server:

For development with auto-reload:

MCP Client Configuration

To use this server with an MCP client, add it to your MCP client configuration:

Available Tools

listFeatureFlags

List all feature flags in the specified environment.

Parameters:

• environmentId (optional) - Environment ID (uses default if not provided)

• pageSize (optional) - Number of items per page (1-100, default: 20)

• cursor (optional) - Pagination cursor for next page

• tags (optional) - Filter by tags

• orderBy (optional) - Field to order by (CREATED_AT, UPDATED_AT, NAME)

• orderDirection (optional) - Order direction (ASC, DESC)

• searchKeyword (optional) - Search keyword for feature name or ID

• maintainer (optional) - Filter by maintainer email

• archived (optional) - Filter by archived status

createFeatureFlag

Create a new feature flag.

Parameters:

• id (required) - Unique identifier (alphanumeric, hyphens, underscores)

• name (required) - Human-readable name

• description (optional) - Description of the feature flag

• environmentId (optional) - Environment ID (uses default if not provided)

• variations (required) - Array of variations (at least 2)

  • value (required) - The value returned when this variation is served

  • name (required) - Name of the variation

  • description (optional) - Description of the variation

• tags (optional) - Tags for the feature flag

• defaultOnVariationIndex (required) - Index of variation when flag is on (0-based)

• defaultOffVariationIndex (required) - Index of variation when flag is off (0-based)

• variationType (optional) - Type of the variation values: STRING (default), BOOLEAN, NUMBER, or JSON

getFeatureFlag

Get a specific feature flag by ID.

Parameters:

• id (required) - The ID of the feature flag to retrieve

• environmentId (optional) - Environment ID (uses default if not provided)

• featureVersion (optional) - Specific version of the feature to retrieve

updateFeatureFlag

Update an existing feature flag.

Parameters:

• id (required) - The ID of the feature flag to update

• comment (required) - Comment for the update (required for audit trail)

• environmentId (optional) - Environment ID (uses default if not provided)

• name (optional) - New name for the feature flag

• description (optional) - New description

• tags (optional) - New tags

• enabled (optional) - Enable or disable the feature flag

• archived (optional) - Archive or unarchive the feature flag

Note:

• This tool requires a comment for audit trail purposes

• It does not support updating variations. To modify variations, you would need to archive the current flag and create a new one.

archiveFeatureFlag

Archive a feature flag (make it inactive). Archived flags will return the default value defined in your code for all users.

Parameters:

• id (required) - The ID of the feature flag to archive

• environmentId (optional) - Environment ID (uses default if not provided)

• comment (required) - Comment for the archive action (required for audit trail)

Note: This operation archives the flag rather than permanently deleting it. The flag can be unarchived later if needed.

API Key Permissions

Different operations require different permission levels:

• READ: Required for listFeatureFlags and getFeatureFlag

• WRITE: Required for createFeatureFlag, updateFeatureFlag, and archiveFeatureFlag

Development

Project Structure

Linting

Run the linter:

Building

Build the TypeScript code:

Troubleshooting

Common Issues

1. Authentication errors: Ensure your API key is valid and has the necessary permissions

2. Environment ID not found: Verify the environment ID exists in your Bucketeer instance

3. Connection errors: Check that the BUCKETEER_HOST is correct and accessible

Logging

The server logs to stderr in JSON format. Adjust the log level using the LOG_LEVEL environment variable:

• error - Only errors

• warn - Warnings and errors

• info - General information (default)

• debug - Detailed debug information

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.