@testomatio/mcp 2.1.2 → 2.2.0-beta

package/README.md

@@ -10,13 +10,14 @@ Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor,
   - Issues (global + scoped helpers for tests/suites/runs/testruns/plans)
   - Attachments (scoped helpers for tests/suites/testruns)
   - Requirements (including file uploads from local file paths)
-- **Smart Search** - delegates to list endpoints with OpenAPI-aligned query/filter forwarding
+- **Project Information** - fetch project configuration, metadata, features, and CI profiles
 - **Issue Linking** - link/unlink issues to any resource
 - **API Compatibility** - automatic handling of payload format differences (flat vs wrapped)
 - **Automatic API Sessions** - groups MCP changes in Testomat.io history using API sessions
 - **Run Management** - status transitions via `status_event` parameter
-- **TQL-Only Search** - `tests_list/tests_search` and `runs_list/runs_search` use `tql` as the single search/filter input
-- **Built-In TQL Reference** - MCP tool descriptions include exact TQL fields, syntax, and examples for agents
+- **TQL-Only Search** - `tests_list` and `runs_list` use `tql` as the single search/filter input
+- **Built-In TQL Reference** - TQL parameters include the exact field whitelist and examples; `tql_help` provides syntax details on demand
+- **Tool Surface Profiles** - expose only the tools a session needs via `--tools full|core|read` (default `full`); cuts the per-call schema cost for long agentic sessions
 
 ## Quick Start
 
@@ -51,6 +52,22 @@ testomatio-mcp
 export TESTOMATIO_BASE_URL=https://beta.testomat.io
 ```
 
+**Optional: tool surface profile**
+
+By default the server exposes all tools. For long, token-sensitive sessions you can expose a smaller set with `--tools`:
+
+```bash
+testomatio-mcp --token <PROJECT_TOKEN> --project <PROJECT_ID> --tools core
+```
+
+| Profile | What's exposed |
+|---------|----------------|
+| `full` (default) | Everything |
+| `core` | Core entities + CRUD (excludes steps, snippets, labels, rungroups, attachments) |
+| `read` | Core entities, read-only (list/get) |
+
+Values are case-insensitive; an unknown value prevents the server from starting. Set the profile at launch with the flag or the `TESTOMATIO_TOOLS` environment variable — it can't be changed mid-session. The CLI flag takes precedence when both are set.
+
 ## Usage with AI Assistants
 
 ### Cursor IDE
@@ -216,6 +233,7 @@ src/
 | `TESTOMATIO_API_TOKEN` | Yes* | - | Alternative token |
 | `TESTOMATIO_PROJECT_ID` | Yes | - | Project ID |
 | `TESTOMATIO_BASE_URL` | No | `https://app.testomat.io` | API base URL |
+| `TESTOMATIO_TOOLS` | No | `full` | Tool profile: `full`, `core`, or `read` |
 
 *Either `TESTOMATIO_PROJECT_TOKEN` or `TESTOMATIO_API_TOKEN`
 
@@ -254,10 +272,10 @@ NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token <TOKEN>
 ## Important Notes
 
 - **Run Status** - Use `runs_update` with `status_event` for transitions (finish, launch, rerun, etc.)
-- **Search** - No dedicated `/search` endpoints. MCP search tools delegate to list tools; for `tests` and `runs` the MCP interface is intentionally simplified to `tql`, while other entities stay closer to Public API v2 filters
-- **TQL** - Use `tql` as the single search/filter input for `tests_list/tests_search` and `runs_list/runs_search`
+- **Search/Filter** - No dedicated `/search` endpoints; filtering is done via the `*_list` tools (`tql` for tests and runs, OpenAPI-aligned filters for other entities)
+- **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** - The full agent-oriented whitelist of documented fields lives inside MCP tool descriptions for `tests` and `runs`
+- **TQL Scope** - TQL parameter descriptions keep the documented field whitelist in-band; call `tql_help` for syntax details and additional examples
 - **Issue Linking** - Scoped helpers available: `{entity}_issues_link/unlink`
 - **Attachments** - Scoped helpers available for tests, suites, and testruns: `{entity}_attachments_list/upload/delete`. Upload sends one local file path as multipart field `file`.
 - **Enterprise Package** - Analytics tools are intentionally exposed only by `@testomatio/mcp-enterprise`, not by the standard `@testomatio/mcp` package

package/package.json

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

package/src/api/testomatio-client.js

@@ -55,10 +55,6 @@ export class TestomatioApiClient {
     return this.mutate('DELETE', this.buildPath(resource, id), { query });
   }
 
-  search(resource, query = {}) {
-    return this.list(resource, query);
-  }
-
   async mutate(method, path, options = {}) {
     const runRequest = async () => {
       const sessionHash = await this.ensureSession();

package/src/cli/main.js

@@ -15,6 +15,10 @@ export function parseArgs(argv = process.argv) {
     .option('-t, --token <token>', 'Testomatio Project token')
     .option('-p, --project <project>', 'Project ID')
     .option('--base-url <url>', 'Base URL for Testomatio API')
+    .option(
+      '--tools <profile>',
+      'Tool surface: full (default, all tools), core (common entities only), read (read-only)'
+    )
     .parse(argv);
 
   return command.opts();

package/src/config/constants.js

@@ -1,3 +1,7 @@
 export const DEFAULT_BASE_URL = 'https://app.testomat.io';
 
 export const DEFAULT_TOOL_RESPONSE = 'Tool is declared but has no handler implementation.';
+
+export const TOOL_PROFILES = ['full', 'core', 'read'];
+
+export const DEFAULT_PROFILE = 'full';

package/src/config/load-config.js

@@ -1,4 +1,4 @@
-import { DEFAULT_BASE_URL } from './constants.js';
+import { DEFAULT_BASE_URL, DEFAULT_PROFILE, TOOL_PROFILES } from './constants.js';
 import { ConfigurationError } from '../core/errors.js';
 
 function normalizeString(value) {
@@ -16,6 +16,8 @@ export function loadConfig(argvOptions = {}) {
   );
   const projectId = normalizeString(argvOptions.project || process.env.TESTOMATIO_PROJECT_ID);
   const baseUrl = normalizeBaseUrl(argvOptions.baseUrl || process.env.TESTOMATIO_BASE_URL || DEFAULT_BASE_URL);
+  const rawToolsProfile = normalizeString(argvOptions.tools || process.env.TESTOMATIO_TOOLS).toLowerCase();
+  const toolsProfile = rawToolsProfile || DEFAULT_PROFILE;
 
   if (!token) {
     throw new ConfigurationError(
@@ -29,9 +31,16 @@ export function loadConfig(argvOptions = {}) {
     );
   }
 
+  if (!TOOL_PROFILES.includes(toolsProfile)) {
+    throw new ConfigurationError(
+      `Unknown tools profile "${toolsProfile}". Use one of: ${TOOL_PROFILES.join(', ')}.`
+    );
+  }
+
   return {
     token,
     projectId,
     baseUrl,
+    toolsProfile,
   };
 }

package/src/index.js

@@ -4,6 +4,8 @@ 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 { selectTools } from './mcp/tool-profiles.js';
 import {
   ANALYTICS_STATS_TQL_INPUT_DESCRIPTION,
   ANALYTICS_STATS_TQL_REFERENCE,
@@ -19,17 +21,22 @@ export {
   ANALYTICS_TESTS_TQL_REFERENCE,
   ConfigurationError,
   TOOL_DEFINITIONS,
+  slimList,
+  withListOptions,
+  selectTools,
 };
 
 export function createApplication(argvOptions = {}, serverOptions = {}) {
   const config = loadConfig(argvOptions);
   const logger = createLogger();
   const apiClient = new TestomatioApiClient({ ...config, logger });
+  const { tools: overrideTools, ...restServerOptions } = serverOptions;
   const mcpServer = new TestomatioMCPServer({
     config,
     apiClient,
     logger,
-    ...serverOptions,
+    tools: selectTools(overrideTools ?? TOOL_DEFINITIONS, config.toolsProfile),
+    ...restServerOptions,
   });
 
   return {

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

@@ -4,7 +4,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'tests',
     idArg: 'test_id',
     listMethod: 'listTests',
-    searchMethod: 'searchTests',
     payloadBuilder: 'buildTestPayload',
     wrapperKey: 'test',
     createMode: 'wrapped',
@@ -15,7 +14,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'suites',
     idArg: 'suite_id',
     listMethod: 'listSuites',
-    searchMethod: 'searchSuites',
     payloadBuilder: 'buildSuitePayload',
     wrapperKey: 'suite',
     createMode: 'wrapped',
@@ -26,7 +24,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'runs',
     idArg: 'run_id',
     listMethod: 'listRuns',
-    searchMethod: 'searchRuns',
     createMode: 'run',
     updateMode: 'run',
   },
@@ -35,7 +32,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'testruns',
     idArg: 'testrun_id',
     listMethod: 'listTestruns',
-    searchMethod: 'searchTestruns',
     payloadBuilder: 'buildTestrunPayload',
     wrapperKey: 'testrun',
     createMode: 'wrapped',
@@ -86,7 +82,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'plans',
     idArg: 'plan_id',
     listMethod: 'listPlans',
-    searchMethod: 'searchPlans',
     payloadBuilder: 'buildPlanPayload',
     wrapperKey: 'plan',
     createMode: 'wrapped',
@@ -97,7 +92,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'requirements',
     idArg: 'requirement_id',
     listMethod: 'listRequirements',
-    searchMethod: 'searchRequirements',
     payloadBuilder: 'buildRequirementPayload',
     wrapperKey: 'requirement',
     createMode: 'requirement',

package/src/mcp/definitions/issues.js

@@ -91,41 +91,4 @@ export const ISSUES_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "issues_search",
-    "description": "Search issues (delegates to issues_list filters)",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        },
-        "test_id": {
-          "type": "string"
-        },
-        "suite_id": {
-          "type": "string"
-        },
-        "run_id": {
-          "type": "string"
-        },
-        "testrun_id": {
-          "type": "integer"
-        },
-        "plan_id": {
-          "type": "string"
-        },
-        "source": {
-          "type": "string"
-        }
-      },
-      "additionalProperties": false
-    }
-  }
 ];

package/src/mcp/definitions/plans.js

@@ -247,45 +247,6 @@ export const PLANS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "plans_search",
-    "description": "Search plans (delegates to plans list; docs has no dedicated search parameter)",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "search_text": {
-          "type": "string"
-        },
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        },
-        "kind": {
-          "type": "string",
-          "enum": [
-            "manual",
-            "automated",
-            "mixed"
-          ]
-        },
-        "hidden": {
-          "type": "boolean"
-        },
-        "labels": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        }
-      },
-      "additionalProperties": false
-    }
-  },
   {
     "name": "plans_issues_list",
     "description": "List linked issues for a plan (/api/v2/{project_id}/issues?plan_id=...)",

package/src/mcp/definitions/projects.js

@@ -0,0 +1,12 @@
+export const PROJECT_TOOLS = [
+  {
+    name: 'project_info',
+    description:
+      'Get configuration and metadata for the current project (/api/v2/{project_id}/info), including framework, language, environments, labels, tags, subscription features, artifact storage status, and CI profiles.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+];

package/src/mcp/definitions/requirements.js

@@ -133,31 +133,4 @@ export const REQUIREMENTS_TOOLS = [
       additionalProperties: false,
     },
   },
-  {
-    name: 'requirements_search',
-    description: 'Search requirements (delegates to requirements list with filters)',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        page: {
-          type: 'integer',
-          minimum: 1,
-        },
-        per_page: {
-          type: 'integer',
-          minimum: 1,
-          maximum: 100,
-        },
-        source: {
-          type: 'string',
-          enum: ['jira', 'confluence', 'file', 'text'],
-        },
-        scope: {
-          type: 'string',
-          enum: ['global', 'attached', 'detached', 'without_suites'],
-        },
-      },
-      additionalProperties: false,
-    },
-  },
 ];

package/src/mcp/definitions/runs.js

@@ -264,29 +264,6 @@ export const RUNS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "runs_search",
-    "description": `Search runs using TQL (delegates to runs_list). ${RUNS_TQL_REFERENCE}`,
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        },
-        "tql": {
-          "type": "string",
-          "description": RUNS_TQL_INPUT_DESCRIPTION
-        }
-      },
-      "additionalProperties": false
-    }
-  },
   {
     "name": "runs_issues_list",
     "description": "List linked issues for a run (/api/v2/{project_id}/issues?run_id=...)",

package/src/mcp/definitions/suites.js

@@ -69,7 +69,11 @@ export const SUITES_TOOLS = [
           "type": "string"
         },
         "file_type": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "file",
+            "folder"
+          ]
         },
         "assigned_to": {
           "type": "string"
@@ -146,7 +150,11 @@ export const SUITES_TOOLS = [
           "type": "string"
         },
         "file_type": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "file",
+            "folder"
+          ]
         },
         "assigned_to": {
           "type": "string"
@@ -217,41 +225,6 @@ export const SUITES_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "suites_search",
-    "description": "Search suites by title (delegates to suites list with search_text)",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "search_text": {
-          "type": "string"
-        },
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        },
-        "file_type": {
-          "type": "string",
-          "enum": [
-            "file",
-            "folder"
-          ]
-        },
-        "tag": {
-          "type": "string"
-        },
-        "labels": {
-          "type": "string"
-        }
-      },
-      "additionalProperties": false
-    }
-  },
   {
     "name": "suites_issues_list",
     "description": "List linked issues for a suite (/api/v2/{project_id}/issues?suite_id=...)",

package/src/mcp/definitions/system.js

@@ -6,5 +6,13 @@ export const SYSTEM_TOOLS = [
       "type": "object",
       "properties": {}
     }
+  },
+  {
+    "name": "tql_help",
+    "description": "Full TQL (Testomat.io Query Language) reference — syntax, filter variables (tests + runs), and examples. Call this before writing a `tql` or `q` filter.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
   }
 ];

package/src/mcp/definitions/testruns.js

@@ -149,7 +149,13 @@ export const TESTRUNS_TOOLS = [
           "type": "string"
         },
         "status": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "passed",
+            "failed",
+            "skipped",
+            "pending"
+          ]
         },
         "message": {
           "type": "string"
@@ -189,7 +195,13 @@ export const TESTRUNS_TOOLS = [
           "type": "string"
         },
         "status": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "passed",
+            "failed",
+            "skipped",
+            "pending"
+          ]
         },
         "message": {
           "type": "string"
@@ -229,127 +241,6 @@ export const TESTRUNS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "testruns_search",
-    "description": "Search testruns (delegates to testruns list; docs has no dedicated search parameter)",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "run_id": {
-          "type": "string"
-        },
-        "test_ids": {
-          "type": [
-            "array",
-            "string"
-          ],
-          "items": {
-            "type": "string"
-          }
-        },
-        "filter_status": {
-          "type": "string",
-          "enum": [
-            "passed",
-            "failed",
-            "skipped",
-            "pending"
-          ]
-        },
-        "filter_kind": {
-          "type": "string",
-          "enum": [
-            "manual",
-            "automated"
-          ]
-        },
-        "filter_user": {
-          "type": [
-            "integer",
-            "string"
-          ]
-        },
-        "filter_priority": {
-          "type": "string",
-          "enum": [
-            "low",
-            "normal",
-            "important",
-            "high",
-            "critical"
-          ]
-        },
-        "filter_substatus": {
-          "type": "string"
-        },
-        "filter_search": {
-          "type": "string"
-        },
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        },
-        "filter_message": {
-          "type": "boolean"
-        },
-        "filter_link": {
-          "type": "boolean"
-        },
-        "filter_finished_at_date_range": {
-          "type": "string"
-        },
-        "tags": {
-          "type": [
-            "array",
-            "string"
-          ],
-          "items": {
-            "type": "string"
-          }
-        },
-        "labels": {
-          "type": [
-            "array",
-            "string"
-          ],
-          "items": {
-            "type": "string"
-          }
-        },
-        "envs": {
-          "type": [
-            "array",
-            "string"
-          ],
-          "items": {
-            "type": "string"
-          }
-        },
-        "rungroups": {
-          "type": [
-            "array",
-            "string"
-          ],
-          "items": {
-            "type": "string"
-          }
-        },
-        "defects": {
-          "type": "string",
-          "enum": [
-            "has_defects",
-            "without_defects"
-          ]
-        }
-      },
-      "additionalProperties": false
-    }
-  },
   {
     "name": "testruns_issues_list",
     "description": "List linked issues for a testrun (/api/v2/{project_id}/issues?testrun_id=...)",

package/src/mcp/definitions/tests.js

@@ -59,7 +59,14 @@ export const TESTS_TOOLS = [
           "type": "string"
         },
         "priority": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "low",
+            "normal",
+            "important",
+            "high",
+            "critical"
+          ]
         },
         "assigned_to": {
           "type": "string"
@@ -68,7 +75,12 @@ export const TESTS_TOOLS = [
           "type": "string"
         },
         "state": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "manual",
+            "detached",
+            "automated"
+          ]
         },
         "link": {
           "type": "array",
@@ -135,7 +147,14 @@ export const TESTS_TOOLS = [
           "type": "string"
         },
         "priority": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "low",
+            "normal",
+            "important",
+            "high",
+            "critical"
+          ]
         },
         "assigned_to": {
           "type": "string"
@@ -144,7 +163,12 @@ export const TESTS_TOOLS = [
           "type": "string"
         },
         "state": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "manual",
+            "detached",
+            "automated"
+          ]
         },
         "sync": {
           "type": "boolean"
@@ -207,29 +231,6 @@ export const TESTS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "tests_search",
-    "description": `Search tests using TQL (delegates to tests_list). ${TESTS_TQL_REFERENCE}`,
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        },
-        "tql": {
-          "type": "string",
-          "description": TESTS_TQL_INPUT_DESCRIPTION
-        }
-      },
-      "additionalProperties": false
-    }
-  },
   {
     "name": "tests_issues_list",
     "description": "List linked issues for a test (/api/v2/{project_id}/issues?test_id=...)",

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

@@ -89,62 +89,42 @@ const RUNS_TQL_EXAMPLES = [
 const COMMON_TQL_SYNTAX =
   "Supported syntax includes logical operators `and`, `or`, `not`, equality operators `==` and `!=`, list membership `in [...]`, `%` for partial text match on supported text fields, and parentheses for grouping. Ordered comparisons `>`, `<`, `>=`, `<=` are for ordered fields such as `priority`, dates, and numeric counters/durations. 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.';
+const TESTS_TQL_FIELDS = TESTS_TQL_VARIABLES.join(', ');
+const RUNS_TQL_FIELDS = RUNS_TQL_VARIABLES.join(', ');
 
-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 TQL_FULL_REFERENCE = [
+  'TQL (Testomat.io Query Language) is a string expression used to filter tests and runs.',
+  COMMON_TQL_SYNTAX,
+  '',
+  `Tests filter variables: ${TESTS_TQL_VARIABLES.map((v) => `\`${v}\``).join(', ')}.`,
+  `Tests examples: ${TESTS_TQL_EXAMPLES.map((e) => `\`${e}\``).join(', ')}.`,
+  '',
+  `Runs filter variables: ${RUNS_TQL_VARIABLES.map((v) => `\`${v}\``).join(', ')}.`,
+  'Runs also support boolean flags used without comparison, e.g. `failed`, `finished`, `automated`, `with_defect`.',
+  `Runs examples: ${RUNS_TQL_EXAMPLES.map((e) => `\`${e}\``).join(', ')}.`,
+  '',
+  'Parameter name: tests/runs/plans use `tql`; analytics tools use `q`.',
+  'Do not invent undocumented fields or syntax. If a query fails, simplify it to one documented predicate.',
+].join('\n');
 
+export const TESTS_TQL_REFERENCE =
+  'Filter tests with `tql` (TQL); call `tql_help` for the syntax and full field list.';
 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(', ')}.`;
-
+  'Filter runs with `tql` (TQL); runs also accept boolean flags. Call `tql_help` for the syntax and full field list.';
 export const PLANS_TQL_REFERENCE =
-  `TQL (Testomat.io Query Language) is a string expression passed in \`tql\` to select tests included in a plan. ${COMMON_TQL_SYNTAX} ` +
-  `Plan TQL uses documented test variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
-  `Documented examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}. ` +
-  'Use `tql` when you want the API to resolve matching tests automatically instead of sending explicit `test_ids`. Do not invent undocumented fields or syntax. If a query fails, simplify it to one documented predicate.';
-
-export const PLANS_TQL_INPUT_DESCRIPTION =
-  'TQL filter for selecting tests included in the plan. ' +
-  `Documented test variables: ${TESTS_TQL_VARIABLES.map((item) => `\`${item}\``).join(', ')}. ` +
-  `Examples: ${TESTS_TQL_EXAMPLES.map((item) => `\`${item}\``).join(', ')}.`;
-
+  'Select tests for the plan with `tql` (TQL); the API resolves matching tests. Call `tql_help` for the syntax and full field list.';
 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(', ')}.`;
-
+  'Filter analytics test reports with `q` (TQL). Call `tql_help` for the syntax and full field list.';
 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.';
+  'Filter analytics aggregated reports with `q` (TQL; tests or runs variables). Call `tql_help` for the syntax and full field list.';
 
+export const TESTS_TQL_INPUT_DESCRIPTION =
+  `TQL filter for tests. Fields: ${TESTS_TQL_FIELDS}. Call \`tql_help\` for syntax. Examples: \`priority == 'high'\`, \`state == 'automated'\`, \`suite % 'Checkout'\`.`;
+export const RUNS_TQL_INPUT_DESCRIPTION =
+  `TQL filter for runs. Fields: ${RUNS_TQL_FIELDS}. Call \`tql_help\` for syntax. Examples: \`finished and with_defect\`, \`env in ['Windows', 'Linux']\`, \`has_retries > 2\`.`;
+export const PLANS_TQL_INPUT_DESCRIPTION =
+  `TQL to select tests for the plan. Fields: ${TESTS_TQL_FIELDS}. Call \`tql_help\` for syntax. Examples: \`priority == 'high'\`, \`tag in ['smoke', 'stage1']\`.`;
+export const ANALYTICS_TESTS_TQL_INPUT_DESCRIPTION =
+  `TQL filter (param \`q\`) for analytics test reports. Fields: ${TESTS_TQL_FIELDS}. Call \`tql_help\` for syntax. Examples: \`priority == 'high'\`, \`state == 'automated'\`.`;
 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(', ')}.`;
+  `TQL filter (param \`q\`) for analytics reports. Test fields: ${TESTS_TQL_FIELDS}. Run fields: ${RUNS_TQL_FIELDS}. Call \`tql_help\` for syntax. Examples: \`priority == 'high'\`, \`finished_at >= '2025-07-01' and failed\`.`;

package/src/mcp/list-projection.js

@@ -0,0 +1,140 @@
+/**
+ * Slim projection for list-tool responses.
+ *
+ * List tools return only what an index view needs: entity-specific heavy fields
+ * and null values are dropped.
+ * `verbose:true` returns the full body; `fields:[...]` selects a custom field set.
+ * Every shaped response carries a `_view` marker so the caller knows it is partial.
+ */
+
+const HEAVY_FIELDS_BY_ENTITY = {
+  tests: new Set(['description', 'code', 'cleanTitle', 'publicTitle']),
+  suites: new Set(['description', 'code', 'cleanTitle', 'publicTitle']),
+  runs: new Set(['description']),
+  testruns: new Set(['description', 'code']),
+  rungroups: new Set(['description']),
+  steps: new Set(['description']),
+  snippets: new Set(['description']),
+  plans: new Set(['description']),
+  requirements: new Set(['description']),
+  analytics_tests: new Set(['description', 'code', 'cleanTitle', 'publicTitle']),
+};
+
+function isNullish(value) {
+  return value === null || value === undefined;
+}
+
+function pickFields(item, fields) {
+  const result = {};
+  for (const key of fields) {
+    if (!(key in item)) continue;
+    const value = item[key];
+    if (isNullish(value)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+function stripHeavy(item, heavyFields) {
+  const result = {};
+  for (const [key, value] of Object.entries(item)) {
+    if (heavyFields.has(key)) continue;
+    if (isNullish(value)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+function mapItems(items, fn) {
+  return items.map((item) =>
+    item && typeof item === 'object' && !Array.isArray(item) ? fn(item) : item
+  );
+}
+
+function applyToEnvelope(payload, fn) {
+  if (!payload || typeof payload !== 'object') return payload;
+  if (Array.isArray(payload)) return mapItems(payload, fn);
+  if (Array.isArray(payload.data)) {
+    return { ...payload, data: mapItems(payload.data, fn) };
+  }
+  return payload;
+}
+
+const VIEW_NOTE =
+  'Entity-specific heavy fields and null values removed. Pass verbose:true for full bodies or fields:[...] to select fields.';
+
+function withViewMarker(result, note = VIEW_NOTE) {
+  if (
+    result &&
+    typeof result === 'object' &&
+    !Array.isArray(result) &&
+    Array.isArray(result.data)
+  ) {
+    return { ...result, _view: note };
+  }
+  return result;
+}
+
+/**
+ * Shape a list payload: drop entity-specific heavy and null fields by default, full body on `verbose`,
+ * custom field set on `fields`. A `_view` marker is added to shaped envelopes.
+ *
+ * @param {*} payload              raw API response ({ data, meta } or a bare array)
+ * @param {{ verbose?: boolean, fields?: string[], entity?: string }} [opts]
+ */
+export function slimList(payload, { verbose = false, fields, entity } = {}) {
+  if (verbose) {
+    return payload;
+  }
+  if (Array.isArray(fields) && fields.length) {
+    return withViewMarker(
+      applyToEnvelope(payload, (item) => pickFields(item, fields)),
+      `Custom fields [${fields.join(', ')}]. Pass verbose:true for the full object.`
+    );
+  }
+  const heavyFields = HEAVY_FIELDS_BY_ENTITY[entity] ?? new Set();
+  return withViewMarker(applyToEnvelope(payload, (item) => stripHeavy(item, heavyFields)));
+}
+
+const LIST_OPTION_PROPERTIES = {
+  verbose: {
+    type: 'boolean',
+    default: false,
+    description:
+      'Return full response bodies. Default strips entity-specific heavy fields and null values; set true when you need those.',
+  },
+  fields: {
+    type: 'array',
+    items: { type: 'string' },
+    description:
+      'Fields to keep per item (e.g. ["id","title","status","message"]). Ignored when verbose is true.',
+  },
+};
+
+/**
+ * Inject `verbose`/`fields` input params into every list-style tool definition so the
+ * model can opt into full bodies or a custom projection. Returns shallow copies; the
+ * source definitions are not mutated.
+ *
+ * @param {Array} tools
+ * @param {{ extraNames?: string[] }} [options]  additional tool names to augment
+ */
+export function withListOptions(tools, { extraNames = [] } = {}) {
+  return tools.map((tool) => {
+    if (!tool || !tool.name) return tool;
+    const isListStyle = tool.name.endsWith('_list') || extraNames.includes(tool.name);
+    if (!isListStyle) return tool;
+
+    const inputSchema = tool.inputSchema || { type: 'object', properties: {} };
+    const properties = { ...(inputSchema.properties || {}), ...LIST_OPTION_PROPERTIES };
+
+    return {
+      ...tool,
+      description: `${tool.description ?? ''} Entity-specific heavy fields are stripped by default; verbose:true for full bodies.`.trim(),
+      inputSchema: {
+        ...inputSchema,
+        properties,
+      },
+    };
+  });
+}

package/src/mcp/registry/handlers.js

@@ -1,18 +1,23 @@
 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';
 
 export const handlerMethods = {
   registerEntityCrudHandlers(handlers) {
     for (const spec of ENTITY_CRUD_CONFIGS) {
-      const { toolPrefix, resource, idArg, listMethod, searchMethod } = spec;
-
-      handlers[`${toolPrefix}_list`] = async (args = {}) =>
-        this.asText(await this[listMethod](args));
-      if (searchMethod) {
-        handlers[`${toolPrefix}_search`] = async (args = {}) =>
-          this.asText(await this[searchMethod](args));
-      }
+      const { toolPrefix, resource, idArg, listMethod } = spec;
+
+      handlers[`${toolPrefix}_list`] = async (args = {}) => {
+        const { verbose, fields, ...listArgs } = args;
+        return this.asText(
+          slimList(await this[listMethod](listArgs), {
+            verbose,
+            fields,
+            entity: toolPrefix,
+          })
+        );
+      };
       handlers[`${toolPrefix}_get`] = async (args = {}) =>
         this.asText(await this.apiClient.get(resource, this.pickRequiredArg(args, idArg)));
       handlers[`${toolPrefix}_create`] = async (args = {}) =>
@@ -31,13 +36,16 @@ export const handlerMethods = {
     for (const { toolPrefix, resourceKey } of ISSUE_SCOPED_TOOL_CONFIGS) {
       handlers[`${toolPrefix}_issues_list`] = async (args = {}) =>
         this.asText(
-          await this.listIssuesForKey({
-            resourceKey,
-            resourceId: this.pickRequiredArg(args, resourceKey),
-            page: args.page,
-            per_page: args.per_page,
-            source: args.source,
-          })
+          slimList(
+            await this.listIssuesForKey({
+              resourceKey,
+              resourceId: this.pickRequiredArg(args, resourceKey),
+              page: args.page,
+              per_page: args.per_page,
+              source: args.source,
+            }),
+            { verbose: args.verbose, fields: args.fields, entity: 'issues' }
+          )
         );
 
       handlers[`${toolPrefix}_issues_link`] = async (args = {}) =>
@@ -59,10 +67,13 @@ export const handlerMethods = {
     for (const { toolPrefix, resourceKey } of ATTACHMENT_SCOPED_TOOL_CONFIGS) {
       handlers[`${toolPrefix}_attachments_list`] = async (args = {}) =>
         this.asText(
-          await this.listAttachmentsForKey({
-            resourceKey,
-            resourceId: this.pickRequiredArg(args, resourceKey),
-          })
+          slimList(
+            await this.listAttachmentsForKey({
+              resourceKey,
+              resourceId: this.pickRequiredArg(args, resourceKey),
+            }),
+            { verbose: args.verbose, fields: args.fields, entity: 'attachments' }
+          )
         );
 
       handlers[`${toolPrefix}_attachments_upload`] = async (args = {}) =>
@@ -86,16 +97,27 @@ export const handlerMethods = {
   },
 
   registerGlobalHandlers(handlers) {
-    handlers.tags_list = async () => this.asText(await this.listTags());
+    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_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_list = async (args = {}) => {
+      const { verbose, fields, ...listArgs } = args;
+      return this.asText(
+        slimList(await this.listMilestones(listArgs), { verbose, fields, entity: 'milestones' })
+      );
+    };
     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_list = async (args = {}) => {
+      const { verbose, fields, ...listArgs } = args;
+      return this.asText(
+        slimList(await this.listIssues(listArgs), { verbose, fields, entity: 'issues' })
+      );
+    };
     handlers.issues_create = async (args = {}) => this.asText(await this.createIssue(args));
     handlers.issues_delete = async ({ issue_id: issueId, type }) =>
       this.asText(await this.apiClient.delete('issues', issueId, { type }));

package/src/mcp/registry/issues.js

@@ -11,10 +11,6 @@ export const issueMethods = {
     });
   },
 
-  searchIssues(args = {}) {
-    return this.listIssues(args);
-  },
-
   createIssue({ url, jira_id: jiraId, ...resourceQuery } = {}) {
     this.validateIssueResourceQuery(resourceQuery, { allowEmpty: false, allowMany: false });
     return this.linkIssueToResource({

package/src/mcp/registry/listings.js

@@ -11,14 +11,6 @@ export const listingMethods = {
     });
   },
 
-  searchTests({ page, per_page: perPage, tql } = {}) {
-    return this.listTests({
-      page,
-      per_page: perPage,
-      tql,
-    });
-  },
-
   listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText } = {}) {
     return this.apiClient.list('suites', {
       page,
@@ -30,13 +22,6 @@ export const listingMethods = {
     });
   },
 
-  searchSuites({ search_text: searchText, ...rest } = {}) {
-    return this.listSuites({
-      ...rest,
-      search_text: searchText,
-    });
-  },
-
   listRuns({
     page,
     per_page: perPage,
@@ -49,10 +34,6 @@ export const listingMethods = {
     });
   },
 
-  searchRuns({ page, per_page: perPage, tql } = {}) {
-    return this.listRuns({ page, per_page: perPage, tql });
-  },
-
   listTestruns({
     page,
     per_page: perPage,
@@ -95,16 +76,6 @@ export const listingMethods = {
     });
   },
 
-  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,
-    });
-  },
-
   listRungroups({ page, per_page: perPage } = {}) {
     return this.apiClient.list('rungroups', { page, per_page: perPage });
   },
@@ -132,18 +103,10 @@ export const listingMethods = {
     });
   },
 
-  searchPlans({ page, per_page: perPage, search_text: searchText, ...rest } = {}) {
-    return this.listPlans({ page, per_page: perPage, search_text: searchText, ...rest });
-  },
-
   listRequirements({ page, per_page: perPage, source, scope } = {}) {
     return this.apiClient.list('requirements', { page, per_page: perPage, source, scope });
   },
 
-  searchRequirements({ page, per_page: perPage, source, scope } = {}) {
-    return this.listRequirements({ page, per_page: perPage, source, scope });
-  },
-
   listMilestones({ page, per_page: perPage, type, status } = {}) {
     return this.apiClient.list('milestones', { page, per_page: perPage, type, status });
   },

package/src/mcp/tool-definitions.js

@@ -1,4 +1,5 @@
 import { SYSTEM_TOOLS } from './definitions/system.js';
+import { PROJECT_TOOLS } from './definitions/projects.js';
 import { TESTS_TOOLS } from './definitions/tests.js';
 import { SUITES_TOOLS } from './definitions/suites.js';
 import { RUNS_TOOLS } from './definitions/runs.js';
@@ -13,9 +14,11 @@ 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';
 
-export const TOOL_DEFINITIONS = [
+export const TOOL_DEFINITIONS = withListOptions([
   ...SYSTEM_TOOLS,
+  ...PROJECT_TOOLS,
   ...TESTS_TOOLS,
   ...SUITES_TOOLS,
   ...RUNS_TOOLS,
@@ -30,4 +33,4 @@ export const TOOL_DEFINITIONS = [
   ...ATTACHMENT_TOOLS,
   ...PLANS_TOOLS,
   ...REQUIREMENTS_TOOLS,
-];
+]);

package/src/mcp/tool-profiles.js

@@ -0,0 +1,37 @@
+const RARE_ENTITIES = new Set(['steps', 'snippets', 'labels', 'rungroups']);
+
+function entityOf(name) {
+  if (name === 'system_ping') return 'system';
+  return name
+    .split('_attachments_')[0]
+    .split('_issues_')[0]
+    .replace(/_(list|get|create|update|delete|search)$/, '');
+}
+
+function isAttachment(name) {
+  return name.includes('_attachments_');
+}
+
+function isReadOp(name) {
+  return name === 'system_ping' || /_(list|get)$/.test(name) || name.endsWith('_issues_list');
+}
+
+/**
+ * Whether a tool is visible under the given profile. Unknown profiles fall back to full
+ *
+ * @param {string} name     tool name
+ * @param {string} profile  'full' | 'core' | 'read'
+ */
+export function isToolInProfile(name, profile) {
+  if (!profile || profile === 'full') return true;
+  if (isAttachment(name)) return false;
+  const coreEntity = !RARE_ENTITIES.has(entityOf(name));
+  if (profile === 'core') return coreEntity;
+  if (profile === 'read') return coreEntity && isReadOp(name);
+  return true;
+}
+
+export function selectTools(allTools, profile) {
+  if (!profile || profile === 'full') return allTools;
+  return allTools.filter((tool) => tool && isToolInProfile(tool.name, profile));
+}

package/src/mcp/tool-registry.js

@@ -2,14 +2,41 @@ 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 { TQL_FULL_REFERENCE } from './definitions/tql-reference.js';
 import { handlerMethods } from './registry/handlers.js';
 import { attachmentMethods } from './registry/attachments.js';
 import { issueMethods } from './registry/issues.js';
 import { listingMethods } from './registry/listings.js';
 import { payloadMethods } from './registry/payloads.js';
 
+function withPagination(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return payload;
+  }
+  const meta = payload.meta;
+  if (!Array.isArray(payload.data) || !meta || typeof meta !== 'object') {
+    return payload;
+  }
+  const { total, page, per_page: perPage } = meta;
+  if (
+    typeof total !== 'number' ||
+    typeof page !== 'number' ||
+    typeof perPage !== 'number' ||
+    perPage <= 0
+  ) {
+    return payload;
+  }
+  if (page * perPage < total) {
+    return {
+      ...payload,
+      _note: `Showing ${payload.data.length} of ${total} (page ${page}). More available — refine the filter or request the next page.`,
+    };
+  }
+  return payload;
+}
+
 function formatJson(payload) {
-  return JSON.stringify(payload, null, 2);
+  return JSON.stringify(payload);
 }
 
 export class ToolRegistry {
@@ -23,7 +50,7 @@ export class ToolRegistry {
   }
 
   asText(payload) {
-    return textResponse(formatJson(payload));
+    return textResponse(formatJson(withPagination(payload)));
   }
 
   buildHandlers() {
@@ -35,6 +62,7 @@ export class ToolRegistry {
           baseUrl: this.config.baseUrl,
           apiVersion: 'v2',
         }),
+      tql_help: async () => textResponse(TQL_FULL_REFERENCE),
     };
 
     this.registerEntityCrudHandlers(handlers);