@testomatio/mcp 2.1.1 → 2.2.0-beta

package/README.md

@@ -8,14 +8,16 @@ Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor,
   - Tests, Suites, Plans, Runs, TestRuns, RunGroups, Steps, Snippets, Labels
   - Tags and Milestones (read-only access)
   - 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
 
@@ -50,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
@@ -178,6 +196,17 @@ Add this config to `opencode.json` in your project root, or to `~/.config/openco
 }
 ```
 
+**Upload attachment to a test:**
+```json
+{
+  "name": "tests_attachments_upload",
+  "arguments": {
+    "test_id": "123",
+    "file_path": "/path/to/screenshot.png"
+  }
+}
+```
+
 ## Documentation
 
 Complete tool reference: [docs/tools.md](./docs/tools.md)
@@ -204,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`
 
@@ -242,11 +272,12 @@ 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
 - **API Sessions** - The server automatically starts a Testomat.io session before the first `POST`, `PUT`, or `DELETE` request, sends the returned session hash as `X-Session-Hash` on later mutating requests, and stops the session when the MCP server shuts down. `GET` requests do not start or use sessions.
 

package/package.json

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

package/src/api/testomatio-client.js

@@ -31,8 +31,8 @@ export class TestomatioApiClient {
     return this.mutate('POST', this.buildPath(resource), { body });
   }
 
-  async createMultipart(resource, formData) {
-    return this.mutate('POST', this.buildPath(resource), { body: formData });
+  async createMultipart(resource, formData, query = {}) {
+    return this.mutate('POST', this.buildPath(resource), { query, body: formData });
   }
 
   async createWithQuery(resource, { query = {}, body = {} } = {}) {
@@ -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/attachments-config.js

@@ -0,0 +1,7 @@
+export const ATTACHMENT_RESOURCE_KEYS = ['test_id', 'suite_id', 'testrun_id'];
+
+export const ATTACHMENT_SCOPED_TOOL_CONFIGS = [
+  { toolPrefix: 'tests', resourceKey: 'test_id' },
+  { toolPrefix: 'suites', resourceKey: 'suite_id' },
+  { toolPrefix: 'testruns', resourceKey: 'testrun_id' },
+];

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/attachments.js

@@ -0,0 +1,70 @@
+function buildAttachmentTools({ toolPrefix, entityName, idKey, idType = 'string' }) {
+  const entityId = {
+    type: idType,
+  };
+
+  return [
+    {
+      name: `${toolPrefix}_attachments_list`,
+      description: `List attachments for a ${entityName} (/api/v2/{project_id}/attachments?${idKey}=...)`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          [idKey]: entityId,
+        },
+        required: [idKey],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: `${toolPrefix}_attachments_upload`,
+      description: `Upload one attachment to a ${entityName} (/api/v2/{project_id}/attachments?${idKey}=...)`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          [idKey]: entityId,
+          file_path: {
+            type: 'string',
+            description: 'Local path to the file that will be sent as multipart/form-data field "file".',
+          },
+        },
+        required: [idKey, 'file_path'],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: `${toolPrefix}_attachments_delete`,
+      description: `Delete attachment from a ${entityName} (/api/v2/{project_id}/attachments/{id}?${idKey}=...)`,
+      inputSchema: {
+        type: 'object',
+        properties: {
+          [idKey]: entityId,
+          attachment_id: {
+            type: 'string',
+          },
+        },
+        required: [idKey, 'attachment_id'],
+        additionalProperties: false,
+      },
+    },
+  ];
+}
+
+export const ATTACHMENT_TOOLS = [
+  ...buildAttachmentTools({
+    toolPrefix: 'tests',
+    entityName: 'test',
+    idKey: 'test_id',
+  }),
+  ...buildAttachmentTools({
+    toolPrefix: 'suites',
+    entityName: 'suite',
+    idKey: 'suite_id',
+  }),
+  ...buildAttachmentTools({
+    toolPrefix: 'testruns',
+    entityName: 'testrun',
+    idKey: 'testrun_id',
+    idType: 'integer',
+  }),
+];

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": {}
+    }
   }
 ];