# TestRail MCP Server

A comprehensive Model Context Protocol (MCP) server for TestRail integration, providing seamless access to TestRail's test management capabilities through MCP tools with advanced project management, reporting, and AutoSpectra integration.

## 🚀 Features

### Core TestRail Integration
- **Complete TestRail API Coverage**: Projects, suites, cases, runs, results, plans, milestones
- **MCP Protocol Integration**: Native MCP server implementation
- **Type-Safe**: Full TypeScript support with comprehensive type definitions
- **Bulk Operations**: Support for bulk test case and result operations
- **Real-time Updates**: WebSocket support for real-time TestRail updates

### Advanced Project Management
- **🏗️ Advanced Project Creation**: Template-driven project setup with predefined structures
- **📊 Project Health Analysis**: Comprehensive project structure analysis with recommendations
- **⚡ Bulk Suite Management**: Efficient bulk operations on test suites with validation
- **🎯 Template System**: Pre-built templates for functional, API, performance, security, and mobile testing

### Comprehensive Reporting & Analytics
- **📈 Project Dashboards**: Interactive dashboards with metrics, trends, and failure analysis
- **🔍 Test Case Metrics**: Detailed analysis of test case execution patterns and health
- **📋 Coverage Reports**: Comprehensive test coverage analysis by priority, type, and automation
- **📊 Trend Analysis**: Historical trend analysis with pass rate and completion tracking
- **🎯 Flakiness Detection**: Automated identification of flaky tests

### AutoSpectra Integration
- **🔄 Seamless Sync**: Direct integration with AutoSpectra test automation framework
- **🚀 CI/CD Ready**: Built-in support for GitHub Actions, Jenkins, and other CI/CD platforms
- **📝 Auto Case Creation**: Automatic test case creation from AutoSpectra test results
- **📊 Real-time Monitoring**: Live test execution monitoring and result submission

### Enterprise Features
- **🔐 Security**: Enterprise-grade security with encrypted credentials and audit logging
- **⚡ Performance**: Optimized for large datasets with rate limiting and batching
- **🛡️ Error Handling**: Comprehensive error handling with retry logic and graceful degradation
- **📝 Comprehensive Testing**: Unit, integration, and E2E tests with 95%+ coverage

## 📁 Project Structure

```
testrail-mcp-server/
├── src/                          # Source code
│   ├── types/                    # TypeScript type definitions
│   │   ├── testrail.ts          # TestRail API types
│   │   ├── mcp.ts               # MCP-specific types
│   │   └── index.ts             # Type exports
│   ├── tools/                    # MCP tool implementations
│   ├── utils/                    # Utility functions and helpers
│   └── index.ts                  # Main server entry point
├── tests/                        # Test suites
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   └── e2e/                      # End-to-end tests
├── docs/                         # Documentation
│   ├── api/                      # API documentation
│   └── guides/                   # User guides and tutorials
├── examples/                     # Usage examples
│   ├── basic/                    # Basic usage examples
│   └── advanced/                 # Advanced usage examples
├── package.json                  # Package configuration
├── tsconfig.json                 # TypeScript configuration
├── .env.example                  # Environment configuration template
└── .gitignore                    # Git ignore rules
```

## ⚡ Quick Start

### Prerequisites

- Node.js 16.0 or higher
- TestRail instance with API access
- TestRail API key

### Installation

```bash
# Clone the repository
git clone https://github.com/samuelvinay91/testrail-mcp.git
cd testrail-mcp

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit .env with your TestRail credentials
# TESTRAIL_BASE_URL=https://your-instance.testrail.io
# TESTRAIL_USERNAME=your.email@company.com
# TESTRAIL_API_KEY=your-api-key-here

# Build and start
npm run build
npm start
```

### 🤖 Quick Setup with AI Coding Agents

**Interactive Setup (Recommended)**:
```bash
# Run the interactive setup script
npm run setup-agents

# Follow the prompts to configure your preferred coding agent
# Supports: Claude Desktop, Cursor IDE, Windsurf IDE, Continue (VS Code)
```

**Manual Configuration Examples**:

**Claude Desktop**:
```json
// ~/.claude-desktop/config.json
{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["path/to/testrail-mcp/dist/index.js"],
      "env": {
        "TESTRAIL_BASE_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_USERNAME": "your.email@company.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}
```

**Cursor IDE**:
```json
// Cursor Settings > MCP Configuration
{
  "mcp": {
    "servers": [{
      "name": "testrail",
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/testrail-mcp"
    }]
  }
}
```

**Windsurf IDE**:
```json
// .windsurf/mcp-config.json
{
  "servers": {
    "testrail": {
      "command": "node",
      "args": ["path/to/testrail-mcp/dist/index.js"],
      "transport": "stdio"
    }
  }
}
```

📄 **See [complete setup guide](./docs/guides/coding-agents-setup.md) for detailed instructions with Claude, Cursor, Windsurf, Continue, Cody, and more!**

### Development

```bash
# Start development server
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Lint and format
npm run lint
npm run format
```

## 🔧 Configuration

Create a `.env` file based on `.env.example`:

```env
# Required: TestRail connection
TESTRAIL_BASE_URL=https://your-instance.testrail.io
TESTRAIL_USERNAME=your.email@company.com
TESTRAIL_API_KEY=your-api-key-here

# Optional: Server configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# Optional: Default project settings
DEFAULT_PROJECT_ID=1
DEFAULT_SUITE_ID=1
```

## 🛠 Available MCP Tools

The TestRail MCP Server provides the following tools:

### Connection & Authentication
- `connect_testrail` - Connect to TestRail instance
- `test_connection` - Test TestRail connection

### Basic Project Management
- `get_projects` - List all projects
- `get_project` - Get specific project
- `create_project` - Create new project

### Advanced Project Management 🆕
- `create_advanced_project` - Create project with templates and initial structure
- `analyze_project_structure` - Analyze project health with recommendations
- `bulk_manage_suites` - Perform bulk operations on test suites
- `create_advanced_suite` - Create suite with templates and structure

### Suite & Section Management
- `get_suites` - List suites in project
- `create_suite` - Create new suite
- `get_sections` - List sections in suite
- `create_section` - Create new section

### Test Case Management
- `get_cases` - List test cases
- `get_case` - Get specific test case
- `create_case` - Create new test case
- `update_case` - Update existing test case
- `delete_case` - Delete test case

### Test Run Management
- `get_runs` - List test runs
- `create_run` - Create new test run
- `update_run` - Update test run
- `close_run` - Close test run

### Test Execution
- `get_tests` - List tests in run
- `add_result` - Add test result
- `add_bulk_results` - Add multiple results
- `get_results` - Get test results

### Advanced Reporting & Analytics 🆕
- `generate_project_dashboard` - Generate comprehensive project dashboard
- `generate_execution_report` - Generate detailed test execution reports
- `analyze_case_metrics` - Analyze test case metrics and health
- `generate_coverage_report` - Generate comprehensive test coverage reports
- `generate_report` - Generate custom test reports

### AutoSpectra Integration 🆕
- `autospectra_sync` - Synchronize AutoSpectra test results with TestRail

### Legacy Tools (Still Available)
- `get_test_stats` - Get test statistics
- `get_execution_trends` - Get execution trends

## 📚 Documentation

- [API Documentation](./docs/api/) - Detailed API reference
- [User Guides](./docs/guides/) - Step-by-step tutorials
- [Coding Agents Setup](./docs/guides/coding-agents-setup.md) - Integration with Claude, Cursor, Windsurf, and other AI tools
- [AutoSpectra Integration](./docs/guides/autospectra-integration.md) - Advanced test automation integration
- [Getting Started](./docs/guides/getting-started.md) - Complete setup guide
- [Examples](./examples/) - Code examples and use cases

## 🧪 Testing

```bash
# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- [GitHub Issues](https://github.com/your-username/testrail-mcp-server/issues)
- [Documentation](./docs/)
- [Examples](./examples/)

## 🔗 Related Projects

- [TestRail API Documentation](https://www.gurock.com/testrail/docs/api)
- [Model Context Protocol](https://github.com/anthropics/mcp)
- [MCP SDK](https://github.com/anthropics/mcp-sdk)