@testomatio/mcp 2.2.0-beta.2 → 2.2.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testomatio/mcp",
-  "version": "2.2.0-beta.2",
+  "version": "2.2.0-beta.3",
   "description": "Model Context Protocol server for Testomatio API",
   "main": "src/index.js",
   "bin": {

package/src/api/testomatio-client.js

@@ -27,8 +27,8 @@ export class TestomatioApiClient {
     return this.http.request('GET', this.buildPath(resource, id), { query });
   }
 
-  async create(resource, body = {}) {
-    return this.mutate('POST', this.buildPath(resource), { body });
+  async create(resource, body = {}, query = {}) {
+    return this.mutate('POST', this.buildPath(resource), { query, body });
   }
 
   async createMultipart(resource, formData, query = {}) {
@@ -39,16 +39,16 @@ export class TestomatioApiClient {
     return this.mutate('POST', this.buildPath(resource), { query, body });
   }
 
-  async update(resource, id, body = {}) {
-    return this.mutate('PUT', this.buildPath(resource, id), { body });
+  async update(resource, id, body = {}, query = {}) {
+    return this.mutate('PUT', this.buildPath(resource, id), { query, body });
   }
 
-  async patch(resource, id, body = {}) {
-    return this.mutate('PATCH', this.buildPath(resource, id), { body });
+  async patch(resource, id, body = {}, query = {}) {
+    return this.mutate('PATCH', this.buildPath(resource, id), { query, body });
   }
 
-  async patchMultipart(resource, id, formData) {
-    return this.mutate('PATCH', this.buildPath(resource, id), { body: formData });
+  async patchMultipart(resource, id, formData, query = {}) {
+    return this.mutate('PATCH', this.buildPath(resource, id), { query, body: formData });
   }
 
   async delete(resource, id, query = {}) {

package/src/mcp/configs/entity-crud-config.js

@@ -8,6 +8,7 @@ export const ENTITY_CRUD_CONFIGS = [
     wrapperKey: 'test',
     createMode: 'wrapped',
     updateMode: 'wrapped',
+    queryArgs: ['branch'],
   },
   {
     toolPrefix: 'suites',
@@ -18,6 +19,7 @@ export const ENTITY_CRUD_CONFIGS = [
     wrapperKey: 'suite',
     createMode: 'wrapped',
     updateMode: 'wrapped',
+    queryArgs: ['branch'],
   },
   {
     toolPrefix: 'runs',
@@ -26,6 +28,7 @@ export const ENTITY_CRUD_CONFIGS = [
     listMethod: 'listRuns',
     createMode: 'run',
     updateMode: 'run',
+    queryArgs: ['branch'],
   },
   {
     toolPrefix: 'testruns',
@@ -98,4 +101,14 @@ export const ENTITY_CRUD_CONFIGS = [
     updateMode: 'requirement',
     updateMethod: 'patch',
   },
+  {
+    toolPrefix: 'branches',
+    resource: 'branches',
+    idArg: 'branch_id',
+    listMethod: 'listBranches',
+    payloadBuilder: 'buildBranchPayload',
+    wrapperKey: 'branch',
+    createMode: 'wrapped',
+    updateMode: 'wrapped',
+  },
 ];

package/src/mcp/definitions/branches.js

@@ -0,0 +1,110 @@
+export const BRANCH_PARAM = {
+  "type": "string",
+  "description": "Branch slug to scope the request to (omit or main for the main branch). For tests and suites, a branch-local record is used when it exists, falling back to main; updating/deleting a main-only record forks an isolated copy into the branch. Runs are tagged with the branch (only reachable with the same branch afterwards). Requires the branches feature."
+};
+
+export const BRANCHES_TOOLS = [
+  {
+    "name": "branches_list",
+    "description":
+      'List project branches (/api/v2/{project_id}/branches). Requires the branches feature (enterprise plan). Use filter[state] / filter[title] to narrow down.',
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "page": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "per_page": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        },
+        "filter_state": {
+          "type": "string",
+          "enum": [
+            "active",
+            "merged"
+          ],
+          "description": "Filter by branch state"
+        },
+        "filter_title": {
+          "type": "string",
+          "description": "Filter by title (partial substring match)"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "branches_get",
+    "description": "Get branch by slug",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "branch_id": {
+          "type": "string",
+          "description": "Branch slug"
+        }
+      },
+      "required": [
+        "branch_id"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "branches_create",
+    "description": "Create branch (/api/v2/{project_id}/branches)",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Branch title; a slug is generated from it"
+        }
+      },
+      "required": [
+        "title"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "branches_update",
+    "description": "Update branch title (/api/v2/{project_id}/branches/{slug})",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "branch_id": {
+          "type": "string",
+          "description": "Branch slug"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "branch_id"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "branches_delete",
+    "description": "Delete branch by slug",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "branch_id": {
+          "type": "string",
+          "description": "Branch slug"
+        }
+      },
+      "required": [
+        "branch_id"
+      ],
+      "additionalProperties": false
+    }
+  }
+];

package/src/mcp/definitions/runs.js

@@ -1,4 +1,5 @@
 import { RUNS_TQL_INPUT_DESCRIPTION, RUNS_TQL_REFERENCE } from './tql-reference.js';
+import { BRANCH_PARAM } from './branches.js';
 
 export const RUNS_TOOLS = [
   {
@@ -19,7 +20,8 @@ export const RUNS_TOOLS = [
         "tql": {
           "type": "string",
           "description": RUNS_TQL_INPUT_DESCRIPTION
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "additionalProperties": false
     }
@@ -32,7 +34,8 @@ export const RUNS_TOOLS = [
       "properties": {
         "run_id": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "run_id"
@@ -135,7 +138,8 @@ export const RUNS_TOOLS = [
             ],
             "additionalProperties": false
           }
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "title"
@@ -240,7 +244,8 @@ export const RUNS_TOOLS = [
             ],
             "additionalProperties": false
           }
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "run_id"
@@ -256,7 +261,8 @@ export const RUNS_TOOLS = [
       "properties": {
         "run_id": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "run_id"

package/src/mcp/definitions/suites.js

@@ -1,3 +1,4 @@
+import { BRANCH_PARAM } from './branches.js';
 export const SUITES_TOOLS = [
   {
     "name": "suites_list",
@@ -29,7 +30,8 @@ export const SUITES_TOOLS = [
         },
         "search_text": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "additionalProperties": false
     }
@@ -42,7 +44,8 @@ export const SUITES_TOOLS = [
       "properties": {
         "suite_id": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "suite_id"
@@ -120,7 +123,8 @@ export const SUITES_TOOLS = [
             ],
             "additionalProperties": false
           }
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "title"
@@ -201,7 +205,8 @@ export const SUITES_TOOLS = [
             ],
             "additionalProperties": false
           }
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "suite_id"
@@ -217,7 +222,8 @@ export const SUITES_TOOLS = [
       "properties": {
         "suite_id": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "suite_id"

package/src/mcp/definitions/tests.js

@@ -1,4 +1,5 @@
 import { TESTS_TQL_INPUT_DESCRIPTION, TESTS_TQL_REFERENCE } from './tql-reference.js';
+import { BRANCH_PARAM } from './branches.js';
 
 export const TESTS_TOOLS = [
   {
@@ -19,7 +20,8 @@ export const TESTS_TOOLS = [
         "tql": {
           "type": "string",
           "description": TESTS_TQL_INPUT_DESCRIPTION
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "additionalProperties": false
     }
@@ -32,7 +34,8 @@ export const TESTS_TOOLS = [
       "properties": {
         "test_id": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "test_id"
@@ -116,7 +119,8 @@ export const TESTS_TOOLS = [
             ],
             "additionalProperties": false
           }
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "title",
@@ -207,7 +211,8 @@ export const TESTS_TOOLS = [
             ],
             "additionalProperties": false
           }
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "test_id"
@@ -223,7 +228,8 @@ export const TESTS_TOOLS = [
       "properties": {
         "test_id": {
           "type": "string"
-        }
+        },
+        "branch": BRANCH_PARAM
       },
       "required": [
         "test_id"

package/src/mcp/registry/handlers.js

@@ -19,17 +19,27 @@ export const handlerMethods = {
           })
         );
       };
-      handlers[`${toolPrefix}_get`] = async (args = {}) =>
-        this.asText(await this.apiClient.get(resource, this.pickRequiredArg(args, idArg)));
-      handlers[`${toolPrefix}_create`] = async (args = {}) =>
-        this.asText(await this.executeCreate(spec, args));
+      handlers[`${toolPrefix}_get`] = async (args = {}) => {
+        const id = this.pickRequiredArg(args, idArg);
+        return this.asText(
+          await this.apiClient.get(resource, id, this.pickQueryArgs(spec, args))
+        );
+      };
+      handlers[`${toolPrefix}_create`] = async (args = {}) => {
+        const { query, payloadArgs } = this.splitQueryArgs(spec, args);
+        return this.asText(await this.executeCreate(spec, payloadArgs, query));
+      };
       handlers[`${toolPrefix}_update`] = async (args = {}) => {
         const id = this.pickRequiredArg(args, idArg);
-        const payloadArgs = this.omitArg(args, idArg);
-        return this.asText(await this.executeUpdate(spec, id, payloadArgs));
+        const { query, payloadArgs } = this.splitQueryArgs(spec, this.omitArgs(args, [idArg]));
+        return this.asText(await this.executeUpdate(spec, id, payloadArgs, query));
+      };
+      handlers[`${toolPrefix}_delete`] = async (args = {}) => {
+        const id = this.pickRequiredArg(args, idArg);
+        return this.asText(
+          await this.apiClient.delete(resource, id, this.pickQueryArgs(spec, args))
+        );
       };
-      handlers[`${toolPrefix}_delete`] = async (args = {}) =>
-        this.asText(await this.apiClient.delete(resource, this.pickRequiredArg(args, idArg)));
     }
   },
 
@@ -139,34 +149,58 @@ export const handlerMethods = {
     return value;
   },
 
-  omitArg(args = {}, key) {
+  omitArgs(args = {}, keys) {
     const payload = { ...args };
-    delete payload[key];
+    for (const key of keys) {
+      delete payload[key];
+    }
     return payload;
   },
 
-  executeCreate(spec, args = {}) {
+  /**
+   * Extract the entity's query args (spec.queryArgs, e.g. branch) from tool args
+   * without knowing their names in the handlers.
+   */
+  splitQueryArgs(spec, args = {}) {
+    const queryArgs = spec.queryArgs || [];
+    const query = {};
+    const payloadArgs = { ...args };
+    for (const key of queryArgs) {
+      if (args[key] !== undefined) {
+        query[key] = args[key];
+        delete payloadArgs[key];
+      }
+    }
+    return { query, payloadArgs };
+  },
+
+  pickQueryArgs(spec, args = {}) {
+    const { query } = this.splitQueryArgs(spec, args);
+    return query;
+  },
+
+  executeCreate(spec, args = {}, query = {}) {
     if (spec.createMode === 'run') {
-      return this.createRunWithFallback(args);
+      return this.createRunWithFallback(args, query);
     }
     if (spec.createMode === 'requirement') {
-      return this.createRequirement(args);
+      return this.createRequirement(args, query);
     }
     const payload = this[spec.payloadBuilder](args);
-    return this.createWrapped(spec.resource, spec.wrapperKey, payload);
+    return this.createWrapped(spec.resource, spec.wrapperKey, payload, query);
   },
 
-  executeUpdate(spec, id, args = {}) {
+  executeUpdate(spec, id, args = {}, query = {}) {
     if (spec.updateMode === 'run') {
-      return this.updateRunWithFallback(id, args);
+      return this.updateRunWithFallback(id, args, query);
     }
     if (spec.updateMode === 'requirement') {
-      return this.updateRequirement(id, args);
+      return this.updateRequirement(id, args, query);
     }
     const payload = this[spec.payloadBuilder](args);
     if (spec.updateMethod === 'patch') {
-      return this.patchWrapped(spec.resource, id, spec.wrapperKey, payload);
+      return this.patchWrapped(spec.resource, id, spec.wrapperKey, payload, query);
     }
-    return this.updateWrapped(spec.resource, id, spec.wrapperKey, payload);
+    return this.updateWrapped(spec.resource, id, spec.wrapperKey, payload, query);
   },
 };

package/src/mcp/registry/listings.js

@@ -6,6 +6,7 @@ export const listingMethods = {
     count,
     group_by: groupBy,
     slim,
+    branch,
   } = {}) {
     return this.apiClient.list('tests', {
       page,
@@ -14,10 +15,11 @@ export const listingMethods = {
       count,
       group_by: groupBy,
       slim,
+      branch,
     });
   },
 
-  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, count, group_by: groupBy, slim } = {}) {
+  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, count, group_by: groupBy, slim, branch } = {}) {
     return this.apiClient.list('suites', {
       page,
       per_page: perPage,
@@ -28,6 +30,7 @@ export const listingMethods = {
       count,
       group_by: groupBy,
       slim,
+      branch,
     });
   },
 
@@ -38,6 +41,7 @@ export const listingMethods = {
     count,
     group_by: groupBy,
     slim,
+    branch,
   } = {}) {
     return this.apiClient.list('runs', {
       page,
@@ -46,6 +50,7 @@ export const listingMethods = {
       count,
       group_by: groupBy,
       slim,
+      branch,
     });
   },
 
@@ -139,6 +144,26 @@ export const listingMethods = {
     return this.apiClient.list('tags', { count, group_by: groupBy, slim });
   },
 
+  listBranches({
+    page,
+    per_page: perPage,
+    filter_state: filterState,
+    filter_title: filterTitle,
+    count,
+    group_by: groupBy,
+    slim,
+  } = {}) {
+    return this.apiClient.list('branches', {
+      page,
+      per_page: perPage,
+      'filter[state]': filterState,
+      'filter[title]': filterTitle,
+      count,
+      group_by: groupBy,
+      slim,
+    });
+  },
+
   getTagByTitle(tagId) {
     return this.apiClient.get('tags', tagId);
   },

package/src/mcp/registry/payloads.js

@@ -2,57 +2,58 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 export const payloadMethods = {
-  async createWrapped(resource, wrapperKey, payload) {
+  async createWrapped(resource, wrapperKey, payload, query = {}) {
     const wrappedBody = { [wrapperKey]: payload };
     try {
-      return await this.apiClient.create(resource, payload);
+      return await this.apiClient.create(resource, payload, query);
     } catch (error) {
       if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
         throw error;
       }
-      return this.apiClient.create(resource, wrappedBody);
+      return this.apiClient.create(resource, wrappedBody, query);
     }
   },
 
-  async updateWrapped(resource, id, wrapperKey, payload) {
+  async updateWrapped(resource, id, wrapperKey, payload, query = {}) {
     const wrappedBody = { [wrapperKey]: payload };
     try {
-      return await this.apiClient.update(resource, id, payload);
+      return await this.apiClient.update(resource, id, payload, query);
     } catch (error) {
       if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
         throw error;
       }
-      return this.apiClient.update(resource, id, wrappedBody);
+      return this.apiClient.update(resource, id, wrappedBody, query);
     }
   },
 
-  async patchWrapped(resource, id, wrapperKey, payload) {
+  async patchWrapped(resource, id, wrapperKey, payload, query = {}) {
     const wrappedBody = { [wrapperKey]: payload };
     try {
-      return await this.apiClient.patch(resource, id, payload);
+      return await this.apiClient.patch(resource, id, payload, query);
     } catch (error) {
       if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
         throw error;
       }
-      return this.apiClient.patch(resource, id, wrappedBody);
+      return this.apiClient.patch(resource, id, wrappedBody, query);
     }
   },
 
-  async createRequirement(args = {}) {
+  async createRequirement(args = {}, query = {}) {
     const { files, ...payloadArgs } = args;
     const payload = this.buildRequirementPayload(payloadArgs);
 
     if (this.hasFiles(files)) {
       return this.apiClient.createMultipart(
         'requirements',
-        await this.buildRequirementFormData(payload, files)
+        await this.buildRequirementFormData(payload, files),
+        query
       );
     }
 
-    return this.createWrapped('requirements', 'requirement', payload);
+    return this.createWrapped('requirements', 'requirement', payload, query);
   },
 
-  async updateRequirement(requirementId, args = {}) {
+  async updateRequirement(requirementId, args = {}, query = {}) {
     const { files, ...payloadArgs } = args;
     const payload = this.buildRequirementPayload(payloadArgs);
 
@@ -60,11 +61,12 @@ export const payloadMethods = {
       return this.apiClient.patchMultipart(
         'requirements',
         requirementId,
-        await this.buildRequirementFormData(payload, files)
+        await this.buildRequirementFormData(payload, files),
+        query
       );
     }
 
-    return this.patchWrapped('requirements', requirementId, 'requirement', payload);
+    return this.patchWrapped('requirements', requirementId, 'requirement', payload, query);
   },
 
   hasFiles(files) {
@@ -198,27 +200,27 @@ export const payloadMethods = {
     };
   },
 
-  async createRunWithFallback(args = {}) {
+  async createRunWithFallback(args = {}, query = {}) {
     const payload = this.buildRunCreatePayload(args);
     try {
-      return await this.apiClient.create('runs', payload);
+      return await this.apiClient.create('runs', payload, query);
     } catch (error) {
       if (!this.shouldRetryWrappedBody(error, 'run')) {
         throw error;
       }
-      return this.apiClient.create('runs', { run: payload });
+      return this.apiClient.create('runs', { run: payload }, query);
     }
   },
 
-  async updateRunWithFallback(runId, args = {}) {
+  async updateRunWithFallback(runId, args = {}, query = {}) {
     const payload = this.buildRunUpdatePayload(args);
     try {
-      return await this.apiClient.update('runs', runId, payload);
+      return await this.apiClient.update('runs', runId, payload, query);
     } catch (error) {
       if (!this.shouldRetryWrappedBody(error, 'run')) {
         throw error;
       }
-      return this.apiClient.update('runs', runId, { run: payload });
+      return this.apiClient.update('runs', runId, { run: payload }, query);
     }
   },
 
@@ -351,4 +353,8 @@ export const payloadMethods = {
       confluence_url: confluenceUrl,
     };
   },
+
+  buildBranchPayload({ title } = {}) {
+    return { title };
+  },
 };

package/src/mcp/tool-definitions.js

@@ -14,6 +14,7 @@ import { ISSUES_TOOLS } from './definitions/issues.js';
 import { PLANS_TOOLS } from './definitions/plans.js';
 import { REQUIREMENTS_TOOLS } from './definitions/requirements.js';
 import { ATTACHMENT_TOOLS } from './definitions/attachments.js';
+import { BRANCHES_TOOLS } from './definitions/branches.js';
 import { withListOptions, withCountGroupOptions } from './list-projection.js';
 
 export const TOOL_DEFINITIONS = withCountGroupOptions(withListOptions([
@@ -33,4 +34,5 @@ export const TOOL_DEFINITIONS = withCountGroupOptions(withListOptions([
   ...ATTACHMENT_TOOLS,
   ...PLANS_TOOLS,
   ...REQUIREMENTS_TOOLS,
+  ...BRANCHES_TOOLS,
 ]));

package/src/mcp/tool-registry.js

@@ -17,7 +17,7 @@ function withPagination(payload) {
   if (!Array.isArray(payload.data) || !meta || typeof meta !== 'object') {
     return payload;
   }
-  const { total, page, per_page: perPage } = meta;
+  const { total, page, per_page: perPage, has_more: backendHasMore } = meta;
   if (
     typeof total !== 'number' ||
     typeof page !== 'number' ||
@@ -26,7 +26,10 @@ function withPagination(payload) {
   ) {
     return payload;
   }
-  if (page * perPage < total) {
+  const hasMore =
+    typeof backendHasMore === 'boolean' ? backendHasMore : page * perPage < total;
+
+  if (hasMore) {
     return {
       ...payload,
       _note: `Showing ${payload.data.length} of ${total} (page ${page}). More available — refine the filter or request the next page.`,