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

package/README.md

@@ -273,6 +273,7 @@ NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token <TOKEN>
 
 - **Run Status** - Use `runs_update` with `status_event` for transitions (finish, launch, rerun, etc.)
 - **Search/Filter** - No dedicated `/search` endpoints; filtering is done via the `*_list` tools (`tql` for tests and runs, OpenAPI-aligned filters for other entities)
+- **Slim List Responses** - List tools request compact API responses by default and omit heavy entity fields and null values. Pass `verbose: true` to return full objects, or `fields: ["id", "title", "description"]` to return only selected fields. Both options disable the backend `slim=true` request so heavy fields remain available when requested.
 - **TQL** - Use `tql` as the single search/filter input for `tests_list` and `runs_list`
 - **TQL Syntax** - For user-facing syntax details and more examples, see the official TQL docs: https://docs.testomat.io/advanced/tql/
 - **TQL Scope** - TQL parameter descriptions keep the documented field whitelist in-band; call `tql_help` for syntax details and additional examples

package/package.json

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

package/src/index.js

@@ -4,7 +4,7 @@ import { ConfigurationError } from './core/errors.js';
 import { createLogger } from './core/logger.js';
 import { TestomatioMCPServer } from './mcp/server.js';
 import { TOOL_DEFINITIONS } from './mcp/tool-definitions.js';
-import { slimList, withListOptions } from './mcp/list-projection.js';
+import { backendSlimQuery, slimList, withListOptions } from './mcp/list-projection.js';
 import { selectTools } from './mcp/tool-profiles.js';
 import {
   ANALYTICS_STATS_TQL_INPUT_DESCRIPTION,
@@ -22,6 +22,7 @@ export {
   ConfigurationError,
   TOOL_DEFINITIONS,
   slimList,
+  backendSlimQuery,
   withListOptions,
   selectTools,
 };

package/src/mcp/list-projection.js

@@ -96,6 +96,18 @@ export function slimList(payload, { verbose = false, fields, entity } = {}) {
   return withViewMarker(applyToEnvelope(payload, (item) => stripHeavy(item, heavyFields)));
 }
 
+/**
+ * Ask the API to omit heavy list fields only when MCP does not need them for a
+ * 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, count = false } = {}) {
+  if (count) {
+    return {};
+  }
+  return !verbose && !(Array.isArray(fields) && fields.length) ? { slim: true } : {};
+}
+
 const LIST_OPTION_PROPERTIES = {
   verbose: {
     type: 'boolean',
@@ -138,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/attachments.js

@@ -4,9 +4,9 @@ import path from 'node:path';
 import { ATTACHMENT_RESOURCE_KEYS } from '../configs/attachments-config.js';
 
 export const attachmentMethods = {
-  listAttachmentsForKey({ resourceKey, resourceId }) {
+  listAttachmentsForKey({ resourceKey, resourceId, slim }) {
     this.assertSupportedAttachmentResourceKey(resourceKey);
-    return this.apiClient.list('attachments', { [resourceKey]: resourceId });
+    return this.apiClient.list('attachments', { [resourceKey]: resourceId, slim });
   },
 
   async uploadAttachmentForKey({ resourceKey, resourceId, filePath }) {

package/src/mcp/registry/handlers.js

@@ -1,7 +1,7 @@
 import { ENTITY_CRUD_CONFIGS } from '../configs/entity-crud-config.js';
 import { ATTACHMENT_SCOPED_TOOL_CONFIGS } from '../configs/attachments-config.js';
 import { ISSUE_SCOPED_TOOL_CONFIGS } from '../configs/issues-config.js';
-import { slimList } from '../list-projection.js';
+import { backendSlimQuery, slimList } from '../list-projection.js';
 
 export const handlerMethods = {
   registerEntityCrudHandlers(handlers) {
@@ -10,6 +10,7 @@ export const handlerMethods = {
 
       handlers[`${toolPrefix}_list`] = async (args = {}) => {
         const { verbose, fields, ...listArgs } = args;
+        Object.assign(listArgs, backendSlimQuery({ verbose, fields, count: listArgs.count }));
         return this.asText(
           slimList(await this[listMethod](listArgs), {
             verbose,
@@ -43,6 +44,7 @@ export const handlerMethods = {
               page: args.page,
               per_page: args.per_page,
               source: args.source,
+              ...backendSlimQuery(args),
             }),
             { verbose: args.verbose, fields: args.fields, entity: 'issues' }
           )
@@ -71,6 +73,7 @@ export const handlerMethods = {
             await this.listAttachmentsForKey({
               resourceKey,
               resourceId: this.pickRequiredArg(args, resourceKey),
+              ...backendSlimQuery(args),
             }),
             { verbose: args.verbose, fields: args.fields, entity: 'attachments' }
           )
@@ -99,12 +102,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(), { ...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, count: listArgs.count }));
       return this.asText(
         slimList(await this.listMilestones(listArgs), { verbose, fields, entity: 'milestones' })
       );
@@ -114,6 +121,7 @@ export const handlerMethods = {
 
     handlers.issues_list = async (args = {}) => {
       const { verbose, fields, ...listArgs } = args;
+      Object.assign(listArgs, backendSlimQuery({ verbose, fields, count: listArgs.count }));
       return this.asText(
         slimList(await this.listIssues(listArgs), { verbose, fields, entity: 'issues' })
       );

package/src/mcp/registry/issues.js

@@ -1,13 +1,14 @@
 import { ISSUE_RESOURCE_KEYS } from '../configs/issues-config.js';
 
 export const issueMethods = {
-  listIssues({ page, per_page: perPage, source, ...resourceQuery } = {}) {
+  listIssues({ page, per_page: perPage, source, slim, ...resourceQuery } = {}) {
     this.validateIssueResourceQuery(resourceQuery, { allowEmpty: true, allowMany: false });
     return this.listIssuesForResource({
       ...resourceQuery,
       page,
       per_page: perPage,
       source,
+      slim,
     });
   },
 
@@ -20,22 +21,24 @@ export const issueMethods = {
     });
   },
 
-  listIssuesForResource({ page, per_page: perPage, source, ...resourceQuery } = {}) {
+  listIssuesForResource({ page, per_page: perPage, source, slim, ...resourceQuery } = {}) {
     return this.apiClient.list('issues', {
       ...resourceQuery,
       page,
       per_page: perPage,
       source,
+      slim,
     });
   },
 
-  listIssuesForKey({ resourceKey, resourceId, page, per_page: perPage, source }) {
+  listIssuesForKey({ resourceKey, resourceId, page, per_page: perPage, source, slim }) {
     this.assertSupportedIssueResourceKey(resourceKey);
     return this.listIssuesForResource({
       [resourceKey]: resourceId,
       page,
       per_page: perPage,
       source,
+      slim,
     });
   },
 

package/src/mcp/registry/listings.js

@@ -3,15 +3,21 @@ export const listingMethods = {
     page,
     per_page: perPage,
     tql,
+    count,
+    group_by: groupBy,
+    slim,
   } = {}) {
     return this.apiClient.list('tests', {
       page,
       per_page: perPage,
       tql,
+      count,
+      group_by: groupBy,
+      slim,
     });
   },
 
-  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText } = {}) {
+  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, count, group_by: groupBy, slim } = {}) {
     return this.apiClient.list('suites', {
       page,
       per_page: perPage,
@@ -19,6 +25,9 @@ export const listingMethods = {
       tag,
       labels,
       search_text: searchText,
+      count,
+      group_by: groupBy,
+      slim,
     });
   },
 
@@ -26,11 +35,17 @@ export const listingMethods = {
     page,
     per_page: perPage,
     tql,
+    count,
+    group_by: groupBy,
+    slim,
   } = {}) {
     return this.apiClient.list('runs', {
       page,
       per_page: perPage,
       tql,
+      count,
+      group_by: groupBy,
+      slim,
     });
   },
 
@@ -53,6 +68,9 @@ export const listingMethods = {
     envs,
     rungroups,
     defects,
+    count,
+    group_by: groupBy,
+    slim,
   } = {}) {
     return this.apiClient.list('testruns', {
       page,
@@ -73,26 +91,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 } = {}) {
-    return this.apiClient.list('rungroups', { page, per_page: perPage });
+  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 } = {}) {
-    return this.apiClient.list('steps', { page, per_page: perPage });
+  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 } = {}) {
-    return this.apiClient.list('snippets', { page, per_page: perPage });
+  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 } = {}) {
-    return this.apiClient.list('labels', { page, per_page: perPage });
+  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 } = {}) {
+  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,
@@ -100,19 +121,22 @@ export const listingMethods = {
       hidden,
       'labels[]': labels,
       search_text: searchText,
+      count,
+      group_by: groupBy,
+      slim,
     });
   },
 
-  listRequirements({ page, per_page: perPage, source, scope } = {}) {
-    return this.apiClient.list('requirements', { page, per_page: perPage, source, scope });
+  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 } = {}) {
-    return this.apiClient.list('milestones', { page, per_page: perPage, type, status });
+  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() {
-    return this.apiClient.list('tags');
+  listTags({ count, group_by: groupBy, slim } = {}) {
+    return this.apiClient.list('tags', { count, group_by: groupBy, slim });
   },
 
   getTagByTitle(tagId) {

package/src/mcp/tool-definitions.js

@@ -14,9 +14,9 @@ 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 { 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 +33,4 @@ export const TOOL_DEFINITIONS = withListOptions([
   ...ATTACHMENT_TOOLS,
   ...PLANS_TOOLS,
   ...REQUIREMENTS_TOOLS,
-]);
+]));