@testomatio/mcp 2.0.0-beta.9 → 2.0.1-beta

package/README.md

@@ -8,17 +8,19 @@ Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor,
   - Tests, Suites, Plans, Runs, TestRuns, RunGroups, Steps, Snippets, Labels
   - Tags (read-only access)
   - Issues (global + scoped helpers for tests/suites/runs/testruns/plans)
-- **Smart Search** - delegates to list endpoints with query/filter forwarding
+- **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)
 - **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
 
 ## Quick Start
 
 ### Installation
 
 ```bash
-npm install -g @testomatio/mcp
+npm install -g @testomatio/mcp@latest
 ```
 
 ### Configuration
@@ -48,17 +50,24 @@ export TESTOMATIO_BASE_URL=https://beta.testomat.io
 
 ### Cursor IDE
 
-Add to `.cursorrules` or settings.json:
+Add this config to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for global access:
 
 ```json
 {
   "mcpServers": {
     "testomatio": {
-      "command": "testomatio-mcp",
-      "args": ["--token", "<TOKEN>", "--project", "<PROJECT_ID>"],
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@testomatio/mcp@latest",
+        "--token",
+        "<TOKEN>",
+        "--project",
+        "<PROJECT_ID>"
+      ],
       "env": {
-        "TESTOMATIO_PROJECT_TOKEN": "<TOKEN>",
-        "TESTOMATIO_PROJECT_ID": "<PROJECT_ID>"
+        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
       }
     }
   }
@@ -67,12 +76,26 @@ Add to `.cursorrules` or settings.json:
 
 ### Claude Desktop
 
+Add this config to:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
     "testomatio": {
-      "command": "node",
-      "args": ["/path/to/mcp/index.js", "--token", "<TOKEN>", "--project", "<PROJECT_ID>"]
+      "command": "npx",
+      "args": [
+        "-y",
+        "@testomatio/mcp@latest",
+        "--token",
+        "<TOKEN>",
+        "--project",
+        "<PROJECT_ID>"
+      ],
+      "env": {
+        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
+      }
     }
   }
 }
@@ -80,7 +103,7 @@ Add to `.cursorrules` or settings.json:
 
 ### OpenCode
 
-Create `.opencode/opencode.json`:
+Add this config to `opencode.json` in your project root, or to `~/.config/opencode/opencode.json` for global access:
 
 ```json
 {
@@ -89,8 +112,9 @@ Create `.opencode/opencode.json`:
     "testomat": {
       "type": "local",
       "command": [
-        "node",
-        "node_modules/@testomatio/mcp/index.js",
+        "npx",
+        "-y",
+        "@testomatio/mcp@latest",
         "--token",
         "<TOKEN>",
         "--project",
@@ -111,7 +135,7 @@ Create `.opencode/opencode.json`:
 ```json
 {
   "name": "tests_list",
-  "arguments": { "page": 1, "per_page": 50 }
+  "arguments": { "page": 1, "per_page": 50, "tql": "priority == high" }
 }
 ```
 
@@ -156,16 +180,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
@@ -179,10 +203,45 @@ src/
 
 *Either `TESTOMATIO_PROJECT_TOKEN` or `TESTOMATIO_API_TOKEN`
 
+## Corporate TLS Certificates
+
+If the MCP server runs behind a corporate proxy or TLS inspection, Node.js may reject Testomat.io HTTPS requests even when the same URL works in a browser. This usually means the company root certificate is trusted by the operating system, but not by Node.js.
+
+Use Node.js system CA support:
+
+```bash
+NODE_OPTIONS=--use-system-ca testomatio-mcp --token <TOKEN> --project <PROJECT_ID>
+```
+
+For MCP clients, pass `NODE_OPTIONS` in the server environment:
+
+```json
+{
+  "mcpServers": {
+    "testomatio": {
+      "command": "testomatio-mcp",
+      "args": ["--token", "<TOKEN>", "--project", "<PROJECT_ID>"],
+      "env": {
+        "NODE_OPTIONS": "--use-system-ca"
+      }
+    }
+  }
+}
+```
+
+If your Node.js version does not support `--use-system-ca`, export the corporate root certificate to a PEM file and use Node.js extra CA support:
+
+```bash
+NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token <TOKEN> --project <PROJECT_ID>
+```
+
 ## 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 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
 - **Issue Linking** - Scoped helpers available: `{entity}_issues_link/unlink`
 
 ## Development
@@ -191,3 +250,16 @@ src/
 npm install
 npm run start -- --token <TOKEN> --project <PROJECT_ID>
 ```
+
+For local MCP development, point Claude Desktop to the checked-out entrypoint:
+
+```json
+{
+  "mcpServers": {
+    "testomatio-local": {
+      "command": "node",
+      "args": ["/path/to/mcp/index.js", "--token", "<TOKEN>", "--project", "<PROJECT_ID>"]
+    }
+  }
+}
+```

package/package.json

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

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',

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/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

package/src/mcp/definitions/rungroups.js

@@ -13,9 +13,6 @@ export const RUNGROUPS_TOOLS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 100
-        },
-        "query": {
-          "type": "string"
         }
       },
       "additionalProperties": false
@@ -130,26 +127,4 @@ export const RUNGROUPS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "rungroups_search",
-    "description": "Search run groups (delegates to rungroups 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/runs.js

@@ -1,7 +1,7 @@
 export const RUNS_TOOLS = [
   {
     "name": "runs_list",
-    "description": "List runs (/api/v2/{project_id}/runs)",
+    "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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -14,8 +14,9 @@ export const RUNS_TOOLS = [
           "minimum": 1,
           "maximum": 100
         },
-        "query": {
-          "type": "string"
+        "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."
         }
       },
       "additionalProperties": false
@@ -49,8 +50,11 @@ export const RUNS_TOOLS = [
         "description": {
           "type": "string"
         },
-        "plan_id": {
-          "type": "string"
+        "plan_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         },
         "kind": {
           "type": "string",
@@ -95,9 +99,6 @@ export const RUNS_TOOLS = [
             "type": "string"
           }
         },
-        "configuration": {
-          "type": "object"
-        },
         "link": {
           "type": "array",
           "items": {
@@ -116,6 +117,7 @@ export const RUNS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -154,9 +156,6 @@ export const RUNS_TOOLS = [
         "description": {
           "type": "string"
         },
-        "plan_id": {
-          "type": "string"
-        },
         "kind": {
           "type": "string",
           "enum": [
@@ -205,9 +204,6 @@ export const RUNS_TOOLS = [
             "type": "string"
           }
         },
-        "configuration": {
-          "type": "object"
-        },
         "link": {
           "type": "array",
           "items": {
@@ -226,6 +222,7 @@ export const RUNS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -267,13 +264,10 @@ export const RUNS_TOOLS = [
   },
   {
     "name": "runs_search",
-    "description": "Search runs (delegates to runs list; docs has no dedicated search parameter)",
+    "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.",
     "inputSchema": {
       "type": "object",
       "properties": {
-        "query": {
-          "type": "string"
-        },
         "page": {
           "type": "integer",
           "minimum": 1
@@ -282,6 +276,10 @@ export const RUNS_TOOLS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 100
+        },
+        "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."
         }
       },
       "additionalProperties": false

package/src/mcp/definitions/snippets.js

@@ -13,9 +13,6 @@ export const SNIPPETS_TOOLS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 100
-        },
-        "query": {
-          "type": "string"
         }
       },
       "additionalProperties": false
@@ -67,6 +64,7 @@ export const SNIPPETS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -123,6 +121,7 @@ export const SNIPPETS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -162,26 +161,4 @@ export const SNIPPETS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "snippets_search",
-    "description": "Search snippets (delegates to snippets 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/steps.js

@@ -13,9 +13,6 @@ export const STEPS_TOOLS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 100
-        },
-        "query": {
-          "type": "string"
         }
       },
       "additionalProperties": false
@@ -67,6 +64,7 @@ export const STEPS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -123,6 +121,7 @@ export const STEPS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -162,26 +161,4 @@ export const STEPS_TOOLS = [
       "additionalProperties": false
     }
   },
-  {
-    "name": "steps_search",
-    "description": "Search steps (delegates to steps 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/suites.js

@@ -29,9 +29,6 @@ export const SUITES_TOOLS = [
         },
         "search_text": {
           "type": "string"
-        },
-        "query": {
-          "type": "string"
         }
       },
       "additionalProperties": false
@@ -101,8 +98,10 @@ export const SUITES_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
-                  "jira"
+                  "jira",
+                  "requirement"
                 ]
               },
               "value": {
@@ -175,8 +174,10 @@ export const SUITES_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
-                  "jira"
+                  "jira",
+                  "requirement"
                 ]
               },
               "value": {
@@ -223,9 +224,6 @@ export const SUITES_TOOLS = [
         "search_text": {
           "type": "string"
         },
-        "query": {
-          "type": "string"
-        },
         "page": {
           "type": "integer",
           "minimum": 1

package/src/mcp/definitions/testruns.js

@@ -17,8 +17,104 @@ export const TESTRUNS_TOOLS = [
         "run_id": {
           "type": "string"
         },
-        "query": {
+        "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"
+        },
+        "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
@@ -142,7 +238,51 @@ export const TESTRUNS_TOOLS = [
         "run_id": {
           "type": "string"
         },
-        "query": {
+        "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": {
@@ -153,6 +293,58 @@ export const TESTRUNS_TOOLS = [
           "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

package/src/mcp/definitions/tests.js

@@ -1,7 +1,7 @@
 export const TESTS_TOOLS = [
   {
     "name": "tests_list",
-    "description": "List tests (/api/v2/{project_id}/tests)",
+    "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.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -14,23 +14,9 @@ export const TESTS_TOOLS = [
           "minimum": 1,
           "maximum": 100
         },
-        "suite_id": {
-          "type": "string"
-        },
-        "search_text": {
-          "type": "string"
-        },
-        "query": {
-          "type": "string"
-        },
-        "assigned_to": {
-          "type": "string"
-        },
-        "priority": {
-          "type": "string"
-        },
-        "state": {
-          "type": "string"
+        "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."
         }
       },
       "additionalProperties": false
@@ -100,6 +86,7 @@ export const TESTS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -178,6 +165,7 @@ export const TESTS_TOOLS = [
                   "label",
                   "custom_field",
                   "tag",
+                  "milestone",
                   "issue",
                   "jira"
                 ]
@@ -219,16 +207,10 @@ export const TESTS_TOOLS = [
   },
   {
     "name": "tests_search",
-    "description": "Search tests by text (delegates to tests list with search_text)",
+    "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.",
     "inputSchema": {
       "type": "object",
       "properties": {
-        "query": {
-          "type": "string"
-        },
-        "search_text": {
-          "type": "string"
-        },
         "page": {
           "type": "integer",
           "minimum": 1
@@ -238,17 +220,9 @@ export const TESTS_TOOLS = [
           "minimum": 1,
           "maximum": 100
         },
-        "suite_id": {
-          "type": "string"
-        },
-        "assigned_to": {
-          "type": "string"
-        },
-        "priority": {
-          "type": "string"
-        },
-        "state": {
-          "type": "string"
+        "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."
         }
       },
       "additionalProperties": false

package/src/mcp/registry/handlers.js

@@ -8,8 +8,10 @@ export const handlerMethods = {
 
       handlers[`${toolPrefix}_list`] = async (args = {}) =>
         this.asText(await this[listMethod](args));
-      handlers[`${toolPrefix}_search`] = async (args = {}) =>
-        this.asText(await this[searchMethod](args));
+      if (searchMethod) {
+        handlers[`${toolPrefix}_search`] = async (args = {}) =>
+          this.asText(await this[searchMethod](args));
+      }
       handlers[`${toolPrefix}_get`] = async (args = {}) =>
         this.asText(await this.apiClient.get(resource, this.pickRequiredArg(args, idArg)));
       handlers[`${toolPrefix}_create`] = async (args = {}) =>

package/src/mcp/registry/listings.js

@@ -1,93 +1,139 @@
 export const listingMethods = {
-  listTests({ page, per_page: perPage, suite_id: suiteId, search_text: searchText, query, ...filters } = {}) {
+  listTests({
+    page,
+    per_page: perPage,
+    tql,
+  } = {}) {
     return this.apiClient.list('tests', {
       page,
       per_page: perPage,
-      suite_id: suiteId,
-      search_text: searchText || query,
-      ...filters,
+      tql,
     });
   },
 
-  searchTests({ query, search_text: searchText, ...rest } = {}) {
+  searchTests({ page, per_page: perPage, tql } = {}) {
     return this.listTests({
-      ...rest,
-      search_text: searchText || query,
+      page,
+      per_page: perPage,
+      tql,
     });
   },
 
-  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText, query } = {}) {
+  listSuites({ page, per_page: perPage, file_type: fileType, tag, labels, search_text: searchText } = {}) {
     return this.apiClient.list('suites', {
       page,
       per_page: perPage,
       file_type: fileType,
       tag,
       labels,
-      search_text: searchText || query,
+      search_text: searchText,
     });
   },
 
-  searchSuites({ query, search_text: searchText, ...rest } = {}) {
+  searchSuites({ search_text: searchText, ...rest } = {}) {
     return this.listSuites({
       ...rest,
-      search_text: searchText || query,
+      search_text: searchText,
     });
   },
 
-  listRuns({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('runs', { page, per_page: perPage, query });
-  },
-
-  searchRuns({ page, per_page: perPage, query } = {}) {
-    return this.listRuns({ page, per_page: perPage, query });
-  },
-
-  listTestruns({ page, per_page: perPage, run_id: runId, query } = {}) {
-    return this.apiClient.list('testruns', { page, per_page: perPage, run_id: runId, query });
-  },
-
-  searchTestruns({ page, per_page: perPage, run_id: runId, query } = {}) {
-    return this.listTestruns({ page, per_page: perPage, run_id: runId, query });
-  },
-
-  listRungroups({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('rungroups', { page, per_page: perPage, query });
-  },
-
-  searchRungroups({ page, per_page: perPage, query } = {}) {
-    return this.listRungroups({ page, per_page: perPage, query });
+  listRuns({
+    page,
+    per_page: perPage,
+    tql,
+  } = {}) {
+    return this.apiClient.list('runs', {
+      page,
+      per_page: perPage,
+      tql,
+    });
   },
 
-  listSteps({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('steps', { page, per_page: perPage, query });
+  searchRuns({ page, per_page: perPage, tql } = {}) {
+    return this.listRuns({ page, per_page: perPage, tql });
+  },
+
+  listTestruns({
+    page,
+    per_page: perPage,
+    run_id: runId,
+    test_ids: testIds,
+    filter_status: filterStatus,
+    filter_kind: filterKind,
+    filter_user: filterUser,
+    filter_priority: filterPriority,
+    filter_substatus: filterSubstatus,
+    filter_search: filterSearch,
+    filter_message: filterMessage,
+    filter_link: filterLink,
+    filter_finished_at_date_range: filterFinishedAtDateRange,
+    tags,
+    labels,
+    envs,
+    rungroups,
+    defects,
+  } = {}) {
+    return this.apiClient.list('testruns', {
+      page,
+      per_page: perPage,
+      run_id: runId,
+      test_ids: Array.isArray(testIds) ? testIds.join(',') : testIds,
+      'filter[status]': filterStatus,
+      'filter[kind]': filterKind,
+      'filter[user]': filterUser,
+      'filter[priority]': filterPriority,
+      'filter[substatus]': filterSubstatus,
+      'filter[search]': filterSearch,
+      'filter[message]': filterMessage,
+      'filter[link]': filterLink,
+      'filter[finished_at_date_range]': filterFinishedAtDateRange,
+      tags: Array.isArray(tags) ? tags.join(',') : tags,
+      labels: Array.isArray(labels) ? labels.join(',') : labels,
+      envs: Array.isArray(envs) ? envs.join(',') : envs,
+      rungroups: Array.isArray(rungroups) ? rungroups.join(',') : rungroups,
+      defects,
+    });
   },
 
-  searchSteps({ page, per_page: perPage, query } = {}) {
-    return this.listSteps({ page, per_page: perPage, query });
+  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,
+    });
   },
 
-  listSnippets({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('snippets', { page, per_page: perPage, query });
+  listRungroups({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('rungroups', { page, per_page: perPage });
   },
 
-  searchSnippets({ page, per_page: perPage, query } = {}) {
-    return this.listSnippets({ page, per_page: perPage, query });
+  listSteps({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('steps', { page, per_page: perPage });
   },
 
-  listLabels({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('labels', { page, per_page: perPage, query });
+  listSnippets({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('snippets', { page, per_page: perPage });
   },
 
-  searchLabels({ page, per_page: perPage, query } = {}) {
-    return this.listLabels({ page, per_page: perPage, query });
+  listLabels({ page, per_page: perPage } = {}) {
+    return this.apiClient.list('labels', { page, per_page: perPage });
   },
 
-  listPlans({ page, per_page: perPage, query } = {}) {
-    return this.apiClient.list('plans', { page, per_page: perPage, query });
+  listPlans({ page, per_page: perPage, kind, hidden, labels, search_text: searchText } = {}) {
+    return this.apiClient.list('plans', {
+      page,
+      per_page: perPage,
+      kind,
+      hidden,
+      'labels[]': labels,
+      search_text: searchText,
+    });
   },
 
-  searchPlans({ page, per_page: perPage, query } = {}) {
-    return this.listPlans({ page, per_page: perPage, query });
+  searchPlans({ page, per_page: perPage, search_text: searchText, ...rest } = {}) {
+    return this.listPlans({ page, per_page: perPage, search_text: searchText, ...rest });
   },
 
   listTags() {

package/src/mcp/registry/payloads.js

@@ -76,7 +76,7 @@ export const payloadMethods = {
   buildRunCreatePayload({
     title,
     description,
-    plan_id: planId,
+    plan_ids: planIds,
     kind,
     rungroup_id: rungroupId,
     env,
@@ -85,13 +85,12 @@ export const payloadMethods = {
     test_ids: testIds,
     suite_ids: suiteIds,
     envs,
-    configuration,
     link,
   } = {}) {
     return {
       title,
       description,
-      plan_id: planId,
+      plan_ids: planIds,
       kind,
       rungroup_id: rungroupId,
       env,
@@ -100,7 +99,6 @@ export const payloadMethods = {
       test_ids: testIds,
       suite_ids: suiteIds,
       envs,
-      configuration,
       link,
     };
   },
@@ -108,7 +106,6 @@ export const payloadMethods = {
   buildRunUpdatePayload({
     title,
     description,
-    plan_id: planId,
     kind,
     rungroup_id: rungroupId,
     env,
@@ -117,13 +114,11 @@ export const payloadMethods = {
     assign_strategy: assignStrategy,
     test_ids: testIds,
     suite_ids: suiteIds,
-    configuration,
     link,
   } = {}) {
     return {
       title,
       description,
-      plan_id: planId,
       kind,
       rungroup_id: rungroupId,
       env,
@@ -132,7 +127,6 @@ export const payloadMethods = {
       assign_strategy: assignStrategy,
       test_ids: testIds,
       suite_ids: suiteIds,
-      configuration,
       link,
     };
   },