npm package: @harpal-dev/x-mcp
Description: MCP server for Product-X Test Management System - Manage test cases, modules, components, and subcomponents via Cursor and VS Code
Author: Product-X
Latest version: 1.0.0

# X-MCP: Product-X Test Management MCP Server

X-MCP is a Model Context Protocol (MCP) server that provides comprehensive test case management capabilities for the Product-X Test Management System. It allows you to manage test cases, modules, components, and subcomponents directly from Cursor, VS Code, or any MCP-compatible client.

## Features

- **Module Management**: Create, update, delete, and list modules, components, and subcomponents
- **Test Case Management**: Full CRUD operations for test cases
- **Test Case Operations**: Clone, move, and bulk create test cases
- **Export/Import**: Export test cases to Excel and import from Excel files
- **Permission-Aware**: Respects the same permissions as the web application
- **Session-Based Auth**: Works with your existing application session

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- Access to a Product-X Test Management System instance
- Valid user credentials for the system

### Quick Install (Recommended)

**Option 1: Using npx (No installation required)**

Simply use `npx` in your MCP configuration - it will download and run the package automatically:

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@product-x/x-mcp"],
      "env": {
        "X_MCP_API_URL": "https://qa-path.com/api",
        "X_MCP_PROJECT_ID": "your-project-id",
        "X_MCP_EMAIL": "your-email@example.com",
        "X_MCP_PASSWORD": "your-password"
      }
    }
  }
}
```

**Option 2: Global Installation**

```bash
npm install -g @product-x/x-mcp
```

Then use in your MCP configuration:
```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "x-mcp",
      "env": {
        "X_MCP_API_URL": "https://qa-path.com/api",
        "X_MCP_PROJECT_ID": "your-project-id",
        "X_MCP_EMAIL": "your-email@example.com",
        "X_MCP_PASSWORD": "your-password"
      }
    }
  }
}
```

**Option 3: Local Installation**

```bash
npm install @product-x/x-mcp
```

Then use the full path:
```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": ["./node_modules/@product-x/x-mcp/dist/index.js"],
      "env": {
        "X_MCP_API_URL": "https://qa-path.com/api",
        "X_MCP_PROJECT_ID": "your-project-id",
        "X_MCP_EMAIL": "your-email@example.com",
        "X_MCP_PASSWORD": "your-password"
      }
    }
  }
}
```

### Install from Source (Development)

```bash
git clone <repository-url>
cd x-mcp
npm install
npm run build
```

## Configuration

X-MCP requires configuration via environment variables or a `.env` file.

### Required Configuration

```bash
# API Base URL (required)
X_MCP_API_URL=http://localhost:3000/api

# Project ID (required for most operations)
X_MCP_PROJECT_ID=your-project-id-here
```

### Authentication Options

You can authenticate using one of the following methods:

#### Option 1: Username/Password Login (Recommended)

Login directly with your email and password. The MCP server will create its own session:

```bash
X_MCP_EMAIL=your-email@example.com
X_MCP_PASSWORD=your-password
```

**Note:** The MCP server will automatically log in when it starts if these credentials are provided.

#### Option 2: Session Token

If you're already logged into the web application, you can extract your session token from the browser cookies:

```bash
X_MCP_SESSION_TOKEN=your-session-token-here
```

To get your session token:
1. Log into the web application
2. Open browser DevTools (F12)
3. Go to Application/Storage > Cookies
4. Copy the `token` cookie value

#### Option 3: API Key (if supported)

```bash
X_MCP_API_KEY=your-api-key-here
```

### Complete Example `.env` file

```bash
# API Configuration
X_MCP_API_URL=http://localhost:3000/api
X_MCP_PROJECT_ID=123e4567-e89b-12d3-a456-426614174000

# Authentication (choose one)
# Option 1: Username/Password (Recommended)
X_MCP_EMAIL=your-email@example.com
X_MCP_PASSWORD=your-password

# Option 2: Session Token
# X_MCP_SESSION_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Option 3: API Key
# X_MCP_API_KEY=your-api-key-here
```

## Usage with Cursor

1. Open Cursor settings
2. Navigate to MCP settings
3. Add the following configuration:

```json
{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@product-x/x-mcp"],
      "env": {
        "X_MCP_API_URL": "http://localhost:3000/api",
        "X_MCP_PROJECT_ID": "your-project-id",
        "X_MCP_SESSION_TOKEN": "your-session-token"
      }
    }
  }
}
```

## Usage with VS Code

1. Install the MCP extension for VS Code
2. Configure the MCP server in your VS Code settings:

```json
{
  "mcp.servers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@product-x/x-mcp"],
      "env": {
        "X_MCP_API_URL": "http://localhost:3000/api",
        "X_MCP_PROJECT_ID": "your-project-id",
        "X_MCP_EMAIL": "your-email@example.com",
        "X_MCP_PASSWORD": "your-password"
      }
    }
  }
}
```

## Available Tools

### Authentication Tools

- `login` - Login to the system using email and password. Creates a session for all subsequent requests.
- `check_auth_status` - Check if the MCP server is currently authenticated.

### Module Tools

- `list_modules` - List all modules, components, and subcomponents
- `create_module` - Create a new module, component, or subcomponent
- `update_module` - Update an existing module
- `delete_module` - Delete a module and all its children
- `get_module` - Get detailed information about a module

### Test Case Tools

- `list_test_cases` - List test cases with optional filtering
- `get_test_case` - Get detailed information about a test case
- `create_test_case` - Create a new test case
- `update_test_case` - Update an existing test case
- `delete_test_case` - Delete a test case
- `clone_test_case` - Clone one or more test cases
- `move_test_case` - Move a test case to a different module
- `bulk_create_test_cases` - Create multiple test cases at once

### Export/Import Tools

- `get_export_structure` - Get the module structure and test case fields needed for export/import

## Examples

### Create a Module

```json
{
  "name": "create_module",
  "arguments": {
    "name": "Authentication Module",
    "context": "Module for authentication-related test cases"
  }
}
```

### Create a Test Case

```json
{
  "name": "create_test_case",
  "arguments": {
    "title": "Verify user login with valid credentials",
    "description": "Test that a user can log in with valid email and password",
    "moduleId": "module-id-here",
    "type": "Functional Test",
    "status": "New",
    "priority": "High",
    "estimatedDuration": 15
  }
}
```

### Clone Test Cases

```json
{
  "name": "clone_test_case",
  "arguments": {
    "testCaseIds": ["test-case-id-1", "test-case-id-2"],
    "targetModuleId": "target-module-id"
  }
}
```

### Export Test Cases

```json
{
  "name": "export_test_cases",
  "arguments": {
    "outputPath": "/path/to/export.xlsx",
    "moduleId": "module-id-here"
  }
}
```

## Permissions

X-MCP respects the same permission system as the web application. Users can only perform actions they have permission for. If you receive a 403 Forbidden error, check your user permissions in the web application.

## Troubleshooting

### Authentication Errors

- **401 Unauthorized**: Check your `X_MCP_SESSION_TOKEN` or `X_MCP_API_KEY`
- **403 Forbidden**: You don't have permission for this action. Check your user role and permissions.

### Connection Errors

- **Network error**: Verify that `X_MCP_API_URL` is correct and the server is accessible
- **Timeout**: The server might be slow. Try increasing the timeout in the API client.

### Project ID Errors

- Make sure `X_MCP_PROJECT_ID` is set correctly
- You can also provide `projectId` as an argument to individual tool calls

## Development

### Building from Source

```bash
npm install
npm run build
```

### Running in Development Mode

```bash
npm run dev
```

### Testing

```bash
npm test
```

## License

MIT

## Support

For issues and questions, please contact the Product-X team or open an issue in the repository.