@testomatio/mcp 2.0.0 → 2.0.1-beta.1

package/README.md

@@ -6,12 +6,16 @@ Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor,
 
 - **Full CRUD** for core entities:
   - Tests, Suites, Plans, Runs, TestRuns, RunGroups, Steps, Snippets, Labels
-  - Tags (read-only access)
+  - Tags and Milestones (read-only access)
   - Issues (global + scoped helpers for tests/suites/runs/testruns/plans)
-- **Smart Search** - delegates to list endpoints with query/filter forwarding
+  - Requirements (including file uploads from local file paths)
+- **Smart Search** - delegates to list endpoints with OpenAPI-aligned query/filter forwarding
 - **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
 
 ## Quick Start
 
@@ -21,6 +25,8 @@ Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor,
 npm install -g @testomatio/mcp@latest
 ```
 
+Need enterprise analytics tools? Install `@testomatio/mcp-enterprise@latest` instead. Details are in the `Enterprise Analytics` section below.
+
 ### Configuration
 
 **Required credentials:**
@@ -133,7 +139,7 @@ Add this config to `opencode.json` in your project root, or to `~/.config/openco
 ```json
 {
   "name": "tests_list",
-  "arguments": { "page": 1, "per_page": 50 }
+  "arguments": { "page": 1, "per_page": 50, "tql": "priority == 'high'" }
 }
 ```
 
@@ -178,16 +184,16 @@ Complete tool reference: [docs/tools.md](./docs/tools.md)
 
 ## Project Structure
 
-```
+```text
 src/
-├── config/          # Config loading, defaults
-├── core/            # Errors, logger
-├── api/             # HTTP client, Testomat.io API client
-├── mcp/             # MCP server, tools, registry
-│   ├── definitions/ # Tool definitions by entity
-│   ├── configs/     # Registry generation configs
-│   └── registry/    # Tool handlers
-└── cli/             # CLI bootstrap
+|- config/          # Config loading, defaults
+|- core/            # Errors, logger
+|- api/             # HTTP client, Testomat.io API client
+|- mcp/             # MCP server, tools, registry
+|  |- definitions/  # Tool definitions by entity
+|  |- configs/      # Registry generation configs
+|  `- registry/     # Tool handlers
+`- cli/             # CLI bootstrap
 ```
 
 ## Environment Variables
@@ -236,8 +242,13 @@ 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; search uses list with filters
+- **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`
+- **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`
 - **Issue Linking** - Scoped helpers available: `{entity}_issues_link/unlink`
+- **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.
 
 ## Development
 
@@ -258,3 +269,55 @@ For local MCP development, point Claude Desktop to the checked-out entrypoint:
   }
 }
 ```
+
+## Enterprise Analytics
+
+Enterprise analytics is available only in the separate `@testomatio/mcp-enterprise` package.
+
+Installation:
+
+```bash
+npm install -g @testomatio/mcp-enterprise@latest
+```
+
+Run:
+
+```bash
+testomatio-mcp-enterprise --token <PROJECT_TOKEN> --project <PROJECT_ID>
+```
+
+Included tools:
+
+- `analytics_tests` - `GET /api/v2/{project_id}/analytics/tests/{kind}`
+- `analytics_stats` - `GET /api/v2/{project_id}/analytics/stats/{kind}`
+
+Analytics endpoints require the `api_analytics` subscription feature. Use `q` as the TQL filter parameter for analytics tools.
+
+Example `analytics_tests` call:
+
+```json
+{
+  "name": "analytics_tests",
+  "arguments": {
+    "kind": "flaky",
+    "q": "priority == 'high'",
+    "days": 30,
+    "page": 1,
+    "per_page": 20
+  }
+}
+```
+
+Example `analytics_stats` call:
+
+```json
+{
+  "name": "analytics_stats",
+  "arguments": {
+    "kind": "success-rate-by-date",
+    "q": "tag IN ['@smoke']",
+    "from": "2026-04-01",
+    "to": "2026-04-30"
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testomatio/mcp",
-  "version": "2.0.0",
+  "version": "2.0.1-beta.1",
   "description": "Model Context Protocol server for Testomatio API",
   "main": "src/index.js",
   "bin": {
@@ -9,7 +9,8 @@
   "type": "module",
   "scripts": {
     "start": "node index.js",
-    "dev": "node index.js"
+    "dev": "node index.js",
+    "sync:enterprise-package": "node scripts/sync-enterprise-package.js"
   },
   "keywords": [
     "testomatio",

package/src/api/http-client.js

@@ -1,5 +1,9 @@
 import { ApiError } from '../core/errors.js';
 
+function isFormData(body) {
+  return typeof FormData !== 'undefined' && body instanceof FormData;
+}
+
 function buildUrl(baseUrl, path, query = {}) {
   const url = new URL(path, `${baseUrl}/`);
 
@@ -26,12 +30,13 @@ export class HttpClient {
     this.logger = logger;
   }
 
-  async request(method, path, { query, body } = {}) {
+  async request(method, path, { query, body, headers: requestHeaders = {} } = {}) {
     const url = buildUrl(this.baseUrl, path, query);
 
     const headers = {
       Accept: 'application/json',
       Authorization: `Bearer ${this.token}`,
+      ...requestHeaders,
     };
 
     const options = {
@@ -40,8 +45,12 @@ export class HttpClient {
     };
 
     if (body !== undefined) {
-      headers['Content-Type'] = 'application/json';
-      options.body = JSON.stringify(body);
+      if (isFormData(body)) {
+        options.body = body;
+      } else {
+        headers['Content-Type'] = 'application/json';
+        options.body = JSON.stringify(body);
+      }
     }
 
     this.logger.debug('HTTP request', { method, url });

package/src/api/testomatio-client.js

@@ -3,6 +3,9 @@ import { HttpClient } from './http-client.js';
 export class TestomatioApiClient {
   constructor({ baseUrl, projectId, token, logger }) {
     this.projectId = projectId;
+    this.logger = logger;
+    this.sessionHash = null;
+    this.sessionPromise = null;
     this.http = new HttpClient({
       baseUrl,
       token,
@@ -24,23 +27,101 @@ export class TestomatioApiClient {
     return this.http.request('GET', this.buildPath(resource, id), { query });
   }
 
-  create(resource, body = {}) {
-    return this.http.request('POST', this.buildPath(resource), { body });
+  async create(resource, body = {}) {
+    return this.mutate('POST', this.buildPath(resource), { body });
   }
 
-  createWithQuery(resource, { query = {}, body = {} } = {}) {
-    return this.http.request('POST', this.buildPath(resource), { query, body });
+  async createMultipart(resource, formData) {
+    return this.mutate('POST', this.buildPath(resource), { body: formData });
   }
 
-  update(resource, id, body = {}) {
-    return this.http.request('PUT', this.buildPath(resource, id), { body });
+  async createWithQuery(resource, { query = {}, body = {} } = {}) {
+    return this.mutate('POST', this.buildPath(resource), { query, body });
   }
 
-  delete(resource, id, query = {}) {
-    return this.http.request('DELETE', this.buildPath(resource, id), { query });
+  async update(resource, id, body = {}) {
+    return this.mutate('PUT', this.buildPath(resource, id), { body });
+  }
+
+  async patch(resource, id, body = {}) {
+    return this.mutate('PATCH', this.buildPath(resource, id), { body });
+  }
+
+  async patchMultipart(resource, id, formData) {
+    return this.mutate('PATCH', this.buildPath(resource, id), { body: formData });
+  }
+
+  async delete(resource, id, query = {}) {
+    return this.mutate('DELETE', this.buildPath(resource, id), { query });
   }
 
   search(resource, query = {}) {
     return this.list(resource, query);
   }
+
+  async mutate(method, path, options = {}) {
+    const sessionHash = await this.ensureSession();
+    return this.http.request(method, path, {
+      ...options,
+      headers: {
+        ...options.headers,
+        'X-Session-Hash': sessionHash,
+      },
+    });
+  }
+
+  async ensureSession() {
+    if (this.sessionHash) {
+      return this.sessionHash;
+    }
+
+    if (!this.sessionPromise) {
+      this.sessionPromise = this.startSession().finally(() => {
+        this.sessionPromise = null;
+      });
+    }
+
+    return this.sessionPromise;
+  }
+
+  async startSession() {
+    const response = await this.http.request('POST', this.buildPath('sessions'), {
+      body: { description: 'MCP session' },
+    });
+    const sessionHash = response?.data?.hash || response?.hash;
+
+    if (!sessionHash) {
+      throw new Error('Failed to start Testomat.io API session: missing session hash');
+    }
+
+    this.sessionHash = sessionHash;
+    return sessionHash;
+  }
+
+  async stopSession() {
+    if (this.sessionPromise) {
+      try {
+        await this.sessionPromise;
+      } catch {
+        return;
+      }
+    }
+
+    if (!this.sessionHash) {
+      return;
+    }
+
+    const sessionHash = this.sessionHash;
+    this.sessionHash = null;
+
+    try {
+      await this.http.request('DELETE', this.buildPath('sessions', sessionHash));
+    } catch (error) {
+      if (error?.status !== 404) {
+        this.logger?.error('Failed to stop Testomat.io API session', {
+          error: error?.message || error,
+        });
+      }
+    }
+  }
 }

package/src/index.js

@@ -1,15 +1,36 @@
 import { TestomatioApiClient } from './api/testomatio-client.js';
 import { loadConfig } from './config/load-config.js';
+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 {
+  ANALYTICS_STATS_TQL_INPUT_DESCRIPTION,
+  ANALYTICS_STATS_TQL_REFERENCE,
+  ANALYTICS_TESTS_TQL_INPUT_DESCRIPTION,
+  ANALYTICS_TESTS_TQL_REFERENCE,
+} from './mcp/definitions/tql-reference.js';
 
 export { TestomatioMCPServer };
+export {
+  ANALYTICS_STATS_TQL_INPUT_DESCRIPTION,
+  ANALYTICS_STATS_TQL_REFERENCE,
+  ANALYTICS_TESTS_TQL_INPUT_DESCRIPTION,
+  ANALYTICS_TESTS_TQL_REFERENCE,
+  ConfigurationError,
+  TOOL_DEFINITIONS,
+};
 
-export function createApplication(argvOptions = {}) {
+export function createApplication(argvOptions = {}, serverOptions = {}) {
   const config = loadConfig(argvOptions);
   const logger = createLogger();
   const apiClient = new TestomatioApiClient({ ...config, logger });
-  const mcpServer = new TestomatioMCPServer({ config, apiClient, logger });
+  const mcpServer = new TestomatioMCPServer({
+    config,
+    apiClient,
+    logger,
+    ...serverOptions,
+  });
 
   return {
     config,

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

@@ -46,7 +46,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'rungroups',
     idArg: 'rungroup_id',
     listMethod: 'listRungroups',
-    searchMethod: 'searchRungroups',
     payloadBuilder: 'buildRungroupPayload',
     wrapperKey: 'rungroup',
     createMode: 'wrapped',
@@ -57,7 +56,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'steps',
     idArg: 'step_id',
     listMethod: 'listSteps',
-    searchMethod: 'searchSteps',
     payloadBuilder: 'buildStepPayload',
     wrapperKey: 'step',
     createMode: 'wrapped',
@@ -68,7 +66,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'snippets',
     idArg: 'snippet_id',
     listMethod: 'listSnippets',
-    searchMethod: 'searchSnippets',
     payloadBuilder: 'buildSnippetPayload',
     wrapperKey: 'snippet',
     createMode: 'wrapped',
@@ -79,7 +76,6 @@ export const ENTITY_CRUD_CONFIGS = [
     resource: 'labels',
     idArg: 'label_id',
     listMethod: 'listLabels',
-    searchMethod: 'searchLabels',
     payloadBuilder: 'buildLabelPayload',
     wrapperKey: 'label',
     createMode: 'wrapped',
@@ -96,4 +92,16 @@ export const ENTITY_CRUD_CONFIGS = [
     createMode: 'wrapped',
     updateMode: 'wrapped',
   },
+  {
+    toolPrefix: 'requirements',
+    resource: 'requirements',
+    idArg: 'requirement_id',
+    listMethod: 'listRequirements',
+    searchMethod: 'searchRequirements',
+    payloadBuilder: 'buildRequirementPayload',
+    wrapperKey: 'requirement',
+    createMode: 'requirement',
+    updateMode: 'requirement',
+    updateMethod: 'patch',
+  },
 ];

package/src/mcp/definitions/labels.js

@@ -13,9 +13,6 @@ export const LABELS_TOOLS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 100
-        },
-        "query": {
-          "type": "string"
         }
       },
       "additionalProperties": false
@@ -148,26 +145,4 @@ export const LABELS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "labels_search",
-    "description": "Search labels (delegates to labels list; docs has no dedicated search parameter)",
-    "inputSchema": {
-      "type": "object",
-      "properties": {
-        "query": {
-          "type": "string"
-        },
-        "page": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "per_page": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100
-        }
-      },
-      "additionalProperties": false
-    }
-  }
 ];

package/src/mcp/definitions/milestones.js

@@ -0,0 +1,43 @@
+export const MILESTONES_TOOLS = [
+  {
+    name: 'milestones_list',
+    description: 'List milestones (/api/v2/{project_id}/milestones)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: {
+          type: 'integer',
+          minimum: 1,
+        },
+        per_page: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 100,
+        },
+        type: {
+          type: 'string',
+          description: 'Filter by milestone type (title), e.g. Sprint or Release.',
+        },
+        status: {
+          type: 'string',
+          enum: ['created', 'active', 'closed'],
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'milestones_get',
+    description: 'Get milestone by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        milestone_id: {
+          type: 'string',
+        },
+      },
+      required: ['milestone_id'],
+      additionalProperties: false,
+    },
+  },
+];

package/src/mcp/definitions/plans.js

@@ -14,7 +14,24 @@ export const PLANS_TOOLS = [
           "minimum": 1,
           "maximum": 100
         },
-        "query": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "automated",
+            "mixed"
+          ]
+        },
+        "hidden": {
+          "type": "boolean"
+        },
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "search_text": {
           "type": "string"
         }
       },
@@ -95,6 +112,7 @@ export const PLANS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -179,6 +197,7 @@ export const PLANS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -224,7 +243,7 @@ export const PLANS_TOOLS = [
     "inputSchema": {
       "type": "object",
       "properties": {
-        "query": {
+        "search_text": {
           "type": "string"
         },
         "page": {
@@ -235,6 +254,23 @@ export const PLANS_TOOLS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 100
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "automated",
+            "mixed"
+          ]
+        },
+        "hidden": {
+          "type": "boolean"
+        },
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       },
       "additionalProperties": false