@testomatio/mcp 1.0.13 → 2.0.0-beta.8

package/src/mcp/registry/issues.js

@@ -0,0 +1,106 @@
+import { ISSUE_RESOURCE_KEYS } from '../configs/issues-config.js';
+
+export const issueMethods = {
+  listIssues({ page, per_page: perPage, source, ...resourceQuery } = {}) {
+    this.validateIssueResourceQuery(resourceQuery, { allowEmpty: true, allowMany: false });
+    return this.listIssuesForResource({
+      ...resourceQuery,
+      page,
+      per_page: perPage,
+      source,
+    });
+  },
+
+  searchIssues(args = {}) {
+    return this.listIssues(args);
+  },
+
+  createIssue({ url, jira_id: jiraId, ...resourceQuery } = {}) {
+    this.validateIssueResourceQuery(resourceQuery, { allowEmpty: false, allowMany: false });
+    return this.linkIssueToResource({
+      ...resourceQuery,
+      url,
+      jira_id: jiraId,
+    });
+  },
+
+  listIssuesForResource({ page, per_page: perPage, source, ...resourceQuery } = {}) {
+    return this.apiClient.list('issues', {
+      ...resourceQuery,
+      page,
+      per_page: perPage,
+      source,
+    });
+  },
+
+  listIssuesForKey({ resourceKey, resourceId, page, per_page: perPage, source }) {
+    this.assertSupportedIssueResourceKey(resourceKey);
+    return this.listIssuesForResource({
+      [resourceKey]: resourceId,
+      page,
+      per_page: perPage,
+      source,
+    });
+  },
+
+  linkIssueForKey({ resourceKey, resourceId, url, jira_id: jiraId }) {
+    this.assertSupportedIssueResourceKey(resourceKey);
+    return this.linkIssueToResource({
+      [resourceKey]: resourceId,
+      url,
+      jira_id: jiraId,
+    });
+  },
+
+  linkIssueToResource({ url, jira_id: jiraId, ...resourceQuery } = {}) {
+    if (Boolean(url) === Boolean(jiraId)) {
+      throw new Error('Provide exactly one field: "url" or "jira_id".');
+    }
+    this.validateIssueResourceQuery(resourceQuery, { allowEmpty: false, allowMany: false });
+
+    const payload = { url, jira_id: jiraId };
+    return this.createIssueWithFallback(resourceQuery, payload);
+  },
+
+  async createIssueWithFallback(resourceQuery, payload) {
+    try {
+      return await this.apiClient.createWithQuery('issues', {
+        query: resourceQuery,
+        body: payload,
+      });
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, 'issue')) {
+        throw error;
+      }
+      return this.apiClient.createWithQuery('issues', {
+        query: resourceQuery,
+        body: { issue: payload },
+      });
+    }
+  },
+
+  assertSupportedIssueResourceKey(resourceKey) {
+    if (!ISSUE_RESOURCE_KEYS.includes(resourceKey)) {
+      throw new Error(`Unsupported issue resource key: ${resourceKey}`);
+    }
+  },
+
+  validateIssueResourceQuery(resourceQuery = {}, { allowEmpty = false, allowMany = false } = {}) {
+    const provided = ISSUE_RESOURCE_KEYS.filter((key) => {
+      const value = resourceQuery[key];
+      return value !== undefined && value !== null && value !== '';
+    });
+
+    if (!allowEmpty && provided.length === 0) {
+      throw new Error(`Provide one resource id: ${ISSUE_RESOURCE_KEYS.join(', ')}.`);
+    }
+
+    if (!allowMany && provided.length > 1) {
+      throw new Error(
+        `Provide only one resource id at a time: ${ISSUE_RESOURCE_KEYS.join(', ')}.`
+      );
+    }
+
+    return provided;
+  },
+};

package/src/mcp/registry/listings.js

@@ -0,0 +1,108 @@
+export const listingMethods = {
+  listTests({ page, per_page: perPage, suite_id: suiteId, search_text: searchText, query, ...filters } = {}) {
+    return this.apiClient.list('tests', {
+      page,
+      per_page: perPage,
+      suite_id: suiteId,
+      search_text: searchText || query,
+      ...filters,
+    });
+  },
+
+  searchTests({ query, search_text: searchText, ...rest } = {}) {
+    return this.listTests({
+      ...rest,
+      search_text: searchText || query,
+    });
+  },
+
+  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, query } = {}) {
+    return this.apiClient.list('suites', {
+      page,
+      per_page: perPage,
+      file_type: fileType,
+      tag,
+      labels,
+      search_text: searchText || query,
+    });
+  },
+
+  searchSuites({ query, search_text: searchText, ...rest } = {}) {
+    return this.listSuites({
+      ...rest,
+      search_text: searchText || query,
+    });
+  },
+
+  listRuns({ page, per_page: perPage, query } = {}) {
+    return this.apiClient.list('runs', { page, per_page: perPage, query });
+  },
+
+  searchRuns({ page, per_page: perPage, query } = {}) {
+    return this.listRuns({ page, per_page: perPage, query });
+  },
+
+  listTestruns({ page, per_page: perPage, run_id: runId, query } = {}) {
+    return this.apiClient.list('testruns', { page, per_page: perPage, run_id: runId, query });
+  },
+
+  searchTestruns({ page, per_page: perPage, run_id: runId, query } = {}) {
+    return this.listTestruns({ page, per_page: perPage, run_id: runId, query });
+  },
+
+  listRungroups({ page, per_page: perPage, query } = {}) {
+    return this.apiClient.list('rungroups', { page, per_page: perPage, query });
+  },
+
+  searchRungroups({ page, per_page: perPage, query } = {}) {
+    return this.listRungroups({ page, per_page: perPage, query });
+  },
+
+  listSteps({ page, per_page: perPage, query } = {}) {
+    return this.apiClient.list('steps', { page, per_page: perPage, query });
+  },
+
+  searchSteps({ page, per_page: perPage, query } = {}) {
+    return this.listSteps({ page, per_page: perPage, query });
+  },
+
+  listSnippets({ page, per_page: perPage, query } = {}) {
+    return this.apiClient.list('snippets', { page, per_page: perPage, query });
+  },
+
+  searchSnippets({ page, per_page: perPage, query } = {}) {
+    return this.listSnippets({ page, per_page: perPage, query });
+  },
+
+  listLabels({ page, per_page: perPage, query } = {}) {
+    return this.apiClient.list('labels', { page, per_page: perPage, query });
+  },
+
+  searchLabels({ page, per_page: perPage, query } = {}) {
+    return this.listLabels({ page, per_page: perPage, query });
+  },
+
+  listPlans({ page, per_page: perPage, query } = {}) {
+    return this.apiClient.list('plans', { page, per_page: perPage, query });
+  },
+
+  searchPlans({ page, per_page: perPage, query } = {}) {
+    return this.listPlans({ page, per_page: perPage, query });
+  },
+
+  listTags() {
+    return this.apiClient.list('tags');
+  },
+
+  getTagByTitle(tagId) {
+    return this.apiClient.get('tags', tagId);
+  },
+
+  searchTags({ tag_id: tagId, query } = {}) {
+    const resolvedTag = tagId || query;
+    if (!resolvedTag) {
+      throw new Error('Provide "tag_id" or "query" for tags_search.');
+    }
+    return this.getTagByTitle(resolvedTag);
+  },
+};

package/src/mcp/registry/payloads.js

@@ -0,0 +1,269 @@
+export const payloadMethods = {
+  async createWrapped(resource, wrapperKey, payload) {
+    const wrappedBody = { [wrapperKey]: payload };
+    try {
+      return await this.apiClient.create(resource, payload);
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
+        throw error;
+      }
+      return this.apiClient.create(resource, wrappedBody);
+    }
+  },
+
+  async updateWrapped(resource, id, wrapperKey, payload) {
+    const wrappedBody = { [wrapperKey]: payload };
+    try {
+      return await this.apiClient.update(resource, id, payload);
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
+        throw error;
+      }
+      return this.apiClient.update(resource, id, wrappedBody);
+    }
+  },
+
+  buildTestPayload({
+    title,
+    suite_id: suiteId,
+    description,
+    emoji,
+    priority,
+    assigned_to: assignedTo,
+    code,
+    state,
+    sync,
+    link,
+  } = {}) {
+    return {
+      title,
+      suite_id: suiteId,
+      description,
+      emoji,
+      priority,
+      assigned_to: assignedTo,
+      code,
+      state,
+      sync,
+      link,
+    };
+  },
+
+  buildSuitePayload({
+    title,
+    description,
+    emoji,
+    parent_id: parentId,
+    file_type: fileType,
+    assigned_to: assignedTo,
+    file,
+    children,
+    link,
+  } = {}) {
+    return {
+      title,
+      description,
+      emoji,
+      parent_id: parentId,
+      file_type: fileType,
+      assigned_to: assignedTo,
+      file,
+      children,
+      link,
+    };
+  },
+
+  buildRunCreatePayload({
+    title,
+    description,
+    plan_id: planId,
+    kind,
+    rungroup_id: rungroupId,
+    env,
+    assigned_to: assignedTo,
+    assign_strategy: assignStrategy,
+    test_ids: testIds,
+    suite_ids: suiteIds,
+    envs,
+    configuration,
+    link,
+  } = {}) {
+    return {
+      title,
+      description,
+      plan_id: planId,
+      kind,
+      rungroup_id: rungroupId,
+      env,
+      assigned_to: assignedTo,
+      assign_strategy: assignStrategy,
+      test_ids: testIds,
+      suite_ids: suiteIds,
+      envs,
+      configuration,
+      link,
+    };
+  },
+
+  buildRunUpdatePayload({
+    title,
+    description,
+    plan_id: planId,
+    kind,
+    rungroup_id: rungroupId,
+    env,
+    status_event: statusEvent,
+    assigned_to: assignedTo,
+    assign_strategy: assignStrategy,
+    test_ids: testIds,
+    suite_ids: suiteIds,
+    configuration,
+    link,
+  } = {}) {
+    return {
+      title,
+      description,
+      plan_id: planId,
+      kind,
+      rungroup_id: rungroupId,
+      env,
+      status_event: statusEvent,
+      assigned_to: assignedTo,
+      assign_strategy: assignStrategy,
+      test_ids: testIds,
+      suite_ids: suiteIds,
+      configuration,
+      link,
+    };
+  },
+
+  async createRunWithFallback(args = {}) {
+    const payload = this.buildRunCreatePayload(args);
+    try {
+      return await this.apiClient.create('runs', payload);
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, 'run')) {
+        throw error;
+      }
+      return this.apiClient.create('runs', { run: payload });
+    }
+  },
+
+  async updateRunWithFallback(runId, args = {}) {
+    const payload = this.buildRunUpdatePayload(args);
+    try {
+      return await this.apiClient.update('runs', runId, payload);
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, 'run')) {
+        throw error;
+      }
+      return this.apiClient.update('runs', runId, { run: payload });
+    }
+  },
+
+  shouldRetryWrappedBody(error, wrapperKey) {
+    if (!error || ![400, 422].includes(error.status)) {
+      return false;
+    }
+    const payload = error.payload || {};
+    const blob = JSON.stringify(payload).toLowerCase();
+    const key = wrapperKey.toLowerCase();
+
+    const mentionsMissingParam =
+      blob.includes('param is missing') ||
+      blob.includes('missing required') ||
+      blob.includes('is required');
+
+    return blob.includes(key) && mentionsMissingParam;
+  },
+
+  buildTestrunPayload({
+    run_id: runId,
+    test_id: testId,
+    status,
+    message,
+    run_time: runTime,
+    assigned_to: assignedTo,
+    test_title: testTitle,
+    automated,
+  } = {}) {
+    return {
+      run_id: runId,
+      test_id: testId,
+      status,
+      message,
+      run_time: runTime,
+      assigned_to: assignedTo,
+      test_title: testTitle,
+      automated,
+    };
+  },
+
+  buildRungroupPayload({
+    title,
+    description,
+    emoji,
+    kind,
+    pin,
+    status,
+    parent_id: parentId,
+    children,
+  } = {}) {
+    return {
+      title,
+      description,
+      emoji,
+      kind,
+      pin,
+      status,
+      parent_id: parentId,
+      children,
+    };
+  },
+
+  buildStepPayload({ title, description, link } = {}) {
+    return {
+      title,
+      description,
+      link,
+    };
+  },
+
+  buildSnippetPayload({ title, description, link } = {}) {
+    return {
+      title,
+      description,
+      link,
+    };
+  },
+
+  buildLabelPayload({ title, color, visibility, scope, field } = {}) {
+    return {
+      title,
+      color,
+      visibility,
+      scope,
+      field,
+    };
+  },
+
+  buildPlanPayload({
+    title,
+    description,
+    kind,
+    hidden,
+    as_manual: asManual,
+    test_plan: testPlan,
+    link,
+  } = {}) {
+    return {
+      title,
+      description,
+      kind,
+      hidden,
+      as_manual: asManual,
+      test_plan: testPlan,
+      link,
+    };
+  },
+};

package/src/mcp/server.js

@@ -0,0 +1,49 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { TOOL_DEFINITIONS } from './tool-definitions.js';
+import { ToolRegistry } from './tool-registry.js';
+import { createLogger } from '../core/logger.js';
+import { getPackageVersion } from '../config/package-version.js';
+
+export class TestomatioMCPServer {
+  constructor({ config, apiClient, logger }) {
+    this.config = config;
+    this.logger = logger || createLogger();
+    this.toolRegistry = new ToolRegistry({ config, apiClient, logger: this.logger });
+
+    this.server = new Server(
+      {
+        name: 'testomatio-mcp-server',
+        version: getPackageVersion(),
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: TOOL_DEFINITIONS,
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const toolName = request.params.name;
+      const args = request.params.arguments || {};
+      this.logger.info('Tool call', { toolName });
+
+      return this.toolRegistry.execute(toolName, args);
+    });
+  }
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    this.logger.info('Testomatio MCP server started');
+  }
+}

package/src/mcp/tool-definitions.js

@@ -0,0 +1,27 @@
+import { SYSTEM_TOOLS } from './definitions/system.js';
+import { TESTS_TOOLS } from './definitions/tests.js';
+import { SUITES_TOOLS } from './definitions/suites.js';
+import { RUNS_TOOLS } from './definitions/runs.js';
+import { TESTRUNS_TOOLS } from './definitions/testruns.js';
+import { RUNGROUPS_TOOLS } from './definitions/rungroups.js';
+import { STEPS_TOOLS } from './definitions/steps.js';
+import { SNIPPETS_TOOLS } from './definitions/snippets.js';
+import { LABELS_TOOLS } from './definitions/labels.js';
+import { TAGS_TOOLS } from './definitions/tags.js';
+import { ISSUES_TOOLS } from './definitions/issues.js';
+import { PLANS_TOOLS } from './definitions/plans.js';
+
+export const TOOL_DEFINITIONS = [
+  ...SYSTEM_TOOLS,
+  ...TESTS_TOOLS,
+  ...SUITES_TOOLS,
+  ...RUNS_TOOLS,
+  ...TESTRUNS_TOOLS,
+  ...RUNGROUPS_TOOLS,
+  ...STEPS_TOOLS,
+  ...SNIPPETS_TOOLS,
+  ...LABELS_TOOLS,
+  ...TAGS_TOOLS,
+  ...ISSUES_TOOLS,
+  ...PLANS_TOOLS,
+];

package/src/mcp/tool-registry.js

@@ -0,0 +1,81 @@
+import { DEFAULT_TOOL_RESPONSE } from '../config/constants.js';
+import { ApiError, NotImplementedToolError } from '../core/errors.js';
+import { textResponse } from '../helpers/mcp-response.js';
+import { TOOL_DEFINITIONS } from './tool-definitions.js';
+import { handlerMethods } from './registry/handlers.js';
+import { issueMethods } from './registry/issues.js';
+import { listingMethods } from './registry/listings.js';
+import { payloadMethods } from './registry/payloads.js';
+
+function formatJson(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+export class ToolRegistry {
+  constructor({ config, apiClient, logger }) {
+    this.config = config;
+    this.apiClient = apiClient;
+    this.logger = logger;
+    this.handlers = this.buildHandlers();
+  }
+
+  asText(payload) {
+    return textResponse(formatJson(payload));
+  }
+
+  buildHandlers() {
+    const handlers = {
+      system_ping: async () =>
+        this.asText({
+          status: 'ok',
+          projectId: this.config.projectId,
+          baseUrl: this.config.baseUrl,
+          apiVersion: 'v2',
+        }),
+    };
+
+    this.registerEntityCrudHandlers(handlers);
+    this.registerScopedIssueHandlers(handlers);
+    this.registerGlobalHandlers(handlers);
+
+    for (const tool of TOOL_DEFINITIONS) {
+      if (tool.name === 'system_ping') continue;
+      if (!handlers[tool.name]) {
+        handlers[tool.name] = async () => textResponse(`${DEFAULT_TOOL_RESPONSE} (${tool.name})`);
+      }
+    }
+
+    return handlers;
+  }
+
+  async execute(name, args = {}) {
+    const handler = this.handlers[name];
+    if (!handler) {
+      throw new NotImplementedToolError(name);
+    }
+
+    try {
+      return await handler(args);
+    } catch (error) {
+      if (error instanceof ApiError) {
+        return this.asText({
+          error: error.message,
+          status: error.status,
+          url: error.url,
+          details: error.payload || null,
+        });
+      }
+
+      this.logger?.error('Unhandled tool execution error', { name, error: error?.message || error });
+      return this.asText({ error: error?.message || 'Unknown execution error' });
+    }
+  }
+}
+
+Object.assign(
+  ToolRegistry.prototype,
+  handlerMethods,
+  listingMethods,
+  issueMethods,
+  payloadMethods
+);