yailenpozo/mcp-testrail-qa-server

🚀 MCP TestRail Server - Production Ready

📋 Descripción

Servidor MCP (Model Context Protocol) que conecta GitHub Copilot con TestRail para gestión automatizada de casos de prueba desde VS Code.

✨ Características

• 13+ herramientas TestRail (create_case, search_cases, get_projects, etc.)
• Servidor HTTP para equipos remotos (puerto 3000)
• Servidor MCP stdio para VS Code local
• Integración GitHub Copilot - comandos en lenguaje natural
• Validación completa de campos obligatorios TestRail
• Soporte campos personalizados (custom_automation_status, etc.)

🚀 Quick Start

1. Clonar e Instalar

git clone https://github.com/tu-usuario/mcp-testrail-advanced.git
cd mcp-testrail-advanced
npm install

2. Configurar Variables de Entorno

# Copiar template de configuración
cp .env.example .env

# Editar .env con tus credenciales TestRail
# BASE_URL=https://tu-empresa.testrail.io
# USER=tu-email@empresa.com  
# KEY=tu-api-key-testrail

3. Compilar y Ejecutar

# Compilar TypeScript
npm run build

# Ejecutar servidor HTTP (para equipos remotos)
npm run dev:http  # Puerto 3000

# O ejecutar servidor MCP stdio (para uso local)
npm run dev:mcp

🛠️ Variables de Entorno Requeridas

Crear archivo .env basado en .env.example:

BASE_URL=https://tu-empresa.testrail.io
USER=tu-email@empresa.com
KEY=tu-api-key-testrail
TIMEOUT=20000
PORT=3000

🔑 Obtener API Key de TestRail:

1. TestRail → Usuario → Settings → API Keys
2. Generar nueva API Key
3. Copiar y pegar en .env

📦 Para QAs (Usuarios Remotos)

1. Obtener Cliente

# Solo necesitan la carpeta del cliente
cp -r mcp-qa-client/ /ruta/destino/

2. Configurar Cliente

// En mcp-qa-client/client/mcp-client.js
const SERVER_URL = 'http://IP_SERVIDOR:3000';  // 🔧 CAMBIAR IP

3. Configurar VS Code MCP Global

Agregar en %APPDATA%\Code\User\mcp.json:

{
  "servers": {
    "testrail": {
      "command": "node",
      "args": ["RUTA_COMPLETA\\mcp-qa-client\\client\\mcp-client.js"],
      "type": "stdio"
    }
  }
}

💬 Ejemplos de Uso con GitHub Copilot

@testrail get_projects
@testrail create_case title="Test Login" sectionId=123
@testrail search_cases projectId=2 query="authentication"
@testrail get_case_fields
@testrail add_result runId=456 caseId=789 statusId=1

📊 Herramientas Disponibles

🔍 Consulta

• get_projects - Listar proyectos
• get_suites - Listar suites
• get_sections - Listar secciones
• get_milestones - Listar milestones
• get_users - Listar usuarios
• get_case_fields - Metadata de campos

📝 Gestión de Casos

• create_case - Crear caso de prueba
• update_case - Actualizar caso
• search_cases - Buscar casos

🏃‍♂️ Ejecución

• create_run - Crear ejecución
• add_result - Agregar resultado
• get_results - Obtener resultados

📁 Estructura del Proyecto

mcp-testrail-advanced/
├── src/                     # 🔧 Servidor (TypeScript)
│   ├── server.ts           # Servidor MCP stdio
│   ├── http-server.ts      # Servidor HTTP + endpoints
│   ├── testrail.ts         # Cliente API TestRail
│   └── mcp-bridge.js       # Bridge stdio-to-HTTP
├── mcp-qa-client/          # 📦 Cliente para QAs
│   ├── client/
│   │   ├── mcp-client.js   # Cliente MCP principal
│   │   └── CLIENT-INDEX.md # Guía de uso
│   └── package.json        # Dependencias cliente
├── .env.example            # 🔐 Template configuración
├── .gitignore              # 🚫 Archivos excluidos de Git
├── README.md               # 📚 Esta documentación
├── DEPLOYMENT_GUIDE.md     # 🚀 Guía de despliegue
├── EJEMPLOS_USO.md         # 🎯 Ejemplos prácticos
├── package.json            # 📦 Configuración proyecto
└── tsconfig.json           # 🔧 Configuración TypeScript

🔧 Scripts Disponibles

npm run build          # Compilar TypeScript
npm run dev:http        # Servidor HTTP (puerto 3000)
npm run dev:mcp         # Servidor MCP stdio
npm run start           # Producción
npm run clean           # Limpiar archivos compilados

🔧 Troubleshooting

Servidor HTTP

• Puerto 3000 ocupado: Cambiar PORT en .env
• Error de conexión TestRail: Verificar credenciales en .env
• Timeout: Ajustar TIMEOUT en .env

Cliente MCP

• "Unknown tool": Verificar configuración mcp.json
• "Connection failed": Verificar IP del servidor
• MCP no aparece: Reiniciar VS Code tras cambios

📖 Documentación Adicional

• - Instalación y configuración detallada
• - Casos de uso prácticos
• - Guía para QAs

🤝 Contribuir

1. Fork el proyecto
2. Crear rama feature (git checkout -b feature/AmazingFeature)
3. Commit cambios (git commit -m 'Add AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abrir Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver para detalles.

🚀 ¡Tu servidor MCP TestRail está listo para producción!