Cucumber Studio MCP

April 1, 2025 · View on GitHub

MCP (Model Context Protocol) server for integrating Cucumber Studio with AI assistants. This integration allows AI assistants to interact with Cucumber Studio to manage BDD scenarios, projects, folders, and tags.

Features

Comprehensive BDD Management: Access and manage your Cucumber Studio projects, scenarios, folders, and tags
Read-Only Mode: Optional protection to prevent accidental modifications to your BDD assets
Caching Support: Improved performance with configurable caching
Detailed Logging: Configurable logging levels for troubleshooting
API Coverage: Coverage of essential Cucumber Studio operations

Tools

Read-Only Tools (available in all modes)

cucumber_studio_get_projects
- Get all projects from Cucumber Studio
- Inputs:
  - None
- Returns: List of all accessible projects
cucumber_studio_get_project
- Get a specific project by ID
- Inputs:
  - project_id (string): ID of the project to retrieve
- Returns: Project details including name, description, and metadata
cucumber_studio_get_scenarios
- Get all scenarios from a project
- Inputs:
  - project_id (string): ID of the project
  - include_tags (optional boolean): Whether to include tags in the response (default: true)
- Returns: List of scenarios in the project
cucumber_studio_get_scenario
- Get a specific scenario by ID
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario
  - include_tags (optional boolean): Whether to include tags (default: true)
- Returns: Scenario details including steps, tags, and metadata
cucumber_studio_find_scenarios_by_tags
- Find scenarios with specific tags
- Inputs:
  - project_id (string): ID of the project
  - tag_key (string): The tag key to search for
  - tag_value (string): The tag value to search for
  - include_tags (optional boolean): Whether to include tags (default: true)
- Returns: List of matching scenarios
cucumber_studio_get_folders
- Get all folders from a project
- Inputs:
  - project_id (string): ID of the project
- Returns: List of folders in the project

Write Tools (blocked in read-only mode)

cucumber_studio_create_scenario
- Create a new scenario
- Inputs:
  - project_id (string): ID of the project
  - name (string): Name of the scenario
  - description (optional string): Description
  - folder_id (optional string): ID of the folder
  - steps (optional array): Steps for the scenario
  - tags (optional array): Tags to add to the scenario
- Returns: Created scenario details
cucumber_studio_update_scenario
- Update an existing scenario
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario to update
  - name (optional string): New name
  - description (optional string): New description
  - folder_id (optional string): New folder ID
  - steps or definition (optional): New steps or definition
  - tags (optional array): New tags
- Returns: Updated scenario details
cucumber_studio_delete_scenario
- Delete a scenario
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario to delete
- Returns: Operation result
cucumber_studio_add_tag
- Add a tag to a scenario
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario
  - key (string): Tag key
  - value (string): Tag value
- Returns: Added tag details
cucumber_studio_add_tags
- Add multiple tags to a scenario
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario
  - tags (array): Tags to add, each with key and value
- Returns: Operation result
cucumber_studio_update_tag
- Update an existing tag
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario
  - tag_id (string): ID of the tag to update
  - key (string): New tag key
  - value (string): New tag value
- Returns: Updated tag details
cucumber_studio_delete_tag
- Delete a tag from a scenario
- Inputs:
  - project_id (string): ID of the project
  - scenario_id (string): ID of the scenario
  - tag_id (string): ID of the tag to delete
- Returns: Operation result
cucumber_studio_create_folder
- Create a new folder
- Inputs:
  - project_id (string): ID of the project
  - name (string): Name of the folder
  - parent_id (optional number): ID of the parent folder
- Returns: Created folder details
cucumber_studio_update_folder
- Update an existing folder
- Inputs:
  - project_id (string): ID of the project
  - folder_id (string): ID of the folder to update
  - name (optional string): New folder name
  - description (optional string): New description
  - definition (optional string): New definition
  - parent_id (optional number): New parent folder ID
- Returns: Updated folder details
cucumber_studio_delete_folder
- Delete a folder
- Inputs:
  - project_id (string): ID of the project
  - folder_id (string): ID of the folder to delete
- Returns: Operation result

Required Credentials

To use Cucumber Studio MCP, you need to obtain the following credentials:

Access Token: Your Cucumber Studio API access token
Client ID: Your Cucumber Studio client identifier
User ID: Your Cucumber Studio user email/ID

These can be obtained from your Cucumber Studio account settings.

Environment Variables

CUCUMBER_STUDIO_ACCESS_TOKEN (required): Your Cucumber Studio API access token
CUCUMBER_STUDIO_CLIENT_ID (required): Your Cucumber Studio client identifier
CUCUMBER_STUDIO_UID (required): Your Cucumber Studio user email/ID

Optional Environment Variables

# API Configuration
CUCUMBER_STUDIO_BASE_URL=https://studio.cucumberstudio.com/api  # Default URL

# Access Control
CUCUMBER_STUDIO_READ_ONLY_MODE=true  # Default: false

# Logging Configuration
CUCUMBER_STUDIO_LOG_LEVEL=info  # Options: error, warn, info, debug
CUCUMBER_STUDIO_ENABLE_REQUEST_LOGGING=true  # Default: true
CUCUMBER_STUDIO_ENABLE_RESPONSE_LOGGING=false  # Default: false
CUCUMBER_STUDIO_LOG_DIR=./logs  # Directory for log files

# Performance
CUCUMBER_STUDIO_ENABLE_CACHE=true  # Default: true
CUCUMBER_STUDIO_CACHE_TTL_SECONDS=120  # Default: 120 seconds
CUCUMBER_STUDIO_REQUEST_TIMEOUT_MS=30000  # Default: 30 seconds

Setup

Usage with Claude and other AI assistants

The MCP server can be integrated with AI assistants that support the Model Context Protocol, enabling them to interact with your Cucumber Studio projects and scenarios.

{
  "mcpServers": {
    "cucumber-studio": {
      "command": "npx",
      "args": [
        "-y",
        "@anht3889/cucumber-studio-mcp"
      ],
      "env": {
        "CUCUMBER_STUDIO_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>",
        "CUCUMBER_STUDIO_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "CUCUMBER_STUDIO_UID": "<YOUR_UID>",
        "CUCUMBER_STUDIO_READ_ONLY_MODE": "< true / false>"
      }
    }
  }
}

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run with inspector for debugging
npm run inspect

# Run the inspector against the live npm package
npm run inspect-live

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Author

Anh Tran