Bucketeer MCP

🚀 Bucketeer MCP Server

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

🚀 Quick Start

This MCP server is designed to manage feature flags in Bucketeer. It offers a set of tools for performing basic CRUD operations on feature flags.

✨ 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)

⚠️ Important Note

This is a beta version. Breaking changes may be introduced before general release.

📦 Installation

Prerequisites

• Node.js 18 or higher
• A Bucketeer instance with API access
• An API key with appropriate permissions (READ, WRITE, or ADMIN)

Steps

1. Clone this repository

git clone https://github.com/yourusername/bucketeer-mcp.git
cd bucketeer-mcp

2. Install dependencies

npm install

3. Build the project

npm run build

💻 Usage Examples

Running the Server

Start the MCP server

npm start

For development with auto - reload

npm run dev

MCP Client Configuration

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

{
  "mcpServers": {
    "bucketeer": {
      "command": "node",
      "args": ["/path/to/bucketeer-mcp/dist/index.js"],
      "env": {
        "BUCKETEER_HOST": "api.bucketeer.io",
        "BUCKETEER_API_KEY": "your-api-key",
        "BUCKETEER_ENVIRONMENT_ID": "your-environment-id"
      }
    }
  }
}

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.

🔧 Technical Details

Linting

Run the linter

npm run lint

Building

Build the TypeScript code

npm run build

🤝 Contributing

We would ❤️ for you to contribute to Bucketeer and help improve it! Anyone can use and enjoy it!

Please follow our contribution guide here.

📄 License

Apache License 2.0, see LICENSE.