cucumberstudio-mcp 1.1.0

package/src/mcp-server.ts

@@ -0,0 +1,342 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+
+import { CucumberStudioApiClient } from './api/client.js'
+import { configManager } from './config/settings.js'
+import { SERVER_NAME, SERVER_VERSION, LOG_PREFIX } from './constants.js'
+import { ActionWordTools } from './tools/action-words.js'
+import { ProjectTools } from './tools/projects.js'
+import { ScenarioTools } from './tools/scenarios.js'
+import { TestRunTools } from './tools/test-runs.js'
+import { StderrLogger, getLogLevel } from './utils/logger.js'
+import { validateEnvironment } from './utils/validation.js'
+
+/**
+ * Create and configure a new CucumberStudio MCP Server
+ */
+export function createCucumberStudioMcpServer(): McpServer {
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  })
+
+  // Initialize server tools asynchronously
+  initializeServerTools(server).catch((error) => {
+    console.error('❌ Failed to initialize server tools:', error)
+  })
+
+  return server
+}
+
+/**
+ * Initialize all tools and register them with the server
+ */
+async function initializeServerTools(server: McpServer): Promise<void> {
+  // Validate environment variables
+  validateEnvironment()
+
+  // Load configuration
+  const config = configManager.loadFromEnvironment()
+
+  // Initialize API client
+  const apiLogger = new StderrLogger({ level: getLogLevel(), prefix: LOG_PREFIX })
+  const apiClient = new CucumberStudioApiClient(config, apiLogger)
+
+  // Initialize tool classes
+  const projectTools = new ProjectTools(apiClient)
+  const scenarioTools = new ScenarioTools(apiClient)
+  const actionWordTools = new ActionWordTools(apiClient)
+  const testRunTools = new TestRunTools(apiClient)
+
+  // Register all tools
+  registerProjectTools(server, projectTools)
+  registerScenarioTools(server, scenarioTools)
+  registerActionWordTools(server, actionWordTools)
+  registerTestRunTools(server, testRunTools)
+
+  console.error('✅ CucumberStudio MCP Server tools initialized')
+}
+
+/**
+ * Register project-related tools
+ */
+function registerProjectTools(server: McpServer, projectTools: ProjectTools): void {
+  server.registerTool(
+    'cucumberstudio_list_projects',
+    {
+      description: 'List all projects accessible to the authenticated user',
+      inputSchema: {
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+        filter: z
+          .object({
+            name: z.string().optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await projectTools.listProjects(args || {})
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_get_project',
+    {
+      description: 'Get detailed information about a specific project',
+      inputSchema: {
+        projectId: z.string(),
+      },
+    },
+    async (args) => {
+      return await projectTools.getProject(args)
+    },
+  )
+}
+
+/**
+ * Register scenario-related tools
+ */
+function registerScenarioTools(server: McpServer, scenarioTools: ScenarioTools): void {
+  server.registerTool(
+    'cucumberstudio_list_scenarios',
+    {
+      description: 'List all scenarios in a project',
+      inputSchema: {
+        projectId: z.string(),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+        filter: z
+          .object({
+            name: z.string().optional(),
+            tags: z.string().optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await scenarioTools.listScenarios(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_get_scenario',
+    {
+      description: 'Get detailed information about a specific scenario',
+      inputSchema: {
+        projectId: z.string(),
+        scenarioId: z.string(),
+      },
+    },
+    async (args) => {
+      return await scenarioTools.getScenario(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_find_scenarios_by_tags',
+    {
+      description: 'Find scenarios by tags in a project',
+      inputSchema: {
+        projectId: z.string(),
+        tags: z.string().min(1),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await scenarioTools.findScenariosByTags(args)
+    },
+  )
+}
+
+/**
+ * Register action word-related tools
+ */
+function registerActionWordTools(server: McpServer, actionWordTools: ActionWordTools): void {
+  server.registerTool(
+    'cucumberstudio_list_action_words',
+    {
+      description: 'List all action words (reusable test steps) in a project',
+      inputSchema: {
+        projectId: z.string(),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+        filter: z
+          .object({
+            name: z.string().optional(),
+            tags: z.string().optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await actionWordTools.listActionWords(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_get_action_word',
+    {
+      description: 'Get detailed information about a specific action word',
+      inputSchema: {
+        projectId: z.string(),
+        actionWordId: z.string(),
+      },
+    },
+    async (args) => {
+      return await actionWordTools.getActionWord(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_find_action_words_by_tags',
+    {
+      description: 'Find action words by tags in a project',
+      inputSchema: {
+        projectId: z.string(),
+        tags: z.string().min(1),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await actionWordTools.findActionWordsByTags(args)
+    },
+  )
+}
+
+/**
+ * Register test run-related tools
+ */
+function registerTestRunTools(server: McpServer, testRunTools: TestRunTools): void {
+  server.registerTool(
+    'cucumberstudio_list_test_runs',
+    {
+      description: 'List all test runs in a project',
+      inputSchema: {
+        projectId: z.string(),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+        filter: z
+          .object({
+            name: z.string().optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await testRunTools.listTestRuns(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_get_test_run',
+    {
+      description: 'Get detailed information about a specific test run',
+      inputSchema: {
+        projectId: z.string(),
+        testRunId: z.string(),
+      },
+    },
+    async (args) => {
+      return await testRunTools.getTestRun(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_get_test_executions',
+    {
+      description: 'Get test executions (individual test results) for a test run',
+      inputSchema: {
+        projectId: z.string(),
+        testRunId: z.string(),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await testRunTools.getTestExecutions(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_list_builds',
+    {
+      description: 'List all builds in a project',
+      inputSchema: {
+        projectId: z.string(),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await testRunTools.listBuilds(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_get_build',
+    {
+      description: 'Get detailed information about a specific build',
+      inputSchema: {
+        projectId: z.string(),
+        buildId: z.string(),
+      },
+    },
+    async (args) => {
+      return await testRunTools.getBuild(args)
+    },
+  )
+
+  server.registerTool(
+    'cucumberstudio_list_execution_environments',
+    {
+      description: 'List all execution environments in a project',
+      inputSchema: {
+        projectId: z.string(),
+        pagination: z
+          .object({
+            page: z.number().min(1).optional(),
+            pageSize: z.number().min(1).max(100).optional(),
+          })
+          .optional(),
+      },
+    },
+    async (args) => {
+      return await testRunTools.listExecutionEnvironments(args)
+    },
+  )
+}

package/src/tools/action-words.ts

@@ -0,0 +1,240 @@
+import { Tool, CallToolRequest, CallToolResult, TextContent } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+
+import { CucumberStudioApiClient } from '../api/client.js'
+import { ActionWord } from '../api/types.js'
+import { safeExecute } from '../utils/errors.js'
+import {
+  validateInput,
+  ProjectIdSchema,
+  ActionWordIdSchema,
+  ListParamsSchema,
+  convertToApiParams,
+} from '../utils/validation.js'
+
+const FindActionWordsByTagsSchema = z.object({
+  projectId: ProjectIdSchema,
+  tags: z.string().min(1, 'Tags parameter is required'),
+  pagination: z
+    .object({
+      page: z.number().int().min(1).optional(),
+      pageSize: z.number().int().min(1).max(100).optional(),
+    })
+    .optional(),
+})
+
+export class ActionWordTools {
+  constructor(private apiClient: CucumberStudioApiClient) {}
+
+  /**
+   * Get all available MCP tools for action words
+   */
+  getTools(): Tool[] {
+    return [
+      {
+        name: 'cucumberstudio_list_action_words',
+        description: 'List all action words (reusable test steps) in a project',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: { type: 'string', description: 'The ID of the project' },
+            pagination: {
+              type: 'object',
+              properties: {
+                page: { type: 'number', minimum: 1, description: 'Page number' },
+                pageSize: { type: 'number', minimum: 1, maximum: 100, description: 'Number of items per page' },
+              },
+              additionalProperties: false,
+            },
+            filter: {
+              type: 'object',
+              properties: {
+                name: { type: 'string', description: 'Filter action words by name' },
+                tags: { type: 'string', description: 'Filter action words by tags' },
+              },
+              additionalProperties: false,
+            },
+          },
+          required: ['projectId'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'cucumberstudio_get_action_word',
+        description: 'Get detailed information about a specific action word',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: { type: 'string', description: 'The ID of the project' },
+            actionWordId: { type: 'string', description: 'The ID of the action word to retrieve' },
+          },
+          required: ['projectId', 'actionWordId'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'cucumberstudio_find_action_words_by_tags',
+        description: 'Find action words by tags in a project',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            projectId: { type: 'string', description: 'The ID of the project' },
+            tags: { type: 'string', description: 'Tags to search for (comma-separated)' },
+            pagination: {
+              type: 'object',
+              properties: {
+                page: { type: 'number', minimum: 1, description: 'Page number' },
+                pageSize: { type: 'number', minimum: 1, maximum: 100, description: 'Number of items per page' },
+              },
+              additionalProperties: false,
+            },
+          },
+          required: ['projectId', 'tags'],
+          additionalProperties: false,
+        },
+      },
+    ]
+  }
+
+  /**
+   * Handle tool calls for action word-related operations
+   */
+  async handleToolCall(request: CallToolRequest): Promise<CallToolResult> {
+    switch (request.params.name) {
+      case 'cucumberstudio_list_action_words':
+        return this.listActionWords(request.params.arguments)
+
+      case 'cucumberstudio_get_action_word':
+        return this.getActionWord(request.params.arguments)
+
+      case 'cucumberstudio_find_action_words_by_tags':
+        return this.findActionWordsByTags(request.params.arguments)
+
+      default:
+        throw new Error(`Unknown tool: ${request.params.name}`)
+    }
+  }
+
+  async listActionWords(args: unknown): Promise<CallToolResult> {
+    return safeExecute(async () => {
+      const projectId = validateInput(
+        ProjectIdSchema,
+        (args as Record<string, unknown>)?.projectId,
+        'list_action_words',
+      )
+      const listParams = validateInput(ListParamsSchema, args, 'list_action_words')
+      const apiParams = convertToApiParams(listParams)
+
+      const response = await this.apiClient.getActionWords(projectId, apiParams)
+
+      const actionWords = Array.isArray(response.data) ? response.data : [response.data]
+      const actionWordList = actionWords.map((actionWord: ActionWord) => ({
+        id: actionWord.id,
+        name: actionWord.attributes.name,
+        description: actionWord.attributes.description || '',
+        definition: actionWord.attributes.definition || '',
+        created_at: actionWord.attributes.created_at,
+        updated_at: actionWord.attributes.updated_at,
+      }))
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                action_words: actionWordList,
+                meta: response.meta || {},
+                total_count: actionWordList.length,
+              },
+              null,
+              2,
+            ),
+          } as TextContent,
+        ],
+      }
+    }, 'listing action words')
+  }
+
+  async getActionWord(args: unknown): Promise<CallToolResult> {
+    return safeExecute(async () => {
+      const projectId = validateInput(ProjectIdSchema, (args as Record<string, unknown>)?.projectId, 'get_action_word')
+      const actionWordId = validateInput(
+        ActionWordIdSchema,
+        (args as Record<string, unknown>)?.actionWordId,
+        'get_action_word',
+      )
+
+      const response = await this.apiClient.getActionWord(projectId, actionWordId)
+
+      const actionWord = response.data
+      const actionWordDetails = {
+        id: actionWord.id,
+        type: actionWord.type,
+        name: actionWord.attributes.name,
+        description: actionWord.attributes.description || '',
+        definition: actionWord.attributes.definition || '',
+        created_at: actionWord.attributes.created_at,
+        updated_at: actionWord.attributes.updated_at,
+        relationships: actionWord.relationships || {},
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                action_word: actionWordDetails,
+                included: response.included || [],
+              },
+              null,
+              2,
+            ),
+          } as TextContent,
+        ],
+      }
+    }, 'getting action word details')
+  }
+
+  async findActionWordsByTags(args: unknown): Promise<CallToolResult> {
+    return safeExecute(async () => {
+      const { projectId, tags, pagination } = validateInput(
+        FindActionWordsByTagsSchema,
+        args,
+        'find_action_words_by_tags',
+      )
+      const apiParams = convertToApiParams({ pagination })
+
+      const response = await this.apiClient.findActionWordsByTag(projectId, tags, apiParams)
+
+      const actionWords = Array.isArray(response.data) ? response.data : [response.data]
+      const actionWordList = actionWords.map((actionWord: ActionWord) => ({
+        id: actionWord.id,
+        name: actionWord.attributes.name,
+        description: actionWord.attributes.description || '',
+        definition: actionWord.attributes.definition || '',
+        created_at: actionWord.attributes.created_at,
+        updated_at: actionWord.attributes.updated_at,
+      }))
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                action_words: actionWordList,
+                search_tags: tags,
+                meta: response.meta || {},
+                total_count: actionWordList.length,
+              },
+              null,
+              2,
+            ),
+          } as TextContent,
+        ],
+      }
+    }, 'finding action words by tags')
+  }
+}