cucumberstudio-mcp 1.1.0

package/src/api/client.ts

@@ -0,0 +1,286 @@
+import axios, { AxiosInstance, AxiosResponse } from 'axios'
+
+import { Config } from '../config/settings.js'
+import { API_VERSION_HEADER, API_TIMEOUT, REDACTED_STRING } from '../constants.js'
+import { Logger } from '../utils/logger.js'
+
+import {
+  CucumberStudioResponse,
+  CucumberStudioError,
+  ListParams,
+  Project,
+  Scenario,
+  ActionWord,
+  Folder,
+  TestRun,
+  TestExecution,
+  Build,
+  ExecutionEnvironment,
+} from './types.js'
+
+export class CucumberStudioApiError extends Error {
+  constructor(
+    message: string,
+    public status?: number,
+    public details?: CucumberStudioError,
+  ) {
+    super(message)
+    this.name = 'CucumberStudioApiError'
+  }
+}
+
+export class CucumberStudioApiClient {
+  private client: AxiosInstance
+
+  constructor(
+    private config: Config,
+    private logger: Logger,
+  ) {
+    this.client = axios.create({
+      baseURL: config.cucumberStudio.baseUrl,
+      headers: {
+        Accept: API_VERSION_HEADER,
+        'Content-Type': 'application/json',
+        'access-token': config.cucumberStudio.accessToken,
+        client: config.cucumberStudio.clientId,
+        uid: config.cucumberStudio.uid,
+      },
+      timeout: API_TIMEOUT,
+    })
+
+    // Add request interceptor for logging
+    this.client.interceptors.request.use(
+      (config) => {
+        this.logger.debug(`🚀 Request: ${config.method?.toUpperCase()} ${config.url}`, {
+          headers: this.sanitizeHeaders(config.headers),
+          params: config.params,
+          bodySize: config.data ? JSON.stringify(config.data).length : 0,
+        })
+
+        if (this.getLoggingConfig().logRequestBodies && config.data) {
+          this.logger.trace('📤 Request Body:', config.data)
+        }
+
+        return config
+      },
+      (error) => {
+        this.logger.error('❌ Request Error:', error)
+        return Promise.reject(error)
+      },
+    )
+
+    // Add response interceptor for logging and error handling
+    this.client.interceptors.response.use(
+      (response) => {
+        this.logger.debug(
+          `✅ Response: ${response.status} ${response.config.method?.toUpperCase()} ${response.config.url}`,
+          {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            dataSize: response.data ? JSON.stringify(response.data).length : 0,
+          },
+        )
+
+        if (this.getLoggingConfig().logApiResponses || this.getLoggingConfig().logResponseBodies) {
+          this.logger.debug('📥 Cucumber Studio Response:', {
+            status: response.status,
+            url: response.config.url,
+            data: response.data,
+          })
+        }
+
+        return response
+      },
+      (error) => {
+        if (error.response) {
+          const status = error.response.status
+          const data = error.response.data as CucumberStudioError
+
+          this.logger.error(`❌ API Error: ${status} ${error.config?.method?.toUpperCase()} ${error.config?.url}`, {
+            status,
+            statusText: error.response.statusText,
+            data,
+            headers: error.response.headers,
+          })
+
+          let message = `API request failed with status ${status}`
+          if (data?.errors?.length > 0) {
+            message = data.errors.map((e) => e.detail).join('; ')
+          }
+
+          throw new CucumberStudioApiError(message, status, data)
+        } else if (error.request) {
+          this.logger.error('🔌 No Response:', {
+            url: error.config?.url,
+            timeout: error.code === 'ECONNABORTED',
+          })
+          throw new CucumberStudioApiError('No response received from Cucumber Studio API')
+        } else {
+          this.logger.error('⚙️ Request Setup Error:', error.message)
+          throw new CucumberStudioApiError(`Request setup failed: ${error.message}`)
+        }
+      },
+    )
+  }
+
+  /**
+   * Get logging configuration with safe defaults
+   */
+  private getLoggingConfig() {
+    return (
+      this.config.logging || {
+        level: 'info' as const,
+        logApiResponses: false,
+        logRequestBodies: false,
+        logResponseBodies: false,
+      }
+    )
+  }
+
+  /**
+   * Sanitize headers to avoid logging sensitive information
+   */
+  private sanitizeHeaders(headers: Record<string, unknown>): Record<string, unknown> {
+    if (!headers) return headers
+
+    const sanitized = { ...headers }
+    const sensitiveKeys = ['access-token', 'authorization', 'cookie', 'x-api-key']
+
+    for (const key of sensitiveKeys) {
+      if (key in sanitized) {
+        sanitized[key] = REDACTED_STRING
+      }
+    }
+
+    return sanitized
+  }
+
+  /**
+   * Generic GET request handler
+   */
+  private async get<T>(endpoint: string, params?: Record<string, unknown>): Promise<CucumberStudioResponse<T>> {
+    const response: AxiosResponse<CucumberStudioResponse<T>> = await this.client.get(endpoint, { params })
+    return response.data
+  }
+
+  // PROJECT ENDPOINTS
+  async getProjects(params?: ListParams): Promise<CucumberStudioResponse<Project[]>> {
+    return this.get<Project[]>('/projects', params)
+  }
+
+  async getProject(projectId: string): Promise<CucumberStudioResponse<Project>> {
+    return this.get<Project>(`/projects/${projectId}`)
+  }
+
+  // SCENARIO ENDPOINTS
+  async getScenarios(projectId: string, params?: ListParams): Promise<CucumberStudioResponse<Scenario[]>> {
+    return this.get<Scenario[]>(`/projects/${projectId}/scenarios`, params)
+  }
+
+  async getScenario(projectId: string, scenarioId: string): Promise<CucumberStudioResponse<Scenario>> {
+    return this.get<Scenario>(`/projects/${projectId}/scenarios/${scenarioId}`)
+  }
+
+  async findScenariosByTag(
+    projectId: string,
+    tags: string,
+    params?: ListParams,
+  ): Promise<CucumberStudioResponse<Scenario[]>> {
+    return this.get<Scenario[]>(`/projects/${projectId}/scenarios/find_by_tags`, {
+      ...params,
+      'filter[tags]': tags,
+    })
+  }
+
+  // ACTION WORD ENDPOINTS
+  async getActionWords(projectId: string, params?: ListParams): Promise<CucumberStudioResponse<ActionWord[]>> {
+    return this.get<ActionWord[]>(`/projects/${projectId}/actionwords`, params)
+  }
+
+  async getActionWord(projectId: string, actionWordId: string): Promise<CucumberStudioResponse<ActionWord>> {
+    return this.get<ActionWord>(`/projects/${projectId}/actionwords/${actionWordId}`)
+  }
+
+  async findActionWordsByTag(
+    projectId: string,
+    tags: string,
+    params?: ListParams,
+  ): Promise<CucumberStudioResponse<ActionWord[]>> {
+    return this.get<ActionWord[]>(`/projects/${projectId}/actionwords/find_by_tags`, {
+      ...params,
+      'filter[tags]': tags,
+    })
+  }
+
+  // FOLDER ENDPOINTS
+  async getFolders(projectId: string, params?: ListParams): Promise<CucumberStudioResponse<Folder[]>> {
+    return this.get<Folder[]>(`/projects/${projectId}/folders`, params)
+  }
+
+  async getFolder(projectId: string, folderId: string): Promise<CucumberStudioResponse<Folder>> {
+    return this.get<Folder>(`/projects/${projectId}/folders/${folderId}`)
+  }
+
+  async getFolderChildren(
+    projectId: string,
+    folderId: string,
+    params?: ListParams,
+  ): Promise<CucumberStudioResponse<Folder[]>> {
+    return this.get<Folder[]>(`/projects/${projectId}/folders/${folderId}/children`, params)
+  }
+
+  async getFolderScenarios(
+    projectId: string,
+    folderId: string,
+    params?: ListParams,
+  ): Promise<CucumberStudioResponse<Scenario[]>> {
+    return this.get<Scenario[]>(`/projects/${projectId}/folders/${folderId}/scenarios`, params)
+  }
+
+  // TEST RUN ENDPOINTS
+  async getTestRuns(projectId: string, params?: ListParams): Promise<CucumberStudioResponse<TestRun[]>> {
+    return this.get<TestRun[]>(`/projects/${projectId}/test_runs`, params)
+  }
+
+  async getTestRun(projectId: string, testRunId: string): Promise<CucumberStudioResponse<TestRun>> {
+    return this.get<TestRun>(`/projects/${projectId}/test_runs/${testRunId}`)
+  }
+
+  async getTestExecutions(
+    projectId: string,
+    testRunId: string,
+    params?: ListParams,
+  ): Promise<CucumberStudioResponse<TestExecution[]>> {
+    return this.get<TestExecution[]>(`/projects/${projectId}/test_runs/${testRunId}/test_executions`, params)
+  }
+
+  // BUILD ENDPOINTS
+  async getBuilds(projectId: string, params?: ListParams): Promise<CucumberStudioResponse<Build[]>> {
+    return this.get<Build[]>(`/projects/${projectId}/builds`, params)
+  }
+
+  async getBuild(projectId: string, buildId: string): Promise<CucumberStudioResponse<Build>> {
+    return this.get<Build>(`/projects/${projectId}/builds/${buildId}`)
+  }
+
+  // EXECUTION ENVIRONMENT ENDPOINTS
+  async getExecutionEnvironments(
+    projectId: string,
+    params?: ListParams,
+  ): Promise<CucumberStudioResponse<ExecutionEnvironment[]>> {
+    return this.get<ExecutionEnvironment[]>(`/projects/${projectId}/execution_environments`, params)
+  }
+
+  /**
+   * Test the connection to Cucumber Studio API
+   */
+  async testConnection(): Promise<boolean> {
+    try {
+      await this.getProjects({ 'page[size]': 1 })
+      return true
+    } catch {
+      return false
+    }
+  }
+}

package/src/api/types.ts

@@ -0,0 +1,137 @@
+// Common API response structure for Cucumber Studio
+export interface CucumberStudioResponse<T = unknown> {
+  data: T
+  included?: Record<string, unknown>[]
+  meta?: {
+    count?: number
+    total_count?: number
+  }
+}
+
+// Base attributes common to many resources
+export interface BaseAttributes {
+  id: string
+  type: string
+  attributes: Record<string, unknown>
+  relationships?: Record<string, unknown>
+}
+
+// Project related types
+export interface Project extends BaseAttributes {
+  type: 'projects'
+  attributes: {
+    name: string
+    description?: string
+    created_at: string
+    updated_at: string
+  }
+}
+
+// Scenario related types
+export interface Scenario extends BaseAttributes {
+  type: 'scenarios'
+  attributes: {
+    name: string
+    description?: string
+    definition?: string
+    created_at: string
+    updated_at: string
+    folder_id?: string
+  }
+}
+
+// Action Word related types
+export interface ActionWord extends BaseAttributes {
+  type: 'actionwords'
+  attributes: {
+    name: string
+    description?: string
+    definition?: string
+    created_at: string
+    updated_at: string
+  }
+}
+
+// Folder related types
+export interface Folder extends BaseAttributes {
+  type: 'folders'
+  attributes: {
+    name: string
+    description?: string
+    created_at: string
+    updated_at: string
+    parent_id?: string
+  }
+}
+
+// Test Run related types
+export interface TestRun extends BaseAttributes {
+  type: 'test_runs'
+  attributes: {
+    name: string
+    description?: string
+    created_at: string
+    updated_at: string
+    execution_environment?: string
+  }
+}
+
+// Test Execution related types
+export interface TestExecution extends BaseAttributes {
+  type: 'test_executions'
+  attributes: {
+    status: 'passed' | 'failed' | 'wip' | 'retest' | 'blocked' | 'skipped' | 'undefined'
+    created_at: string
+    updated_at: string
+    scenario_id: string
+    test_run_id: string
+  }
+}
+
+// Build related types
+export interface Build extends BaseAttributes {
+  type: 'builds'
+  attributes: {
+    name: string
+    description?: string
+    created_at: string
+    updated_at: string
+  }
+}
+
+// Execution Environment related types
+export interface ExecutionEnvironment extends BaseAttributes {
+  type: 'execution_environments'
+  attributes: {
+    name: string
+    description?: string
+    created_at: string
+    updated_at: string
+  }
+}
+
+// Tag related types
+export interface Tag extends BaseAttributes {
+  type: 'tags'
+  attributes: {
+    key: string
+    value?: string
+  }
+}
+
+// API Error structure
+export interface CucumberStudioError {
+  errors: Array<{
+    detail: string
+    status: string
+    title: string
+  }>
+}
+
+// Query parameters for list endpoints
+export interface ListParams extends Record<string, unknown> {
+  'page[number]'?: number
+  'page[size]'?: number
+  'filter[name]'?: string
+  'filter[tags]'?: string
+}

package/src/config/settings.ts

@@ -0,0 +1,113 @@
+import { config as loadDotenv } from 'dotenv'
+import { z } from 'zod'
+
+import {
+  SERVER_NAME,
+  SERVER_VERSION,
+  DEFAULT_API_BASE_URL,
+  DEFAULT_PORT,
+  DEFAULT_HOST,
+  DEFAULT_LOG_LEVEL,
+} from '../constants.js'
+
+// Configuration schema for type safety and validation
+const ConfigSchema = z.object({
+  cucumberStudio: z.object({
+    baseUrl: z.string().url().default(DEFAULT_API_BASE_URL),
+    accessToken: z.string().min(1),
+    clientId: z.string().min(1),
+    uid: z.string().min(1),
+  }),
+  server: z.object({
+    name: z.string().default(SERVER_NAME),
+    version: z.string().default(SERVER_VERSION),
+    transport: z.enum(['stdio', 'http', 'streamable-http']).default('stdio'),
+    port: z.number().int().min(1).max(65535).default(DEFAULT_PORT),
+    host: z.string().default(DEFAULT_HOST),
+  }),
+  logging: z.object({
+    level: z.enum(['error', 'warn', 'info', 'debug', 'trace']).default(DEFAULT_LOG_LEVEL as 'info'),
+    logApiResponses: z.boolean().default(false),
+    logRequestBodies: z.boolean().default(false),
+    logResponseBodies: z.boolean().default(false),
+    transport: z.enum(['console', 'file', 'stderr', 'none']).default('stderr'),
+    filePath: z.string().optional(),
+  }),
+})
+
+export type Config = z.infer<typeof ConfigSchema>
+
+export class ConfigManager {
+  private config: Config | null = null
+
+  /**
+   * Load configuration from environment variables
+   */
+  public loadFromEnvironment(): Config {
+    // Auto-load .env file if it exists
+    loadDotenv({ path: '.env' })
+    const rawConfig = {
+      cucumberStudio: {
+        baseUrl: process.env.CUCUMBERSTUDIO_BASE_URL,
+        accessToken: process.env.CUCUMBERSTUDIO_ACCESS_TOKEN,
+        clientId: process.env.CUCUMBERSTUDIO_CLIENT_ID,
+        uid: process.env.CUCUMBERSTUDIO_UID,
+      },
+      server: {
+        name: process.env.MCP_SERVER_NAME,
+        version: process.env.MCP_SERVER_VERSION,
+        transport: process.env.MCP_TRANSPORT,
+        port: process.env.MCP_PORT ? parseInt(process.env.MCP_PORT, 10) : undefined,
+        host: process.env.MCP_HOST,
+      },
+      logging: {
+        level: process.env.LOG_LEVEL,
+        logApiResponses: process.env.LOG_API_RESPONSES === 'true',
+        logRequestBodies: process.env.LOG_REQUEST_BODIES === 'true',
+        logResponseBodies: process.env.LOG_RESPONSE_BODIES === 'true',
+        transport: process.env.LOG_TRANSPORT,
+        filePath: process.env.LOG_FILE,
+      },
+    }
+
+    try {
+      this.config = ConfigSchema.parse(rawConfig)
+      return this.config
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        const missingFields = error.errors.map((e) => e.path.join('.')).join(', ')
+        throw new Error(
+          `Configuration validation failed. Missing or invalid fields: ${missingFields}. ` +
+            'Please ensure all required environment variables are set: ' +
+            'CUCUMBERSTUDIO_ACCESS_TOKEN, CUCUMBERSTUDIO_CLIENT_ID, CUCUMBERSTUDIO_UID',
+        )
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Get current configuration
+   */
+  public getConfig(): Config {
+    if (!this.config) {
+      throw new Error('Configuration not loaded. Call loadFromEnvironment() first.')
+    }
+    return this.config
+  }
+
+  /**
+   * Validate that all required configuration is present
+   */
+  public validate(): boolean {
+    try {
+      this.getConfig()
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+// Singleton instance
+export const configManager = new ConfigManager()

package/src/constants.ts

@@ -0,0 +1,29 @@
+// Import build-time generated version
+import { PACKAGE_VERSION, PACKAGE_NAME } from './generated/version.js'
+
+// Server Configuration
+export const SERVER_NAME = PACKAGE_NAME
+export const SERVER_VERSION = PACKAGE_VERSION // Build-time constant from package.json
+export const PROTOCOL_VERSION = '2025-03-26' // MCP protocol version
+
+// API Configuration
+export const API_VERSION_HEADER = 'application/vnd.api+json; version=1'
+export const API_TIMEOUT = 30000 // 30 seconds
+export const DEFAULT_API_BASE_URL = 'https://studio.cucumberstudio.com/api'
+
+// Network Configuration
+export const DEFAULT_PORT = 3000
+export const DEFAULT_HOST = '0.0.0.0'
+export const JSON_BODY_LIMIT = '10mb'
+export const DEFAULT_CORS_ORIGINS = ['localhost', '127.0.0.1', '0.0.0.0']
+
+// Pagination
+export const MAX_PAGE_SIZE = 100
+export const DEFAULT_PAGE_SIZE = 20
+
+// Security
+export const REDACTED_STRING = '***REDACTED***'
+
+// Logger
+export const LOG_PREFIX = '🥒 API'
+export const DEFAULT_LOG_LEVEL = 'info'

package/src/index.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { config as loadDotenv } from 'dotenv'
+
+import { createCucumberStudioMcpServer } from './mcp-server.js'
+import { StreamableHttpTransport, TransportType } from './transports/index.js'
+import { StderrLogger, getLogLevel } from './utils/logger.js'
+
+/**
+ * Main entry point for the Cucumber Studio MCP Server
+ * Supports both STDIO and HTTP transports based on environment variables
+ */
+async function main(): Promise<void> {
+  // Load .env file first to ensure environment variables are available
+  loadDotenv({ path: '.env' })
+
+  // Determine transport based on environment variable
+  const transportString = process.env.MCP_TRANSPORT?.toLowerCase() || 'stdio'
+  const transport = Object.values(TransportType).includes(transportString as TransportType)
+    ? (transportString as TransportType)
+    : TransportType.STDIO
+
+  const port = parseInt(process.env.MCP_PORT || '3000', 10)
+  const host = process.env.MCP_HOST || '127.0.0.1'
+
+  console.error(`🎯 Starting Cucumber Studio MCP Server with ${transport} transport...`)
+
+  try {
+    switch (transport) {
+      case TransportType.HTTP:
+      case TransportType.STREAMABLE_HTTP: {
+        // HTTP/Streamable HTTP transport
+        const httpLogger = new StderrLogger({ level: getLogLevel(), prefix: '🌐 HTTP' })
+        const httpTransport = new StreamableHttpTransport(
+          createCucumberStudioMcpServer,
+          {
+            port,
+            host,
+            cors: {
+              origin: process.env.MCP_CORS_ORIGIN === 'false' ? false : true,
+              credentials: true,
+            },
+          },
+          httpLogger,
+        )
+
+        await httpTransport.start()
+
+        // Handle graceful shutdown for HTTP transport
+        const shutdown = async () => {
+          console.error('🛑 Shutting down HTTP transport...')
+          await httpTransport.close()
+          process.exit(0)
+        }
+
+        process.on('SIGINT', shutdown)
+        process.on('SIGTERM', shutdown)
+        break
+      }
+
+      case TransportType.STDIO:
+      default: {
+        // STDIO transport (default)
+        const server = createCucumberStudioMcpServer()
+        const stdioTransport = new StdioServerTransport()
+
+        console.error('🚀 CucumberStudio MCP Server running on stdio')
+        console.error('📡 Transport: STDIO (standard input/output)')
+        console.error('🔄 Protocol: MCP')
+
+        await server.connect(stdioTransport)
+        break
+      }
+    }
+  } catch (error) {
+    console.error(`❌ ${transport} transport failed to start:`, error)
+    process.exit(1)
+  }
+}
+
+// Handle graceful shutdown for STDIO transport
+process.on('SIGINT', () => {
+  console.error('🛑 Received SIGINT, shutting down gracefully...')
+  process.exit(0)
+})
+
+process.on('SIGTERM', () => {
+  console.error('🛑 Received SIGTERM, shutting down gracefully...')
+  process.exit(0)
+})
+
+// Run if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error('❌ Unhandled error:', error)
+    process.exit(1)
+  })
+}