cucumberstudio-mcp 1.1.0

package/.env.example

@@ -0,0 +1,36 @@
+# Cucumber Studio API Configuration
+# Get these values from your Cucumber Studio account settings
+
+# Your Cucumber Studio access token
+CUCUMBERSTUDIO_ACCESS_TOKEN=your_access_token_here
+
+# Your Cucumber Studio client ID
+CUCUMBERSTUDIO_CLIENT_ID=your_client_id_here
+
+# Your Cucumber Studio UID
+CUCUMBERSTUDIO_UID=your_uid_here
+
+# Optional: Custom base URL (defaults to https://studio.cucumberstudio.com/api)
+# CUCUMBERSTUDIO_BASE_URL=https://studio.cucumberstudio.com/api
+
+# Optional: MCP Server Configuration
+# MCP_SERVER_NAME=cucumberstudio-mcp
+# MCP_SERVER_VERSION=1.0.0
+
+# Transport Configuration
+# MCP_TRANSPORT=stdio  # Options: stdio, http, streamable-http
+# MCP_PORT=3000        # Port for HTTP transport
+# MCP_HOST=127.0.0.1   # Host for HTTP transport
+# MCP_CORS_ORIGIN=true # CORS origin setting for HTTP transport
+
+# Logging Configuration
+# LOG_LEVEL=info             # Options: error, warn, info, debug, trace
+# LOG_API_RESPONSES=false    # Log Cucumber Studio API responses
+# LOG_REQUEST_BODIES=false   # Log API request bodies (for debugging)
+# LOG_RESPONSE_BODIES=false  # Log API response bodies (for debugging)
+
+# Optional: Performance and Limits Configuration
+# API_TIMEOUT=30000          # API request timeout in milliseconds (default: 30000)
+# MAX_PAGE_SIZE=100          # Maximum items per page for list operations (default: 100)
+# JSON_BODY_LIMIT=10mb       # Maximum JSON body size for HTTP transport (default: 10mb)
+# CORS_ORIGINS=localhost,127.0.0.1,0.0.0.0  # Comma-separated list of allowed CORS origins

package/.github/workflows/pr-checks.yml

@@ -0,0 +1,41 @@
+name: PR Checks
+
+on:
+  pull_request:
+    branches: [ master, main ]
+  push:
+    branches: [ master, main ]
+
+jobs:
+  quality-checks:
+    name: Quality Checks
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x]
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Run TypeScript type checking
+        run: npm run typecheck
+        
+      - name: Run ESLint
+        run: npm run lint
+        
+      - name: Run tests
+        run: npm test
+        
+      - name: Run build check
+        run: npm run build

package/.github/workflows/release.yml

@@ -0,0 +1,194 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*' # Trigger on version tags like v1.0.0, v1.2.3, etc.
+
+permissions:
+  contents: write
+  packages: write
+  actions: read
+  pull-requests: write
+  issues: write
+  repository-projects: write
+
+env:
+  NODE_VERSION: '20'
+  REGISTRY: docker.io
+  IMAGE_NAME: herosizy/cucumberstudio-mcp
+
+jobs:
+  test:
+    name: Test and Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run type checking
+        run: npm run typecheck
+
+      - name: Run linting
+        run: npm run lint
+
+      - name: Run tests
+        run: npm run test:coverage
+
+      - name: Build project
+        run: npm run build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts
+          path: build/
+          retention-days: 1
+
+  publish-npm:
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: build-artifacts
+          path: build/
+
+      - name: Extract version from tag
+        id: get_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Update package.json version
+        run: |
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          TARGET_VERSION=${{ steps.get_version.outputs.VERSION }}
+          if [ "$CURRENT_VERSION" != "$TARGET_VERSION" ]; then
+            echo "Updating version from $CURRENT_VERSION to $TARGET_VERSION"
+            npm version $TARGET_VERSION --no-git-tag-version
+          else
+            echo "Version $TARGET_VERSION already matches package.json, skipping update"
+          fi
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-docker:
+    name: Publish to Docker Hub
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: get_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=tag
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [publish-npm, publish-docker]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: get_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          if [ -f CHANGELOG.md ]; then
+            echo "CHANGELOG<<EOF" >> $GITHUB_OUTPUT
+            sed -n "/## \[${{ steps.get_version.outputs.VERSION }}\]/,/## \[/p" CHANGELOG.md | head -n -1 >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+          else
+            echo "CHANGELOG=Release ${{ steps.get_version.outputs.VERSION }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: Release ${{ steps.get_version.outputs.VERSION }}
+          body: |
+            ## Changes in v${{ steps.get_version.outputs.VERSION }}
+            
+            ${{ steps.changelog.outputs.CHANGELOG }}
+            
+            ## Installation
+            
+            ### NPM
+            ```bash
+            npx cucumberstudio-mcp
+            ```
+            
+            ### Docker
+            ```bash
+            docker run --env-file .env ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.get_version.outputs.VERSION }}
+            ```
+            
+            ## Links
+            - [NPM Package](https://www.npmjs.com/package/cucumberstudio-mcp)
+            - [Docker Image](https://hub.docker.com/r/${{ env.IMAGE_NAME }})
+          draft: false
+          prerelease: false

package/.prettierignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+build/
+dist/
+
+# Coverage
+coverage/
+
+# Config files
+package-lock.json
+*.md
+*.json
+
+# Docker
+Dockerfile*
+docker-compose*.yml
+
+# Git
+.git/
+.gitignore
+
+# IDE
+.vscode/
+.idea/

package/.prettierrc

@@ -0,0 +1,14 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 120,
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "embeddedLanguageFormatting": "auto"
+}

package/CLAUDE.md

@@ -0,0 +1,140 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a CucumberStudio MCP (Model Context Protocol) project. MCP servers provide standardized interfaces for AI assistants to interact with external systems and data sources.
+
+## Development Commands
+
+- `npm install` - Install dependencies
+- `npm run build` - Build TypeScript to JavaScript
+- `npm run dev` - Run the server in development mode with tsx
+- `npm start` - Run the built server
+- `npm run lint` - Run ESLint
+- `npm run typecheck` - Run TypeScript type checking
+- `npm test` - Run tests once
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Run tests with coverage report
+
+### Docker Commands
+- `npm run docker:build` - Build production Docker image
+- `npm run docker:build:dev` - Build development Docker image
+- `npm run docker:run` - Run production container
+- `npm run docker:run:dev` - Run development container with hot reload
+- `npm run docker:compose:up` - Start with docker-compose
+- `npm run docker:compose:up:dev` - Start development environment
+- `npm run docker:compose:down` - Stop docker-compose services
+
+### Transport Options
+- **STDIO** (default): `npm start` or `MCP_TRANSPORT=stdio npm start`
+- **HTTP/Streamable HTTP**: `npm run start:http` or `MCP_TRANSPORT=http npm start`
+- **Development HTTP**: `npm run dev:http` or `MCP_TRANSPORT=http npm run dev`
+
+## Architecture
+
+The MCP server is built with TypeScript and follows a clean, modular architecture:
+
+- **Entry Point**: `src/index.ts` - Main entry point with transport selection using enum-based switch cases
+- **Server Factory**: `src/mcp-server.ts` - Direct McpServer creation with tool registration
+- **Configuration**: `src/config/settings.ts` - Environment-based configuration management
+- **Transports**: `src/transports/` - Transport layer implementations
+  - `stdio.ts` - Standard input/output transport (default)
+  - `http.ts` - Streamable HTTP transport with session management
+  - `index.ts` - Transport exports, types, and enums
+- **API Client**: `src/api/client.ts` - Cucumber Studio API client with authentication
+- **Tool Modules**: `src/tools/` - MCP tool implementations organized by feature
+  - `projects.ts` - Project management tools
+  - `scenarios.ts` - Scenario retrieval tools  
+  - `action-words.ts` - Action word (reusable steps) tools
+  - `test-runs.ts` - Test execution and build tools
+- **Utilities**: `src/utils/` - Error handling and validation utilities
+
+## MCP Server Development Notes
+
+- MCP servers implement the Model Context Protocol specification
+- Servers typically expose tools, resources, and prompts to MCP clients
+- Common patterns include resource discovery, tool execution, and state management
+- Follow MCP specification for proper server implementation
+- **SDK Version**: Uses MCP TypeScript SDK v1.12.3+ with modern `McpServer` class and `registerTool` pattern
+- **Implementation**: Uses modern `McpServer.registerTool()` method for clean tool registration with Zod validation
+- **Architecture**: Direct McpServer usage without unnecessary wrapper classes
+
+## Key Resources
+
+- MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
+- MCP Specifications for LLMs: https://modelcontextprotocol.io/llms.txt
+- Cucumber Studio API Documentation: https://studio-api.cucumberstudio.com/#introduction
+- Cucumber Studio API Reference (GitHub): https://github.com/SmartBear/cucumberstudio-api-documentation/tree/master/source/includes
+
+## Technical Implementation
+
+### MCP SDK Integration
+- **Server Class**: Uses `Server` from `@modelcontextprotocol/sdk/server/index.js`
+- **Transport**: Uses `StdioServerTransport` from `@modelcontextprotocol/sdk/server/stdio.js`
+- **Request Handlers**: Implements `ListToolsRequestSchema` and `CallToolRequestSchema` handlers
+- **Tool Registration**: Tools are registered through request handlers, not direct registration
+- **Capabilities**: Server declares `tools: {}` capability to MCP clients
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Main entry point with transport selection
+├── server.ts             # MCP server class and tool handler setup
+├── config/
+│   └── settings.ts       # Configuration management with Zod validation
+├── transports/
+│   ├── index.ts          # Transport exports and types
+│   ├── stdio.ts          # Standard input/output transport
+│   └── http.ts           # Streamable HTTP transport with session management
+├── api/
+│   ├── client.ts         # Cucumber Studio API client with authentication
+│   └── types.ts          # TypeScript types for API responses
+├── tools/
+│   ├── projects.ts       # Project retrieval tools
+│   ├── scenarios.ts      # Scenario and folder tools
+│   ├── action-words.ts   # Action word (reusable steps) tools
+│   └── test-runs.ts      # Test run, execution, and build tools
+└── utils/
+    ├── errors.ts         # MCP error handling utilities
+    └── validation.ts     # Input validation with Zod schemas
+```
+
+## Available MCP 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
+
+## Environment Setup
+
+Copy `.env.example` to `.env` and configure your Cucumber Studio API credentials:
+- `CUCUMBERSTUDIO_ACCESS_TOKEN` - Your API access token
+- `CUCUMBERSTUDIO_CLIENT_ID` - Your client ID  
+- `CUCUMBERSTUDIO_UID` - Your user ID
+
+### Transport Configuration
+- `MCP_TRANSPORT` - Transport type: `stdio` (default), `http`, or `streamable-http`
+- `MCP_PORT` - HTTP transport port (default: 3000)
+- `MCP_HOST` - HTTP transport host (default: 127.0.0.1)
+- `MCP_CORS_ORIGIN` - CORS origin setting (default: true)

package/Dockerfile

@@ -0,0 +1,50 @@
+# Stage 1: Build stage
+FROM node:20-alpine AS builder
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files and scripts
+COPY package*.json ./
+COPY scripts/ ./scripts/
+
+# Install all dependencies (including dev dependencies for build)
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Stage 2: Production stage
+FROM node:20-alpine AS production
+
+# Install dumb-init for proper signal handling
+RUN apk add --no-cache dumb-init
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S mcpserver -u 1001
+
+# Set working directory
+WORKDIR /app
+
+# Copy built application from builder stage
+COPY --from=builder --chown=mcpserver:nodejs /app/build ./build
+
+# Switch to non-root user
+USER mcpserver
+
+# Expose port for HTTP transport
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "console.log('MCP Server is healthy')" || exit 1
+
+# Use dumb-init to handle signals properly
+ENTRYPOINT ["dumb-init", "--"]
+
+# Start the server
+CMD ["node", "build/index.js"]

package/Dockerfile.dev

@@ -0,0 +1,31 @@
+# Development Dockerfile with hot reload
+FROM node:20-alpine
+
+# Set working directory
+WORKDIR /app
+
+# Install global dependencies for development
+RUN npm install -g tsx nodemon
+
+# Copy package files
+COPY package*.json ./
+
+# Install all dependencies (including dev dependencies)
+RUN npm install
+
+# Copy source code
+COPY . .
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S mcpserver -u 1001
+
+# Change ownership of the app directory
+RUN chown -R mcpserver:nodejs /app
+USER mcpserver
+
+# Expose port for development/debugging
+EXPOSE 3000
+
+# Development command with hot reload
+CMD ["npm", "run", "dev"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cucumber Studio MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.