@testomatio/mcp 2.0.1 → 2.1.0-beta

package/README.md

@@ -6,14 +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)
+  - 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
-- **Safe TQL Guidance** - prefer documented expressions like `priority == high`, `state == automated`, `size == 5`, `size > 1`; do not guess undocumented TQL syntax; fall back only when the API rejects the TQL expression or the needed field is not supported
+- **Built-In TQL Reference** - MCP tool descriptions include exact TQL fields, syntax, and examples for agents
 
 ## Quick Start
 
@@ -23,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:**
@@ -135,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, "tql": "priority == high" }
+  "arguments": { "page": 1, "per_page": 50, "tql": "priority == 'high'" }
 }
 ```
 
@@ -240,9 +244,11 @@ 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** - 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 Safety** - Prefer documented expressions like `priority == high`, `state == automated`, `size == 5`, `size > 1`; do not invent tag-style or free-text syntax unless it was verified
-- **Fallback Rule** - For `tests` and `runs`, try `tql` first. Use other tools or extra analysis only after the API rejects the TQL expression or the needed field is not supported by TQL
+- **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
 
@@ -263,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.1",
+  "version": "2.1.0-beta",
   "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

@@ -92,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/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/requirements.js

@@ -0,0 +1,163 @@
+export const REQUIREMENTS_TOOLS = [
+  {
+    name: 'requirements_list',
+    description: 'List requirements (/api/v2/{project_id}/requirements)',
+    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,
+    },
+  },
+  {
+    name: 'requirements_get',
+    description: 'Get requirement by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        requirement_id: {
+          type: 'string',
+        },
+      },
+      required: ['requirement_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'requirements_create',
+    description: 'Create requirement (/api/v2/{project_id}/requirements)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+        },
+        source_type: {
+          type: 'string',
+          enum: ['jira', 'confluence', 'file', 'text'],
+        },
+        description: {
+          type: 'string',
+          description: 'Required for text requirements. Must be at least 500 characters.',
+        },
+        details: {
+          type: 'string',
+        },
+        active: {
+          type: 'boolean',
+        },
+        global: {
+          type: 'boolean',
+        },
+        confluence_url: {
+          type: 'string',
+          description: 'Required for confluence requirements.',
+        },
+        files: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: 'Local file paths to upload for file requirements.',
+        },
+      },
+      required: ['title', 'source_type'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'requirements_update',
+    description: 'Update requirement (/api/v2/{project_id}/requirements/{id})',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        requirement_id: {
+          type: 'string',
+        },
+        title: {
+          type: 'string',
+        },
+        description: {
+          type: 'string',
+          description: 'Only applied for text requirements.',
+        },
+        details: {
+          type: 'string',
+        },
+        active: {
+          type: 'boolean',
+        },
+        global: {
+          type: 'boolean',
+        },
+        files: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          description: 'Local file paths to upload for file requirements.',
+        },
+      },
+      required: ['requirement_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'requirements_delete',
+    description: 'Delete requirement (/api/v2/{project_id}/requirements/{id})',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        requirement_id: {
+          type: 'string',
+        },
+      },
+      required: ['requirement_id'],
+      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

@@ -1,7 +1,9 @@
+import { RUNS_TQL_INPUT_DESCRIPTION, RUNS_TQL_REFERENCE } from './tql-reference.js';
+
 export const RUNS_TOOLS = [
   {
     "name": "runs_list",
-    "description": "List runs (/api/v2/{project_id}/runs). Use `tql` first for search/filtering. Prefer known-safe expressions such as `size == 5` or `size > 1`. Do not guess undocumented TQL syntax. Fall back to other tools or analysis only if the API rejects the TQL expression or the needed field is not supported by TQL.",
+    "description": `List runs (/api/v2/{project_id}/runs). ${RUNS_TQL_REFERENCE}`,
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16,7 +18,7 @@ export const RUNS_TOOLS = [
         },
         "tql": {
           "type": "string",
-          "description": "Universal TQL filter for runs. Prefer known-safe expressions like `size == 5` or `size > 1`. Do not guess undocumented syntax. Fall back only if the API rejects the TQL expression or the needed field is not supported by TQL."
+          "description": RUNS_TQL_INPUT_DESCRIPTION
         }
       },
       "additionalProperties": false
@@ -264,7 +266,7 @@ export const RUNS_TOOLS = [
   },
   {
     "name": "runs_search",
-    "description": "Search runs using TQL (delegates to runs_list). Use `tql` first. Prefer known-safe expressions such as `size == 5` or `size > 1`. Do not guess undocumented TQL syntax. Fall back to other tools or analysis only if the API rejects the TQL expression or the needed field is not supported by TQL.",
+    "description": `Search runs using TQL (delegates to runs_list). ${RUNS_TQL_REFERENCE}`,
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -279,7 +281,7 @@ export const RUNS_TOOLS = [
         },
         "tql": {
           "type": "string",
-          "description": "Universal TQL filter for runs. Prefer known-safe expressions like `size == 5` or `size > 1`. Do not guess undocumented syntax. Fall back only if the API rejects the TQL expression or the needed field is not supported by TQL."
+          "description": RUNS_TQL_INPUT_DESCRIPTION
         }
       },
       "additionalProperties": false

package/src/mcp/definitions/tests.js

@@ -1,7 +1,9 @@
+import { TESTS_TQL_INPUT_DESCRIPTION, TESTS_TQL_REFERENCE } from './tql-reference.js';
+
 export const TESTS_TOOLS = [
   {
     "name": "tests_list",
-    "description": "List tests (/api/v2/{project_id}/tests). Use `tql` first for search/filtering. Prefer known-safe expressions such as `priority == high` or `state == automated`. Do not guess undocumented TQL syntax. Fall back to other tools or analysis only if the API rejects the TQL expression or the needed field is not supported by TQL.",
+    "description": `List tests (/api/v2/{project_id}/tests). ${TESTS_TQL_REFERENCE}`,
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -16,7 +18,7 @@ export const TESTS_TOOLS = [
         },
         "tql": {
           "type": "string",
-          "description": "Universal TQL filter for tests. Prefer known-safe expressions like `priority == high` or `state == automated`. Do not guess undocumented syntax. Fall back only if the API rejects the TQL expression or the needed field is not supported by TQL."
+          "description": TESTS_TQL_INPUT_DESCRIPTION
         }
       },
       "additionalProperties": false
@@ -207,7 +209,7 @@ export const TESTS_TOOLS = [
   },
   {
     "name": "tests_search",
-    "description": "Search tests using TQL (delegates to tests_list). Use `tql` first. Prefer known-safe expressions such as `priority == high` or `state == automated`. Do not guess undocumented TQL syntax. Fall back to other tools or analysis only if the API rejects the TQL expression or the needed field is not supported by TQL.",
+    "description": `Search tests using TQL (delegates to tests_list). ${TESTS_TQL_REFERENCE}`,
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -222,7 +224,7 @@ export const TESTS_TOOLS = [
         },
         "tql": {
           "type": "string",
-          "description": "Universal TQL filter for tests. Prefer known-safe expressions like `priority == high` or `state == automated`. Do not guess undocumented syntax. Fall back only if the API rejects the TQL expression or the needed field is not supported by TQL."
+          "description": TESTS_TQL_INPUT_DESCRIPTION
         }
       },
       "additionalProperties": false

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

@@ -0,0 +1,133 @@
+const TESTS_TQL_VARIABLES = [
+  'tag',
+  'label',
+  'priority',
+  'issue',
+  'jira',
+  'state',
+  'status',
+  'custom_status',
+  'created_at',
+  'updated_at',
+  'last_run_at',
+  'executed_at',
+  'created_by',
+  'assigned_to',
+  'suite',
+  'test',
+];
+
+const RUNS_TQL_VARIABLES = [
+  'title',
+  'plan',
+  'rungroup',
+  'env',
+  'tag',
+  'label',
+  'jira',
+  'duration',
+  'passed_count',
+  'failed_count',
+  'skipped_count',
+  'automated',
+  'manual',
+  'mixed',
+  'finished',
+  'unfinished',
+  'passed',
+  'failed',
+  'terminated',
+  'published',
+  'private',
+  'archived',
+  'unarchived',
+  'with_defect',
+  'has_defect',
+  'has_test',
+  'has_test_tag',
+  'has_test_label',
+  'has_suite',
+  'has_message',
+  'has_custom_status',
+  'has_assigned_to',
+  'has_retries',
+  'has_test_duration',
+  'has_priority',
+  'created_at',
+  'updated_at',
+  'launched_at',
+  'finished_at',
+];
+
+const TESTS_TQL_EXAMPLES = [
+  "priority == 'high'",
+  "state == 'automated'",
+  "tag in ['smoke', 'stage1'] and status == 'failed'",
+  "suite % 'Checkout'",
+  "test % 'User login'",
+  "created_at < 1.month_ago",
+  "jira in ['JST-1', 'JST-2']",
+];
+
+const RUNS_TQL_EXAMPLES = [
+  "title % 'Manual tests'",
+  "plan == '{PLAN_ID}'",
+  "env in ['Windows', 'Linux']",
+  "failed and has_test_tag == 'regression'",
+  'finished and with_defect',
+  'has_retries > 2',
+  "automated and env == 'Production' and has_message % 'Server Error'",
+  "finished_at >= '2025-07-01' and finished_at <= '2025-07-31' and failed",
+];
+
+const COMMON_TQL_SYNTAX =
+  "Supported syntax includes `==`, `!=`, `>`, `<`, `>=`, `<=`, `in [...]`, `%` for partial text match, `and`, `or`, `not`, and parentheses for grouping. 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.';
+
+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 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(', ')}.`;
+
+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(', ')}.`;
+
+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.';
+
+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(', ')}.`;

package/src/mcp/registry/handlers.js

@@ -59,6 +59,10 @@ export const handlerMethods = {
     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_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_create = async (args = {}) => this.asText(await this.createIssue(args));
@@ -84,6 +88,9 @@ export const handlerMethods = {
     if (spec.createMode === 'run') {
       return this.createRunWithFallback(args);
     }
+    if (spec.createMode === 'requirement') {
+      return this.createRequirement(args);
+    }
     const payload = this[spec.payloadBuilder](args);
     return this.createWrapped(spec.resource, spec.wrapperKey, payload);
   },
@@ -92,7 +99,13 @@ export const handlerMethods = {
     if (spec.updateMode === 'run') {
       return this.updateRunWithFallback(id, args);
     }
+    if (spec.updateMode === 'requirement') {
+      return this.updateRequirement(id, args);
+    }
     const payload = this[spec.payloadBuilder](args);
+    if (spec.updateMethod === 'patch') {
+      return this.patchWrapped(spec.resource, id, spec.wrapperKey, payload);
+    }
     return this.updateWrapped(spec.resource, id, spec.wrapperKey, payload);
   },
 };

package/src/mcp/registry/listings.js

@@ -136,6 +136,18 @@ export const listingMethods = {
     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 });
+  },
+
   listTags() {
     return this.apiClient.list('tags');
   },

package/src/mcp/registry/payloads.js

@@ -1,3 +1,6 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
 export const payloadMethods = {
   async createWrapped(resource, wrapperKey, payload) {
     const wrappedBody = { [wrapperKey]: payload };
@@ -23,6 +26,70 @@ export const payloadMethods = {
     }
   },
 
+  async patchWrapped(resource, id, wrapperKey, payload) {
+    const wrappedBody = { [wrapperKey]: payload };
+    try {
+      return await this.apiClient.patch(resource, id, payload);
+    } catch (error) {
+      if (!this.shouldRetryWrappedBody(error, wrapperKey)) {
+        throw error;
+      }
+      return this.apiClient.patch(resource, id, wrappedBody);
+    }
+  },
+
+  async createRequirement(args = {}) {
+    const { files, ...payloadArgs } = args;
+    const payload = this.buildRequirementPayload(payloadArgs);
+
+    if (this.hasFiles(files)) {
+      return this.apiClient.createMultipart(
+        'requirements',
+        await this.buildRequirementFormData(payload, files)
+      );
+    }
+
+    return this.createWrapped('requirements', 'requirement', payload);
+  },
+
+  async updateRequirement(requirementId, args = {}) {
+    const { files, ...payloadArgs } = args;
+    const payload = this.buildRequirementPayload(payloadArgs);
+
+    if (this.hasFiles(files)) {
+      return this.apiClient.patchMultipart(
+        'requirements',
+        requirementId,
+        await this.buildRequirementFormData(payload, files)
+      );
+    }
+
+    return this.patchWrapped('requirements', requirementId, 'requirement', payload);
+  },
+
+  hasFiles(files) {
+    return Array.isArray(files) && files.length > 0;
+  },
+
+  async buildRequirementFormData(payload, files = []) {
+    const formData = new FormData();
+
+    Object.entries(payload).forEach(([key, value]) => {
+      if (value === undefined || value === null) {
+        return;
+      }
+      formData.append(key, typeof value === 'boolean' ? String(value) : value);
+    });
+
+    for (const filePath of files) {
+      const resolvedPath = path.resolve(String(filePath));
+      const data = await fs.readFile(resolvedPath);
+      formData.append('files', new Blob([data]), path.basename(resolvedPath));
+    }
+
+    return formData;
+  },
+
   buildTestPayload({
     title,
     suite_id: suiteId,
@@ -262,4 +329,24 @@ export const payloadMethods = {
       link,
     };
   },
+
+  buildRequirementPayload({
+    title,
+    source_type: sourceType,
+    description,
+    details,
+    active,
+    global,
+    confluence_url: confluenceUrl,
+  } = {}) {
+    return {
+      title,
+      source_type: sourceType,
+      description,
+      details,
+      active,
+      global,
+      confluence_url: confluenceUrl,
+    };
+  },
 };

package/src/mcp/server.js

@@ -7,14 +7,30 @@ import { createLogger } from '../core/logger.js';
 import { getPackageVersion } from '../config/package-version.js';
 
 export class TestomatioMCPServer {
-  constructor({ config, apiClient, logger }) {
+  constructor({
+    config,
+    apiClient,
+    logger,
+    tools = TOOL_DEFINITIONS,
+    name = 'testomatio-mcp-server',
+    registryOptions = {},
+  }) {
     this.config = config;
+    this.apiClient = apiClient;
     this.logger = logger || createLogger();
-    this.toolRegistry = new ToolRegistry({ config, apiClient, logger: this.logger });
+    this.tools = tools;
+    this.toolRegistry = new ToolRegistry({
+      config,
+      apiClient,
+      logger: this.logger,
+      tools,
+      ...registryOptions,
+    });
+    this.cleanupStarted = false;
 
     this.server = new Server(
       {
-        name: 'testomatio-mcp-server',
+        name,
         version: getPackageVersion(),
       },
       {
@@ -29,7 +45,7 @@ export class TestomatioMCPServer {
 
   setupHandlers() {
     this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-      tools: TOOL_DEFINITIONS,
+      tools: this.tools,
     }));
 
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -44,6 +60,33 @@ export class TestomatioMCPServer {
   async run() {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
+    this.installSessionCleanup();
     this.logger.info('Testomatio MCP server started');
   }
+
+  installSessionCleanup() {
+    const cleanup = async () => {
+      if (this.cleanupStarted) {
+        return;
+      }
+
+      this.cleanupStarted = true;
+      await this.apiClient?.stopSession?.();
+    };
+
+    this.server.onclose = () => {
+      void cleanup();
+    };
+
+    process.once('beforeExit', () => {
+      void cleanup();
+    });
+
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.once(signal, async () => {
+        await cleanup();
+        process.exit(0);
+      });
+    }
+  }
 }

package/src/mcp/tool-definitions.js

@@ -8,8 +8,10 @@ import { STEPS_TOOLS } from './definitions/steps.js';
 import { SNIPPETS_TOOLS } from './definitions/snippets.js';
 import { LABELS_TOOLS } from './definitions/labels.js';
 import { TAGS_TOOLS } from './definitions/tags.js';
+import { MILESTONES_TOOLS } from './definitions/milestones.js';
 import { ISSUES_TOOLS } from './definitions/issues.js';
 import { PLANS_TOOLS } from './definitions/plans.js';
+import { REQUIREMENTS_TOOLS } from './definitions/requirements.js';
 
 export const TOOL_DEFINITIONS = [
   ...SYSTEM_TOOLS,
@@ -22,6 +24,8 @@ export const TOOL_DEFINITIONS = [
   ...SNIPPETS_TOOLS,
   ...LABELS_TOOLS,
   ...TAGS_TOOLS,
+  ...MILESTONES_TOOLS,
   ...ISSUES_TOOLS,
   ...PLANS_TOOLS,
+  ...REQUIREMENTS_TOOLS,
 ];

package/src/mcp/tool-registry.js

@@ -12,10 +12,12 @@ function formatJson(payload) {
 }
 
 export class ToolRegistry {
-  constructor({ config, apiClient, logger }) {
+  constructor({ config, apiClient, logger, tools = TOOL_DEFINITIONS, handlerRegistrars = [] }) {
     this.config = config;
     this.apiClient = apiClient;
     this.logger = logger;
+    this.tools = tools;
+    this.handlerRegistrars = handlerRegistrars;
     this.handlers = this.buildHandlers();
   }
 
@@ -37,8 +39,11 @@ export class ToolRegistry {
     this.registerEntityCrudHandlers(handlers);
     this.registerScopedIssueHandlers(handlers);
     this.registerGlobalHandlers(handlers);
+    for (const registerHandlers of this.handlerRegistrars) {
+      registerHandlers.call(this, handlers);
+    }
 
-    for (const tool of TOOL_DEFINITIONS) {
+    for (const tool of this.tools) {
       if (tool.name === 'system_ping') continue;
       if (!handlers[tool.name]) {
         handlers[tool.name] = async () => textResponse(`${DEFAULT_TOOL_RESPONSE} (${tool.name})`);