cucumberstudio-mcp

Name: cucumberstudio-mcp
Availability: InStock
Author: Si Zengyu

MCP Server for Cucumber Studio

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

Cucumber Studio MCP Server

Vibe Coded with Claude Code and Pu-Er 🍵

A Model Context Protocol (MCP) server that provides LLM access to Cucumber Studio's testing platform. This server enables AI assistants to retrieve test scenarios, action words, test runs, and project information from Cucumber Studio.

Features

Dual Transport Support - STDIO and Streamable HTTP transports with session management
Project Management - List and retrieve project details
Scenario Access - Browse test scenarios and search by tags
Action Words - Access reusable test steps and definitions
Test Execution - View test runs, executions, and build information
Hot Reload Development - Instant server restart on file changes with tsx --watch
Configurable Logging - Structured logging with multiple output destinations
Comprehensive Error Handling - Robust error handling with detailed feedback
Type Safety - Full TypeScript implementation with Zod validation
Comprehensive Testing - 82%+ test coverage with Vitest and MSW

Installation

Desktop Extension (DXT) Installation

The easiest way to use this MCP server is as a Desktop Extension:

Download Extension: Get the latest .dxt file from the releases page (automatically built from each release)
Install Extension: Import the extension in your compatible AI desktop application
Configure Credentials: Set up your Cucumber Studio API credentials through the extension settings:
- Access Token: Your Cucumber Studio API access token
- Client ID: Your Cucumber Studio client ID
- User ID: Your Cucumber Studio user ID

The extension will automatically handle the MCP server setup and communication.

Quick Start (Command Line)

Run directly with npx (no installation required):

npx cucumberstudio-mcp

Set your environment variables first:

export CUCUMBERSTUDIO_ACCESS_TOKEN="your_token"
export CUCUMBERSTUDIO_CLIENT_ID="your_client_id"
export CUCUMBERSTUDIO_UID="your_uid"

Development Installation

Clone the repository:

git clone https://github.com/HeroSizy/cucumberstudio-mcp.git
cd cucumberstudio-mcp

Install dependencies:

npm install

Set up environment variables:

cp .env.example .env
# Edit .env with your Cucumber Studio API credentials

Build the server:

npm run build

Docker Support

Using Pre-built Image (Recommended)

Run the official Docker image from Docker Hub:

# With environment file
docker run --env-file .env herosizy/cucumberstudio-mcp

# With environment variables
docker run -e CUCUMBERSTUDIO_ACCESS_TOKEN=your_token \
           -e CUCUMBERSTUDIO_CLIENT_ID=your_client_id \
           -e CUCUMBERSTUDIO_UID=your_uid \
           herosizy/cucumberstudio-mcp

Using Docker Compose

Set up environment variables:

cp .env.example .env
# Edit .env with your Cucumber Studio API credentials

Update docker-compose.yml to use the pre-built image:

version: '3.8'
services:
  cucumberstudio-mcp:
    image: herosizy/cucumberstudio-mcp
    env_file:
      - .env
    restart: unless-stopped
    ports:
      - "${MCP_PORT:-3000}:3000"

Run with Docker Compose:

docker-compose up

Building Locally

Build the image:

npm run docker:build

Run the container:

npm run docker:run

The Docker setup includes health checks and automatic restarts for production use. The multi-stage build process creates optimized production images with only runtime dependencies (~150MB).

Configuration

The server requires Cucumber Studio API credentials. Get these from your Cucumber Studio account settings:

Required Environment Variables

CUCUMBERSTUDIO_ACCESS_TOKEN - Your API access token
CUCUMBERSTUDIO_CLIENT_ID - Your client ID
CUCUMBERSTUDIO_UID - Your user ID

Optional Configuration

CUCUMBERSTUDIO_BASE_URL - API base URL (default: https://studio.cucumberstudio.com/api)
MCP_TRANSPORT - Transport type: stdio (default), http, or streamable-http
MCP_PORT - HTTP transport port (default: 3000)
MCP_HOST - HTTP transport host (default: 0.0.0.0)
MCP_CORS_ORIGIN - CORS origin setting (default: true)

Logging Configuration

LOG_LEVEL - Log level: error, warn, info, debug, trace (default: info)
LOG_API_RESPONSES - Log Cucumber Studio API responses (default: false)
LOG_REQUEST_BODIES - Log API request bodies for debugging (default: false)
LOG_RESPONSE_BODIES - Log API response bodies for debugging (default: false)
LOG_TRANSPORT - Logging output: console, stderr, file, none (default: stderr)
LOG_FILE - Log file path (required if LOG_TRANSPORT=file)

Usage

Transport Options

The server supports both STDIO and HTTP transports:

STDIO Transport (Default)

# Development
npm run dev

# Production
npm start

HTTP Transport

# Development
npm run dev:http

# Production
npm run start:http

Using with MCP Clients

Desktop Extension (Recommended)

Import the .dxt extension file directly into your compatible AI desktop application. The extension handles all configuration through its settings interface.

Manual MCP Configuration

For manual MCP client configuration:

Option 1: NPX (Recommended)

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "npx",
      "args": ["cucumberstudio-mcp"],
      "env": {
        "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token",
        "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id",
        "CUCUMBERSTUDIO_UID": "your_uid"
      }
    }
  }
}

Option 2: Local Installation

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "node",
      "args": ["/path/to/cucumberstudio-mcp/build/index.js"],
      "env": {
        "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token",
        "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id",
        "CUCUMBERSTUDIO_UID": "your_uid"
      }
    }
  }
}

Option 3: Docker Hub Image

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "herosizy/cucumberstudio-mcp"]
    }
  }
}

Option 4: Local Docker Build

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "cucumberstudio-mcp"]
    }
  }
}

Available Tools

Project Tools

cucumberstudio_list_projects - List all accessible projects
cucumberstudio_get_project - Get detailed project information

Scenario Tools

cucumberstudio_list_scenarios - List scenarios in a project
cucumberstudio_get_scenario - Get detailed scenario information
cucumberstudio_find_scenarios_by_tags - Find scenarios by tags

Action Word Tools

cucumberstudio_list_action_words - List reusable action words
cucumberstudio_get_action_word - Get detailed action word information
cucumberstudio_find_action_words_by_tags - Find action words by tags

Test Execution Tools

cucumberstudio_list_test_runs - List test runs
cucumberstudio_get_test_run - Get detailed test run information
cucumberstudio_get_test_executions - Get individual test results
cucumberstudio_list_builds - List builds
cucumberstudio_get_build - Get build details
cucumberstudio_list_execution_environments - List execution environments

Development

Hot Reload Development

The server supports hot reload for rapid development:

# STDIO transport with hot reload
npm run dev

# HTTP transport with hot reload  
npm run dev:http

Files are automatically recompiled and the server restarts when changes are detected.

Testing and Quality

# Install dependencies
npm install

# Run type checking
npm run typecheck

# Run linting
npm run lint

# Build for production
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage (82%+ coverage)
npm run test:coverage

# Run tests with UI
npm run test:ui

Build Options

# Production build (default) - optimized for size, no .d.ts/.js.map files
npm run build

# Development build - includes source maps and type declarations for debugging
npm run build:dev

DXT Extension Development

# Validate manifest.json
npm run dxt:validate

# Build complete DXT extension for local testing (optimized production build)
npm run dxt:build

# Check info about built extension
npm run dxt:info

# Clean up build artifacts
npm run dxt:clean

Architecture

The server is built with a modular, production-ready architecture:

Core Technologies

TypeScript - Full type safety with strict configuration
Dual Transports - STDIO for local use, Streamable HTTP for remote access
Zod - Runtime validation for API inputs and configuration
Axios - HTTP client with comprehensive error handling and logging
MCP SDK - Official Model Context Protocol implementation
Express - HTTP server with CORS, security middleware, and session management
Vitest - Modern testing framework with 82%+ code coverage
MSW - Mock Service Worker for realistic API testing

Key Features

Session Management - HTTP transport with session tracking and cleanup
Comprehensive Logging - Structured logging with configurable outputs and levels
Error Handling - Robust error handling with detailed feedback and recovery
Security - Origin validation, CORS protection, and input sanitization
Health Monitoring - Health check endpoints and request/response tracking
Development Workflow - Hot reload, comprehensive testing, and Docker support

Testing

The project includes comprehensive test coverage:

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

Test coverage includes:

Unit tests for all modules
Integration tests for the MCP server
Transport layer testing
API client mocking and testing
Configuration validation
Error handling scenarios

Publishing and Releases

This project uses automated releases via GitHub Actions. When a version tag is pushed, it automatically:

Runs full test suite - Ensures code quality and coverage
Publishes to NPM - Makes the package available via npx cucumberstudio-mcp
Builds and publishes Docker image - Pushes multi-platform images to Docker Hub
Creates GitHub release - Generates release notes and links