@testomatio/mcp 2.0.0 → 2.0.1-beta.1

package/src/mcp/definitions/tests.js

@@ -1,7 +1,9 @@
+import { TESTS_TQL_INPUT_DESCRIPTION, TESTS_TQL_REFERENCE } from './tql-reference.js';
+
 export const TESTS_TOOLS = [
   {
     "name": "tests_list",
-    "description": "List tests (/api/v2/{project_id}/tests)",
+    "description": `List tests (/api/v2/{project_id}/tests). ${TESTS_TQL_REFERENCE}`,
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -14,23 +16,9 @@ export const TESTS_TOOLS = [
           "minimum": 1,
           "maximum": 100
         },
-        "suite_id": {
-          "type": "string"
-        },
-        "search_text": {
-          "type": "string"
-        },
-        "query": {
-          "type": "string"
-        },
-        "assigned_to": {
-          "type": "string"
-        },
-        "priority": {
-          "type": "string"
-        },
-        "state": {
-          "type": "string"
+        "tql": {
+          "type": "string",
+          "description": TESTS_TQL_INPUT_DESCRIPTION
         }
       },
       "additionalProperties": false
@@ -100,6 +88,7 @@ export const TESTS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -178,6 +167,7 @@ export const TESTS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -219,16 +209,10 @@ export const TESTS_TOOLS = [
   },
   {
     "name": "tests_search",
-    "description": "Search tests by text (delegates to tests list with search_text)",
+    "description": `Search tests using TQL (delegates to tests_list). ${TESTS_TQL_REFERENCE}`,
     "inputSchema": {
       "type": "object",
       "properties": {
-        "query": {
-          "type": "string"
-        },
-        "search_text": {
-          "type": "string"
-        },
         "page": {
           "type": "integer",
           "minimum": 1
@@ -238,17 +222,9 @@ export const TESTS_TOOLS = [
           "minimum": 1,
           "maximum": 100
         },
-        "suite_id": {
-          "type": "string"
-        },
-        "assigned_to": {
-          "type": "string"
-        },
-        "priority": {
-          "type": "string"
-        },
-        "state": {
-          "type": "string"
+        "tql": {
+          "type": "string",
+          "description": TESTS_TQL_INPUT_DESCRIPTION
         }
       },
       "additionalProperties": false

package/src/mcp/definitions/tql-reference.js

@@ -0,0 +1,133 @@
+const TESTS_TQL_VARIABLES = [
+  'tag',
+  'label',
+  'priority',
+  'issue',
+  'jira',
+  'state',
+  'status',
+  'custom_status',
+  'created_at',
+  'updated_at',
+  'last_run_at',
+  'executed_at',
+  'created_by',
+  'assigned_to',
+  'suite',
+  'test',
+];
+
+const RUNS_TQL_VARIABLES = [
+  'title',
+  'plan',
+  'rungroup',
+  'env',
+  'tag',
+  'label',
+  'jira',
+  'duration',
+  'passed_count',
+  'failed_count',
+  'skipped_count',
+  'automated',
+  'manual',
+  'mixed',
+  'finished',
+  'unfinished',
+  'passed',
+  'failed',
+  'terminated',
+  'published',
+  'private',
+  'archived',
+  'unarchived',
+  'with_defect',
+  'has_defect',
+  'has_test',
+  'has_test_tag',
+  'has_test_label',
+  'has_suite',
+  'has_message',
+  'has_custom_status',
+  'has_assigned_to',
+  'has_retries',
+  'has_test_duration',
+  'has_priority',
+  'created_at',
+  'updated_at',
+  'launched_at',
+  'finished_at',
+];
+
+const TESTS_TQL_EXAMPLES = [
+  "priority == 'high'",
+  "state == 'automated'",
+  "tag in ['smoke', 'stage1'] and status == 'failed'",
+  "suite % 'Checkout'",
+  "test % 'User login'",
+  "created_at < 1.month_ago",
+  "jira in ['JST-1', 'JST-2']",
+];
+
+const RUNS_TQL_EXAMPLES = [
+  "title % 'Manual tests'",
+  "plan == '{PLAN_ID}'",
+  "env in ['Windows', 'Linux']",
+  "failed and has_test_tag == 'regression'",
+  'finished and with_defect',
+  'has_retries > 2',
+  "automated and env == 'Production' and has_message % 'Server Error'",
+  "finished_at >= '2025-07-01' and finished_at <= '2025-07-31' and failed",
+];
+
+const COMMON_TQL_SYNTAX =
+  "Supported syntax includes `==`, `!=`, `>`, `<`, `>=`, `<=`, `in [...]`, `%` for partial text match, `and`, `or`, `not`, and parentheses for grouping. Use quotes for string values, for example `state == 'automated'`.";
+
+export const TESTS_TQL_REFERENCE =
+  `TQL (Testomat.io Query Language) is a string expression passed in \`tql\` to filter tests. ${COMMON_TQL_SYNTAX} ` +
+  `Documented test variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  'Do not invent undocumented fields or syntax. If a query fails, simplify it to one documented predicate.';
+
+export const TESTS_TQL_INPUT_DESCRIPTION =
+  `TQL filter for tests. Documented variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}.`;
+
+export const RUNS_TQL_REFERENCE =
+  `TQL (Testomat.io Query Language) is a string expression passed in \`tql\` to filter runs. ${COMMON_TQL_SYNTAX} ` +
+  'Runs also support boolean flags without comparison such as `failed`, `finished`, `automated`, or `with_defect`. ' +
+  `Documented run variables: ${RUNS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented examples: ${RUNS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  'Do not invent undocumented fields or syntax. If a query fails, simplify it to one documented predicate.';
+
+export const RUNS_TQL_INPUT_DESCRIPTION =
+  `TQL filter for runs. Documented variables: ${RUNS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Examples: ${RUNS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}.`;
+
+export const ANALYTICS_TESTS_TQL_REFERENCE =
+  `TQL (Testomat.io Query Language) is a string expression passed in \`q\` to filter enterprise analytics test reports. ${COMMON_TQL_SYNTAX} ` +
+  'For analytics tools, the API parameter name is `q`, not `tql`. ' +
+  `Documented analytics test variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  'Do not invent undocumented fields or syntax. If a query fails, simplify it to one documented predicate.';
+
+export const ANALYTICS_TESTS_TQL_INPUT_DESCRIPTION =
+  'TQL filter for analytics test reports. The API parameter name is `q`, not `tql`. ' +
+  `Documented variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}.`;
+
+export const ANALYTICS_STATS_TQL_REFERENCE =
+  `TQL (Testomat.io Query Language) is a string expression passed in \`q\` to filter enterprise analytics aggregated reports. ${COMMON_TQL_SYNTAX} ` +
+  'For analytics tools, the API parameter name is `q`, not `tql`. ' +
+  'According to the official Analytics docs, analytics queries are configured using supported query variables for two data sources: `Tests Variables` and `Runs Variables`. ' +
+  `Documented Tests Variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented Runs Variables: ${RUNS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented Tests examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented Runs examples: ${RUNS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  'Use Tests Variables for test-centric filters and Runs Variables for run-centric filters such as `plan`, `rungroup`, `env`, `finished_at`, or `has_test_tag`. Do not invent undocumented fields or syntax. If a query fails, simplify it to one documented predicate.';
+
+export const ANALYTICS_STATS_TQL_INPUT_DESCRIPTION =
+  'TQL filter for analytics aggregated reports. The API parameter name is `q`, not `tql`. ' +
+  `Documented Tests Variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Documented Runs Variables: ${RUNS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
+  `Examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}, ${RUNS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}.`;

package/src/mcp/registry/handlers.js

@@ -8,8 +8,10 @@ export const handlerMethods = {
 
       handlers[`${toolPrefix}_list`] = async (args = {}) =>
         this.asText(await this[listMethod](args));
-      handlers[`${toolPrefix}_search`] = async (args = {}) =>
-        this.asText(await this[searchMethod](args));
+      if (searchMethod) {
+        handlers[`${toolPrefix}_search`] = async (args = {}) =>
+          this.asText(await this[searchMethod](args));
+      }
       handlers[`${toolPrefix}_get`] = async (args = {}) =>
         this.asText(await this.apiClient.get(resource, this.pickRequiredArg(args, idArg)));
       handlers[`${toolPrefix}_create`] = async (args = {}) =>
@@ -57,6 +59,10 @@ export const handlerMethods = {
     handlers.tags_get = async ({ tag_id: tagId }) => this.asText(await this.getTagByTitle(tagId));
     handlers.tags_search = async (args = {}) => this.asText(await this.searchTags(args));
 
+    handlers.milestones_list = async (args = {}) => this.asText(await this.listMilestones(args));
+    handlers.milestones_get = async ({ milestone_id: milestoneId }) =>
+      this.asText(await this.apiClient.get('milestones', milestoneId));
+
     handlers.issues_list = async (args = {}) => this.asText(await this.listIssues(args));
     handlers.issues_search = async (args = {}) => this.asText(await this.searchIssues(args));
     handlers.issues_create = async (args = {}) => this.asText(await this.createIssue(args));
@@ -82,6 +88,9 @@ export const handlerMethods = {
     if (spec.createMode === 'run') {
       return this.createRunWithFallback(args);
     }
+    if (spec.createMode === 'requirement') {
+      return this.createRequirement(args);
+    }
     const payload = this[spec.payloadBuilder](args);
     return this.createWrapped(spec.resource, spec.wrapperKey, payload);
   },
@@ -90,7 +99,13 @@ export const handlerMethods = {
     if (spec.updateMode === 'run') {
       return this.updateRunWithFallback(id, args);
     }
+    if (spec.updateMode === 'requirement') {
+      return this.updateRequirement(id, args);
+    }
     const payload = this[spec.payloadBuilder](args);
+    if (spec.updateMethod === 'patch') {
+      return this.patchWrapped(spec.resource, id, spec.wrapperKey, payload);
+    }
     return this.updateWrapped(spec.resource, id, spec.wrapperKey, payload);
   },
 };

package/src/mcp/registry/listings.js

@@ -1,93 +1,151 @@
 export const listingMethods = {
-  listTests({ page, per_page: perPage, suite_id: suiteId, search_text: searchText, query, ...filters } = {}) {
+  listTests({
+    page,
+    per_page: perPage,
+    tql,
+  } = {}) {
     return this.apiClient.list('tests', {
       page,
       per_page: perPage,
-      suite_id: suiteId,
-      search_text: searchText || query,
-      ...filters,
+      tql,
     });
   },
 
-  searchTests({ query, search_text: searchText, ...rest } = {}) {
+  searchTests({ page, per_page: perPage, tql } = {}) {
     return this.listTests({
-      ...rest,
-      search_text: searchText || query,
+      page,
+      per_page: perPage,
+      tql,
     });
   },
 
-  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, query } = {}) {
+  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText } = {}) {
     return this.apiClient.list('suites', {
       page,
       per_page: perPage,
       file_type: fileType,
       tag,
       labels,
-      search_text: searchText || query,
+      search_text: searchText,
     });
   },
 
-  searchSuites({ query, search_text: searchText, ...rest } = {}) {
+  searchSuites({ search_text: searchText, ...rest } = {}) {
     return this.listSuites({
       ...rest,
-      search_text: searchText || query,
+      search_text: searchText,
     });
   },
 
-  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 });
+  listRuns({
+    page,
+    per_page: perPage,
+    tql,
+  } = {}) {
+    return this.apiClient.list('runs', {
+      page,
+      per_page: perPage,
+      tql,
+    });
   },
 
-  searchTestruns({ page, per_page: perPage, run_id: runId, query } = {}) {
-    return this.listTestruns({ page, per_page: perPage, run_id: runId, query });
+  searchRuns({ page, per_page: perPage, tql } = {}) {
+    return this.listRuns({ page, per_page: perPage, tql });
+  },
+
+  listTestruns({
+    page,
+    per_page: perPage,
+    run_id: runId,
+    test_ids: testIds,
+    filter_status: filterStatus,
+    filter_kind: filterKind,
+    filter_user: filterUser,
+    filter_priority: filterPriority,
+    filter_substatus: filterSubstatus,
+    filter_search: filterSearch,
+    filter_message: filterMessage,
+    filter_link: filterLink,
+    filter_finished_at_date_range: filterFinishedAtDateRange,
+    tags,
+    labels,
+    envs,
+    rungroups,
+    defects,
+  } = {}) {
+    return this.apiClient.list('testruns', {
+      page,
+      per_page: perPage,
+      run_id: runId,
+      test_ids: Array.isArray(testIds) ? testIds.join(',') : testIds,
+      'filter[status]': filterStatus,
+      'filter[kind]': filterKind,
+      'filter[user]': filterUser,
+      'filter[priority]': filterPriority,
+      'filter[substatus]': filterSubstatus,
+      'filter[search]': filterSearch,
+      'filter[message]': filterMessage,
+      'filter[link]': filterLink,
+      'filter[finished_at_date_range]': filterFinishedAtDateRange,
+      tags: Array.isArray(tags) ? tags.join(',') : tags,
+      labels: Array.isArray(labels) ? labels.join(',') : labels,
+      envs: Array.isArray(envs) ? envs.join(',') : envs,
+      rungroups: Array.isArray(rungroups) ? rungroups.join(',') : rungroups,
+      defects,
+    });
   },
 
-  listRungroups({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('rungroups', { page, per_page: perPage, query });
+  searchTestruns({ page, per_page: perPage, run_id: runId, filter_search: filterSearch, ...rest } = {}) {
+    return this.listTestruns({
+      page,
+      per_page: perPage,
+      run_id: runId,
+      filter_search: filterSearch,
+      ...rest,
+    });
   },
 
-  searchRungroups({ page, per_page: perPage, query } = {}) {
-    return this.listRungroups({ page, per_page: perPage, query });
+  listRungroups({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('rungroups', { page, per_page: perPage });
   },
 
-  listSteps({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('steps', { page, per_page: perPage, query });
+  listSteps({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('steps', { page, per_page: perPage });
   },
 
-  searchSteps({ page, per_page: perPage, query } = {}) {
-    return this.listSteps({ page, per_page: perPage, query });
+  listSnippets({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('snippets', { page, per_page: perPage });
   },
 
-  listSnippets({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('snippets', { page, per_page: perPage, query });
+  listLabels({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('labels', { page, per_page: perPage });
   },
 
-  searchSnippets({ page, per_page: perPage, query } = {}) {
-    return this.listSnippets({ page, per_page: perPage, query });
+  listPlans({ page, per_page: perPage, kind, hidden, labels, search_text: searchText } = {}) {
+    return this.apiClient.list('plans', {
+      page,
+      per_page: perPage,
+      kind,
+      hidden,
+      'labels[]': labels,
+      search_text: searchText,
+    });
   },
 
-  listLabels({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('labels', { page, per_page: perPage, query });
+  searchPlans({ page, per_page: perPage, search_text: searchText, ...rest } = {}) {
+    return this.listPlans({ page, per_page: perPage, search_text: searchText, ...rest });
   },
 
-  searchLabels({ page, per_page: perPage, query } = {}) {
-    return this.listLabels({ page, per_page: perPage, query });
+  listRequirements({ page, per_page: perPage, source, scope } = {}) {
+    return this.apiClient.list('requirements', { page, per_page: perPage, source, scope });
   },
 
-  listPlans({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('plans', { page, per_page: perPage, query });
+  searchRequirements({ page, per_page: perPage, source, scope } = {}) {
+    return this.listRequirements({ page, per_page: perPage, source, scope });
   },
 
-  searchPlans({ page, per_page: perPage, query } = {}) {
-    return this.listPlans({ page, per_page: perPage, query });
+  listMilestones({ page, per_page: perPage, type, status } = {}) {
+    return this.apiClient.list('milestones', { page, per_page: perPage, type, status });
   },
 
   listTags() {

package/src/mcp/registry/payloads.js

@@ -1,3 +1,6 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
 export const payloadMethods = {
   async createWrapped(resource, wrapperKey, payload) {
     const wrappedBody = { [wrapperKey]: payload };
@@ -23,6 +26,70 @@ export const payloadMethods = {
     }
   },
 
+  async patchWrapped(resource, id, wrapperKey, payload) {
+    const wrappedBody = { [wrapperKey]: payload };
+    try {
+      return await this.apiClient.patch(resource, id, payload);
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
+        throw error;
+      }
+      return this.apiClient.patch(resource, id, wrappedBody);
+    }
+  },
+
+  async createRequirement(args = {}) {
+    const { files, ...payloadArgs } = args;
+    const payload = this.buildRequirementPayload(payloadArgs);
+
+    if (this.hasFiles(files)) {
+      return this.apiClient.createMultipart(
+        'requirements',
+        await this.buildRequirementFormData(payload, files)
+      );
+    }
+
+    return this.createWrapped('requirements', 'requirement', payload);
+  },
+
+  async updateRequirement(requirementId, args = {}) {
+    const { files, ...payloadArgs } = args;
+    const payload = this.buildRequirementPayload(payloadArgs);
+
+    if (this.hasFiles(files)) {
+      return this.apiClient.patchMultipart(
+        'requirements',
+        requirementId,
+        await this.buildRequirementFormData(payload, files)
+      );
+    }
+
+    return this.patchWrapped('requirements', requirementId, 'requirement', payload);
+  },
+
+  hasFiles(files) {
+    return Array.isArray(files) && files.length > 0;
+  },
+
+  async buildRequirementFormData(payload, files = []) {
+    const formData = new FormData();
+
+    Object.entries(payload).forEach(([key, value]) => {
+      if (value === undefined || value === null) {
+        return;
+      }
+      formData.append(key, typeof value === 'boolean' ? String(value) : value);
+    });
+
+    for (const filePath of files) {
+      const resolvedPath = path.resolve(String(filePath));
+      const data = await fs.readFile(resolvedPath);
+      formData.append('files', new Blob([data]), path.basename(resolvedPath));
+    }
+
+    return formData;
+  },
+
   buildTestPayload({
     title,
     suite_id: suiteId,
@@ -76,7 +143,7 @@ export const payloadMethods = {
   buildRunCreatePayload({
     title,
     description,
-    plan_id: planId,
+    plan_ids: planIds,
     kind,
     rungroup_id: rungroupId,
     env,
@@ -85,13 +152,12 @@ export const payloadMethods = {
     test_ids: testIds,
     suite_ids: suiteIds,
     envs,
-    configuration,
     link,
   } = {}) {
     return {
       title,
       description,
-      plan_id: planId,
+      plan_ids: planIds,
       kind,
       rungroup_id: rungroupId,
       env,
@@ -100,7 +166,6 @@ export const payloadMethods = {
       test_ids: testIds,
       suite_ids: suiteIds,
       envs,
-      configuration,
       link,
     };
   },
@@ -108,7 +173,6 @@ export const payloadMethods = {
   buildRunUpdatePayload({
     title,
     description,
-    plan_id: planId,
     kind,
     rungroup_id: rungroupId,
     env,
@@ -117,13 +181,11 @@ export const payloadMethods = {
     assign_strategy: assignStrategy,
     test_ids: testIds,
     suite_ids: suiteIds,
-    configuration,
     link,
   } = {}) {
     return {
       title,
       description,
-      plan_id: planId,
       kind,
       rungroup_id: rungroupId,
       env,
@@ -132,7 +194,6 @@ export const payloadMethods = {
       assign_strategy: assignStrategy,
       test_ids: testIds,
       suite_ids: suiteIds,
-      configuration,
       link,
     };
   },
@@ -268,4 +329,24 @@ export const payloadMethods = {
       link,
     };
   },
+
+  buildRequirementPayload({
+    title,
+    source_type: sourceType,
+    description,
+    details,
+    active,
+    global,
+    confluence_url: confluenceUrl,
+  } = {}) {
+    return {
+      title,
+      source_type: sourceType,
+      description,
+      details,
+      active,
+      global,
+      confluence_url: confluenceUrl,
+    };
+  },
 };