# Testomat.io MCP Server

A Model Context Protocol (MCP) server for Testomat.io API integration with AI assistants like Cursor.

## Installation

### Prerequisites

- Node.js 18 or higher (with built-in fetch support)
- npm or yarn package manager
- Testomat.io account with API access

### Run directly with npx

```bash
npx @testomatio/mcp --token <your-token> --project <project-id>
```

## Usage

### Command Line Options

The MCP server can be started using command line arguments or environment variables:

#### Using Command Line Arguments

```bash
# Using short flags
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

# With custom base URL
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id --base-url https://your-instance.testomat.io
```

#### Using Environment Variables

```bash
# Set environment variables
export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE
export TESTOMATIO_BASE_URL=https://app.testomat.io  # Optional, defaults to https://app.testomat.io

# Run with project ID
npx @testomatio/mcp --project your-project-id

# Or run directly with environment variables
TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE npx @testomatio/mcp --project your-project-id
```

### Getting Your API Token

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_`)

### Getting Your Project ID

Your project ID can be found in the URL when you're viewing your project:
```
https://app.testomat.io/projects/YOUR_PROJECT_ID
```

## Integration with Cursor

To use this MCP server with Cursor, add the following configuration to your Cursor settings:

### Option 1: Using npx (Recommended)

Add this to your Cursor MCP settings (`cursor-settings.json` or through the Cursor settings UI):

```json
{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": ["-y", "@testomatio/mcp@latest", "--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
    }
  }
}
```

### Option 2: Using Environment Variables

First, set your environment variables in your shell profile (`.bashrc`, `.zshrc`, etc.):

```bash
export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE
```

Then add this to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": ["-y", "@testomatio/mcp@latest", "--project", "YOUR_PROJECT_ID"],
      "env": {
        "TESTOMATIO_API_TOKEN": "testomat_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

## Features

### Tools

#### 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`

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

Once configured, you can ask your AI assistant questions like:

- "Show me all the tests in the project"
- "Get the test runs for test ID abc123"
- "What are the root suites in this project?"
- "Show me details for test run xyz789"
- "List all automated tests with the @smoke tag"
- "Get all test plans for this project"

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

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

### Common Issues

1. **"API token is required" error**
   - Make sure your token starts with `testomat_`
   - 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
   - Verify the project ID exists and you have access to it

3. **Connection errors**
   - Ensure you have internet connectivity
   - Check if your firewall allows connections to `app.testomat.io`
   - Verify your API token has the necessary permissions

4. **MCP server not starting in Cursor**
   - Check Cursor's MCP logs for error messages
   - Ensure Node.js 18+ is installed and accessible
   - Try running the command manually first to test

### Debug Mode

To see detailed logs when running the server:

```bash
DEBUG=* npx @testomatio/mcp --token <token> --project <project-id>
```

## API Reference

For detailed information about the underlying Testomat.io API, refer to the [Testomat.io API Documentation](https://app.testomat.io/docs/api/).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For support, please:
1. Check the [Testomat.io Documentation](https://docs.testomat.io)
2. Open an issue on GitHub
3. Contact Testomat.io support

## Changelog

### v1.0.0
- Initial release
- Support for all major Testomat.io API endpoints
- MCP-compatible tool interface
- Semantic XML formatting for LLM processing