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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testomatio/mcp",
-  "version": "2.2.0-beta.1",
+  "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/list-projection.js

@@ -98,9 +98,13 @@ export function slimList(payload, { verbose = false, fields, entity } = {}) {
 
 /**
  * Ask the API to omit heavy list fields only when MCP does not need them for a
- * full or custom projection.
+ * full or custom projection. When `count` is requested the response is meta only,
+ * so `slim` is irrelevant and must not be sent alongside `count`.
  */
-export function backendSlimQuery({ verbose = false, fields } = {}) {
+export function backendSlimQuery({ verbose = false, fields, count = false } = {}) {
+  if (count) {
+    return {};
+  }
   return !verbose && !(Array.isArray(fields) && fields.length) ? { slim: true } : {};
 }
 
@@ -146,3 +150,47 @@ export function withListOptions(tools, { extraNames = [] } = {}) {
     };
   });
 }
+
+// Scoped list tools (*_issues_list, *_attachments_list) are filtered to one entity,
+// so count/group_by aggregation does not apply there.
+const SCOPED_LIST_INFIXES = ['_issues_', '_attachments_'];
+
+function isPrimaryListToolName(name) {
+  return (
+    typeof name === 'string' &&
+    name.endsWith('_list') &&
+    !SCOPED_LIST_INFIXES.some((infix) => name.includes(infix))
+  );
+}
+
+const COUNT_PROPERTY = {
+  type: 'boolean',
+  description:
+    'Return only metadata with total counts instead of the entity list. Pair with group_by for an aggregated breakdown.',
+};
+
+const GROUP_BY_PROPERTY = {
+  type: 'string',
+  description:
+    'Aggregate counts by this field, e.g. status, state, priority, created_by (use with count=true). The backend validates supported fields per resource. For created_by, counts are keyed by user email, not ID.',
+};
+
+/**
+ * Inject `count` and `group_by` into every primary list tool. `group_by` is a
+ * free-form string — the backend is the source of truth for which fields each
+ * resource accepts. Scoped list tools (*_issues_list, *_attachments_list) are skipped.
+ *
+ * @param {Array} tools
+ */
+export function withCountGroupOptions(tools) {
+  return tools.map((tool) => {
+    if (!tool || !isPrimaryListToolName(tool.name)) return tool;
+    const inputSchema = tool.inputSchema || { type: 'object', properties: {} };
+    const properties = {
+      ...(inputSchema.properties || {}),
+      count: COUNT_PROPERTY,
+      group_by: GROUP_BY_PROPERTY,
+    };
+    return { ...tool, inputSchema: { ...inputSchema, properties } };
+  });
+}

package/src/mcp/registry/handlers.js

@@ -10,7 +10,7 @@ export const handlerMethods = {
 
       handlers[`${toolPrefix}_list`] = async (args = {}) => {
         const { verbose, fields, ...listArgs } = args;
-        Object.assign(listArgs, backendSlimQuery({ verbose, fields }));
+        Object.assign(listArgs, backendSlimQuery({ verbose, fields, count: listArgs.count }));
         return this.asText(
           slimList(await this[listMethod](listArgs), {
             verbose,
@@ -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)));
     }
   },
 
@@ -102,15 +112,16 @@ export const handlerMethods = {
   registerGlobalHandlers(handlers) {
     handlers.project_info = async () => this.asText(await this.apiClient.get('info'));
 
-    handlers.tags_list = async (args = {}) =>
-      this.asText(
-        slimList(await this.listTags(backendSlimQuery(args)), { ...args, entity: 'tags' })
-      );
+    handlers.tags_list = async (args = {}) => {
+      const { verbose, fields, ...listArgs } = args;
+      Object.assign(listArgs, backendSlimQuery({ verbose, fields, count: listArgs.count }));
+      return this.asText(slimList(await this.listTags(listArgs), { ...args, entity: 'tags' }));
+    };
     handlers.tags_get = async ({ tag_id: tagId }) => this.asText(await this.getTagByTitle(tagId));
 
     handlers.milestones_list = async (args = {}) => {
       const { verbose, fields, ...listArgs } = args;
-      Object.assign(listArgs, backendSlimQuery({ verbose, fields }));
+      Object.assign(listArgs, backendSlimQuery({ verbose, fields, count: listArgs.count }));
       return this.asText(
         slimList(await this.listMilestones(listArgs), { verbose, fields, entity: 'milestones' })
       );
@@ -120,7 +131,7 @@ export const handlerMethods = {
 
     handlers.issues_list = async (args = {}) => {
       const { verbose, fields, ...listArgs } = args;
-      Object.assign(listArgs, backendSlimQuery({ verbose, fields }));
+      Object.assign(listArgs, backendSlimQuery({ verbose, fields, count: listArgs.count }));
       return this.asText(
         slimList(await this.listIssues(listArgs), { verbose, fields, entity: 'issues' })
       );
@@ -138,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

@@ -3,17 +3,23 @@ export const listingMethods = {
     page,
     per_page: perPage,
     tql,
+    count,
+    group_by: groupBy,
     slim,
+    branch,
   } = {}) {
     return this.apiClient.list('tests', {
       page,
       per_page: perPage,
       tql,
+      count,
+      group_by: groupBy,
       slim,
+      branch,
     });
   },
 
-  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, 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,
@@ -21,7 +27,10 @@ export const listingMethods = {
       tag,
       labels,
       search_text: searchText,
+      count,
+      group_by: groupBy,
       slim,
+      branch,
     });
   },
 
@@ -29,13 +38,19 @@ export const listingMethods = {
     page,
     per_page: perPage,
     tql,
+    count,
+    group_by: groupBy,
     slim,
+    branch,
   } = {}) {
     return this.apiClient.list('runs', {
       page,
       per_page: perPage,
       tql,
+      count,
+      group_by: groupBy,
       slim,
+      branch,
     });
   },
 
@@ -58,6 +73,8 @@ export const listingMethods = {
     envs,
     rungroups,
     defects,
+    count,
+    group_by: groupBy,
     slim,
   } = {}) {
     return this.apiClient.list('testruns', {
@@ -79,27 +96,29 @@ export const listingMethods = {
       envs: Array.isArray(envs) ? envs.join(',') : envs,
       rungroups: Array.isArray(rungroups) ? rungroups.join(',') : rungroups,
       defects,
+      count,
+      group_by: groupBy,
       slim,
     });
   },
 
-  listRungroups({ page, per_page: perPage, slim } = {}) {
-    return this.apiClient.list('rungroups', { page, per_page: perPage, slim });
+  listRungroups({ page, per_page: perPage, count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('rungroups', { page, per_page: perPage, count, group_by: groupBy, slim });
   },
 
-  listSteps({ page, per_page: perPage, slim } = {}) {
-    return this.apiClient.list('steps', { page, per_page: perPage, slim });
+  listSteps({ page, per_page: perPage, count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('steps', { page, per_page: perPage, count, group_by: groupBy, slim });
   },
 
-  listSnippets({ page, per_page: perPage, slim } = {}) {
-    return this.apiClient.list('snippets', { page, per_page: perPage, slim });
+  listSnippets({ page, per_page: perPage, count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('snippets', { page, per_page: perPage, count, group_by: groupBy, slim });
   },
 
-  listLabels({ page, per_page: perPage, slim } = {}) {
-    return this.apiClient.list('labels', { page, per_page: perPage, slim });
+  listLabels({ page, per_page: perPage, count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('labels', { page, per_page: perPage, count, group_by: groupBy, slim });
   },
 
-  listPlans({ page, per_page: perPage, kind, hidden, labels, search_text: searchText, slim } = {}) {
+  listPlans({ page, per_page: perPage, kind, hidden, labels, search_text: searchText, count, group_by: groupBy, slim } = {}) {
     return this.apiClient.list('plans', {
       page,
       per_page: perPage,
@@ -107,20 +126,42 @@ export const listingMethods = {
       hidden,
       'labels[]': labels,
       search_text: searchText,
+      count,
+      group_by: groupBy,
       slim,
     });
   },
 
-  listRequirements({ page, per_page: perPage, source, scope, slim } = {}) {
-    return this.apiClient.list('requirements', { page, per_page: perPage, source, scope, slim });
+  listRequirements({ page, per_page: perPage, source, scope, count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('requirements', { page, per_page: perPage, source, scope, count, group_by: groupBy, slim });
   },
 
-  listMilestones({ page, per_page: perPage, type, status, slim } = {}) {
-    return this.apiClient.list('milestones', { page, per_page: perPage, type, status, slim });
+  listMilestones({ page, per_page: perPage, type, status, count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('milestones', { page, per_page: perPage, type, status, count, group_by: groupBy, slim });
   },
 
-  listTags({ slim } = {}) {
-    return this.apiClient.list('tags', { slim });
+  listTags({ count, group_by: groupBy, slim } = {}) {
+    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) {

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,9 +14,10 @@ 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 { withListOptions } from './list-projection.js';
+import { BRANCHES_TOOLS } from './definitions/branches.js';
+import { withListOptions, withCountGroupOptions } from './list-projection.js';
 
-export const TOOL_DEFINITIONS = withListOptions([
+export const TOOL_DEFINITIONS = withCountGroupOptions(withListOptions([
   ...SYSTEM_TOOLS,
   ...PROJECT_TOOLS,
   ...TESTS_TOOLS,
@@ -33,4 +34,5 @@ export const TOOL_DEFINITIONS = 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.`,