@testomatio/mcp 1.0.1 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
-# Testomatio MCP Server
+# Testomat.io MCP Server
 
-A Model Context Protocol (MCP) server for Testomatio API integration with AI assistants like Cursor.
+A Model Context Protocol (MCP) server for Testomat.io API integration with AI assistants like Cursor.
 
 ## Installation
 
@@ -8,15 +8,9 @@ A Model Context Protocol (MCP) server for Testomatio API integration with AI ass
 
 - Node.js 18 or higher (with built-in fetch support)
 - npm or yarn package manager
-- Testomatio account with API access
+- Testomat.io account with API access
 
-### Install via npm
-
-```bash
-npm install -g @testomatio/mcp
-```
-
-### Or run directly with npx
+### Run directly with npx
 
 ```bash
 npx @testomatio/mcp --token <your-token> --project <project-id>
@@ -37,9 +31,6 @@ npx @testomatio/mcp -t testomat_YOUR_TOKEN_HERE -p your-project-id
 # Using long flags
 npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id
 
-# If installed globally
-testomatio-mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id
-
 # With custom base URL
 npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id --base-url https://your-instance.testomat.io
 ```
@@ -60,7 +51,7 @@ TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE npx @testomatio/mcp --project your
 
 ### Getting Your API Token
 
-1. Go to [Testomatio](https://app.testomat.io)
+1. Go to [Testomat.io](https://app.testomat.io)
 2. Navigate to user tokens https://app.testomat.io/account/access_tokens
 3. Create and copy **General API token** (starts with `testomat_`)
 
@@ -84,7 +75,7 @@ Add this to your Cursor MCP settings (`cursor-settings.json` or through the Curs
   "mcpServers": {
     "testomatio": {
       "command": "npx",
-      "args": ["@testomatio/mcp", "--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
+      "args": ["-y", "@testomatio/mcp@latest", "--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
     }
   }
 }
@@ -105,7 +96,7 @@ Then add this to your Cursor MCP settings:
   "mcpServers": {
     "testomatio": {
       "command": "npx",
-      "args": ["@testomatio/mcp", "--project", "YOUR_PROJECT_ID"],
+      "args": ["-y", "@testomatio/mcp@latest", "--project", "YOUR_PROJECT_ID"],
       "env": {
         "TESTOMATIO_API_TOKEN": "testomat_YOUR_TOKEN_HERE"
       }
@@ -114,20 +105,29 @@ Then add this to your Cursor MCP settings:
 }
 ```
 
-### Option 3: Global Installation
+## Features
 
-If you've installed the package globally:
+### Tools
 
-```json
-{
-  "mcpServers": {
-    "testomatio": {
-      "command": "testomatio-mcp",
-      "args": ["--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
-    }
-  }
-}
-```
+#### Tests
+* `get_tests` – Get all tests (params: `plan`, `query`, `state`, `suite_id`, `tag`, `labels`) — api: GET `/tests`
+* `search_tests` – Search tests (params: `query`, `tql`, `labels`, `state`, `priority`, `filter`, `page`) — api: GET `/tests`
+* `create_test` – Create a new test (params: `suite_id`, `title`, `description`, `code`, `file`, `state`, `tags`, `jira_issues`, `assigned_to`, `labels_ids`) — api: POST `/tests`
+* `update_test` – Update an existing test (params: `test_id`, `suite_id`, `title`, `description`, `code`, `file`, `state`, `tags`, `jira_issues`, `assigned_to`, `labels_ids`) — api: PUT `/tests/{test_id}`
+
+#### Test Suites
+* `search_suites` – Search suites (params: `query`, `labels`, `state`, `priority`, `page`) — api: GET `/suites`
+* `get_root_suites` – List root-level suites (no params) — api: GET `/suites`
+* `get_suite` – Get one suite (params: `suite_id`) — api: GET `/suites/{suite_id}`
+
+#### Test Runs
+* `get_runs` – List all runs (no params) — api: GET `/runs`
+* `get_run` – Get one run (params: `run_id`, `tree`) — api: GET `/runs/{run_id}`
+* `get_testruns` – Runs for a test (params: `test_id`, `finished_at_date_range`) — api: GET `/testruns`
+
+#### Test Plans
+* `get_plans` – List all plans (params: `detail`, `labels`, `page`) — api: GET `/plans`
+* `get_plan` – Get one plan (params: `plan_id`) — api: GET `/plans/{plan_id}`
 
 ## Example Usage in Cursor
 
@@ -139,6 +139,75 @@ Once configured, you can ask your AI assistant questions like:
 - "Show me details for test run xyz789"
 - "List all automated tests with the @smoke tag"
 - "Get all test plans for this project"
+- "Create a new test called 'Login validation' in suite suite-123"
+- "Update test test-456 to change its description and add @regression tag"
+
+## Query Patterns
+
+### Basic Information Queries
+
+These queries retrieve general information without specific filtering:
+
+- **"Show me all the tests in the project"** → `get_tests` tool
+- **"What are the root suites in this project?"** → `get_root_suites` tool  
+- **"Get all test runs"** → `get_runs` tool
+- **"Get all test plans for this project"** → `get_plans` tool
+
+### Test Management Queries
+
+These queries allow creating and updating tests:
+
+- **"Create a new test called 'Login validation' in suite suite-123"** → `create_test` tool with `title: "Login validation"`, `suite_id: "suite-123"`
+- **"Update test test-456 to change its description"** → `update_test` tool with `test_id: "test-456"`, `description: "new description"`
+- **"Create an automated test with @smoke tag"** → `create_test` tool with `state: "automated"`, `tags: ["smoke"]`
+
+### Specific Item Queries
+
+These queries target specific entities by ID:
+
+- **"Get test runs for test ID abc123"** → `get_testruns` tool with `test_id: "abc123"`
+- **"Show me details for test run xyz789"** → `get_run` tool with `run_id: "xyz789"`
+- **"Get suite details for suite-456"** → `get_suite` tool with `suite_id: "suite-456"`
+
+### Search and Filter Queries
+
+These queries use advanced filtering capabilities:
+
+- **"List all automated tests with the @smoke tag"** → `search_tests` tool with `query: "@smoke"`, `state: "automated"`
+- **"Find tests with priority high"** → `search_tests` tool with `priority: "high"`
+- **"Search for tests containing 'login'"** → `search_tests` tool with `query: "login"`
+- **"List tests tagged @critical or labelled 'ux' with high priority"** → `search_tests` tool with `tql: "tag == 'critical' or label == 'ux' and priority == 'high'"`
+- **"Find tests linked to JIRA-123"** → `search_tests` tool with `tql: jira == 'BDCP-2'`
+
+### Advanced Query Syntax
+
+#### Test Query Language (TQL)
+
+The `search_tests` tool supports TQL for complex filtering:
+
+```
+"tag == 'smoke' and state == 'manual'"
+"priority == 'high' or label == 'ux'"
+```
+
+#### Tag-Based Searches
+
+Tags can be searched using the `@` prefix:
+
+```
+@smoke        # Tests tagged with 'smoke'
+@regression   # Tests tagged with 'regression'
+@critical     # Tests tagged with 'critical'
+```
+
+#### Jira Integration
+
+Tests linked to Jira issues can be found using issue keys:
+
+```
+JIRA-123      # Tests linked to JIRA-123
+PROJ-456      # Tests linked to PROJ-456
+```
 
 ## Troubleshooting
 
@@ -146,7 +215,7 @@ Once configured, you can ask your AI assistant questions like:
 
 1. **"API token is required" error**
    - Make sure your token starts with `testomat_`
-   - Verify the token is correct in your Testomatio project settings
+   - Verify the token is correct in your Testomat.io project settings
 
 2. **"Project ID is required" error**
    - Check that you're passing the correct project ID
@@ -172,7 +241,7 @@ DEBUG=* npx @testomatio/mcp --token <token> --project <project-id>
 
 ## API Reference
 
-For detailed information about the underlying Testomatio API, refer to the [Testomatio API Documentation](https://app.testomat.io/docs/api/).
+For detailed information about the underlying Testomat.io API, refer to the [Testomat.io API Documentation](https://app.testomat.io/docs/api/).
 
 ## Contributing
 
@@ -185,14 +254,14 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 ## Support
 
 For support, please:
-1. Check the [Testomatio Documentation](https://docs.testomat.io)
+1. Check the [Testomat.io Documentation](https://docs.testomat.io)
 2. Open an issue on GitHub
-3. Contact Testomatio support
+3. Contact Testomat.io support
 
 ## Changelog
 
 ### v1.0.0
 - Initial release
-- Support for all major Testomatio API endpoints
+- Support for all major Testomat.io API endpoints
 - MCP-compatible tool interface
 - Semantic XML formatting for LLM processing

package/index.js

@@ -269,6 +269,118 @@ class TestomatioMCPServer {
               required: ['plan_id'],
             },
           },
+          {
+            name: 'create_test',
+            description: 'Create a new test in the specified suite',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                suite_id: {
+                  type: 'string',
+                  description: 'Suite ID where the test will be created',
+                },
+                title: {
+                  type: 'string',
+                  description: 'Test title',
+                },
+                description: {
+                  type: 'string',
+                  description: 'Test description',
+                },
+                code: {
+                  type: 'string',
+                  description: 'Source code of an automated test',
+                },
+                file: {
+                  type: 'string',
+                  description: 'File of an automated test',
+                },
+                state: {
+                  type: 'string',
+                  enum: ['manual', 'automated'],
+                  description: 'State of the test',
+                },
+                tags: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'List of tags for the test',
+                },
+                jira_issues: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'List of assigned Jira issues',
+                },
+                assigned_to: {
+                  type: 'string',
+                  description: 'User assigned to this test',
+                },
+                labels_ids: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Slugs of labels to assign to the test',
+                },
+              },
+              required: ['suite_id', 'title'],
+            },
+          },
+          {
+            name: 'update_test',
+            description: 'Update an existing test',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                test_id: {
+                  type: 'string',
+                  description: 'ID of the test to update',
+                },
+                suite_id: {
+                  type: 'string',
+                  description: 'Suite ID where the test belongs',
+                },
+                title: {
+                  type: 'string',
+                  description: 'Test title',
+                },
+                description: {
+                  type: 'string',
+                  description: 'Test description',
+                },
+                code: {
+                  type: 'string',
+                  description: 'Source code of an automated test',
+                },
+                file: {
+                  type: 'string',
+                  description: 'File of an automated test',
+                },
+                state: {
+                  type: 'string',
+                  enum: ['manual', 'automated'],
+                  description: 'State of the test',
+                },
+                tags: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'List of tags for the test',
+                },
+                jira_issues: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'List of assigned Jira issues',
+                },
+                assigned_to: {
+                  type: 'string',
+                  description: 'User assigned to this test',
+                },
+                labels_ids: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Slugs of labels to assign to the test',
+                },
+              },
+              required: ['test_id'],
+            },
+          },
         ],
       };
     });
@@ -298,6 +410,10 @@ class TestomatioMCPServer {
             return await this.getPlans(args);
           case 'get_plan':
             return await this.getPlan(args.plan_id);
+          case 'create_test':
+            return await this.createTest(args);
+          case 'update_test':
+            return await this.updateTest(args);
           default:
             throw new Error(`Unknown tool: ${name}`);
         }
@@ -352,6 +468,55 @@ class TestomatioMCPServer {
     return await response.json();
   }
 
+  async makePostRequest(path, data) {
+    const jwt = await this.authenticate();
+    const url = `${this.config.baseUrl}/api/${this.config.projectId}${path}`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': jwt,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      if (response.status === 401 && this.jwtToken) {
+        this.jwtToken = null;
+        return this.makePostRequest(path, data);
+      }
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.json();
+  }
+
+  async makePutRequest(path, data) {
+    const jwt = await this.authenticate();
+    const url = `${this.config.baseUrl}/api/${this.config.projectId}${path}`;
+
+    const response = await fetch(url, {
+      method: 'PUT',
+      headers: {
+        'Authorization': jwt,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      if (response.status === 401 && this.jwtToken) {
+        this.jwtToken = null;
+        return this.makePutRequest(path, data);
+      }
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return await response.json();
+  }
+
+
   escapeXml(text) {
     if (typeof text !== 'string') return text;
     return text
@@ -748,6 +913,54 @@ class TestomatioMCPServer {
     };
   }
 
+  async createTest(args) {
+    const { test_id, labels_ids, ...attributes } = args;
+    const requestData = {
+      type: 'test',
+      attributes: Object.fromEntries(Object.entries(attributes).map(([k, v]) => [k.replace(/_/g, '-'), v])),
+    };
+    if (labels_ids) requestData.labels_ids = labels_ids;
+
+    const data = await this.makePostRequest('/tests', requestData);
+    const formattedTest = this.formatModel(data.data, 'test', [
+      'title', 'description', 'code', 'priority', 
+      'state', 'suite-id', 'tags', 'file'
+    ]);
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Successfully created test:\n\n${formattedTest}`,
+        },
+      ],
+    };
+  }
+
+  async updateTest(args) {
+    const { test_id, labels_ids, ...attributes } = args;
+    const requestData = {
+      type: 'test',
+      attributes: Object.fromEntries(Object.entries(attributes).map(([k, v]) => [k.replace(/_/g, '-'), v])),
+    };
+    if (labels_ids) requestData.labels_ids = labels_ids;
+
+    const data = await this.makePutRequest(`/tests/${args.test_id}`, requestData);
+    const formattedTest = this.formatModel(data.data, 'test', [
+      'title', 'description', 'code', 'priority', 
+      'state', 'suite-id', 'tags', 'file'
+    ]);
+    
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Successfully updated test:\n\n${formattedTest}`,
+        },
+      ],
+    };
+  }
+
   async run() {
     // Test authentication on startup
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testomatio/mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Model Context Protocol server for Testomatio API",
   "main": "index.js",
   "bin": {
@@ -33,4 +33,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}