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)

Prerequisites

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

Installation

Clone this repository:

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

Install dependencies:

npm install

Build the project:

npm run build

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

cp .env.example .env

Configure your environment variables in .env:

BUCKETEER_HOST=api.bucketeer.io
BUCKETEER_API_KEY=your-api-key-here
BUCKETEER_ENVIRONMENT_ID=your-environment-id
LOG_LEVEL=info

Usage

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.

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

bucketeer-mcp/
├── src/
│   ├── api/
│   │   └── client.ts       # Bucketeer API client
│   ├── tools/
│   │   ├── list-flags.ts   # List feature flags tool
│   │   ├── create-flag.ts  # Create feature flag tool
│   │   ├── get-flag.ts     # Get feature flag tool
│   │   ├── update-flag.ts  # Update feature flag tool
│   │   ├── archive-flag.ts # Archive feature flag tool
│   │   └── index.ts        # Tool exports
│   ├── types/
│   │   └── bucketeer.ts    # TypeScript type definitions
│   ├── utils/
│   │   └── logger.ts       # Logging utility
│   ├── config.ts           # Configuration management
│   ├── server.ts           # MCP server implementation
│   └── index.ts            # Entry point
├── .env.example            # Environment variables template
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Linting

Run the linter:

npm run lint

Building

Build the TypeScript code:

npm run build

Troubleshooting

Common Issues

Authentication errors: Ensure your API key is valid and has the necessary permissions
Environment ID not found: Verify the environment ID exists in your Bucketeer instance
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.

Bucketeer MCP Server