OneTest MCP Server

A Model Context Protocol (MCP) server for the OneTest AI-driven testing platform, integrating Blazemeter and Perfecto services.

Overview

This MCP server provides tools and resources to interact with the OneTest backend API, enabling AI assistants to create test scenarios, execute test suites, manage applications and environments, generate policy rules, and more.

Installation

Global Installation (Recommended)

yarn global add @okep/onetest-mcp-server

Yarn Usage (One-time execution)

# For Yarn 2+ (Berry)
yarn dlx @okep/onetest-mcp-server --url http://localhost:3000/api/v1

# For Yarn 1.x - use npx or install globally
npx @okep/onetest-mcp-server --url http://localhost:3000/api/v1

NPX Usage (Alternative)

npx @okep/onetest-mcp-server --url http://localhost:3000/api/v1

Local Development (from source)

# Clone and build the project
cd tools/onetest-mcp-server
yarn install
yarn build

# Run using yarn start
yarn start --url http://localhost:3000/api/v1 --one-test-token YOUR_TOKEN_HERE

Local Installation

yarn add @okep/onetest-mcp-server

Usage

Command Line

onetest-mcp-server --url <ONETEST_API_URL> [options]

Options

• --url, -u <url>: OneTest backend API URL (required)
• --one-test-token <token>: Bearer token for OneTest server API calls (optional)
• --timeout, -t <timeout>: Request timeout in milliseconds (default: 30000)
• --verbose: Enable verbose logging
• --help: Show help information
• --version: Show version information

Examples

# Basic usage
onetest-mcp-server --url http://localhost:3000/api/v1

# With bearer token authentication
onetest-mcp-server --url http://localhost:3000/api/v1 --one-test-token YOUR_TOKEN_HERE

# With custom timeout and verbose logging
onetest-mcp-server --url https://api.onetest.com/v1 --timeout 60000 --verbose

# Full configuration with token
onetest-mcp-server --url http://localhost:3000/api/v1 --one-test-token syg_72dc12525c0d6ffc3c930f28a7d43300e5841abc49a4627dccf2c2c33e3a0c57 --verbose

# Using yarn dlx for one-time execution (Yarn 2+)
yarn dlx @okep/onetest-mcp-server --url http://localhost:3000/api/v1 --verbose

# Using npx for one-time execution (alternative)
npx @okep/onetest-mcp-server --url http://localhost:3000/api/v1 --verbose

# Using yarn start for local development
cd tools/onetest-mcp-server
yarn start --url http://localhost:3000/api/v1 --one-test-token YOUR_TOKEN_HERE --verbose

MCP Client Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "onetest": {
      "command": "onetest-mcp-server",
      "args": ["--url", "http://localhost:3000/api/v1", "--one-test-token", "YOUR_TOKEN_HERE"],
      "env": {}
    }
  }
}

For Claude Desktop (using yarn dlx - Yarn 2+ only):

{
  "mcpServers": {
    "onetest": {
      "command": "yarn",
      "args": [
        "dlx",
        "@okep/onetest-mcp-server", 
        "--url", "http://localhost:3000/api/v1",
        "--one-test-token", "YOUR_TOKEN_HERE"
      ],
      "env": {}
    }
  }
}

For Claude Desktop (using npx - alternative):

{
  "mcpServers": {
    "onetest": {
      "command": "npx",
      "args": [
        "@okep/onetest-mcp-server", 
        "--url", "http://localhost:3000/api/v1",
        "--one-test-token", "YOUR_TOKEN_HERE"
      ],
      "env": {}
    }
  }
}

For local development (using built version):

{
  "mcpServers": {
    "onetest": {
      "command": "node",
      "args": [
        "/path/to/synergy/tools/onetest-mcp-server/dist/index.js",
        "--url", "http://localhost:3000/api/v1",
        "--one-test-token", "YOUR_TOKEN_HERE"
      ],
      "env": {}
    }
  }
}

Testing

Testing the MCP Server

To verify the MCP server is running properly:

1. Check server startup: Run with --verbose flag to see startup logs:

yarn start --url http://localhost:3000/api/v1 --one-test-token YOUR_TOKEN_HERE --verbose

1. Test API connectivity: Verify the backend API is accessible with your token:

# Test applications endpoint
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -H "Content-Type: application/json" \
     "http://localhost:3000/api/v1/applications?workspace_id=test&limit=1"

# Test with your specific token
curl -H "Authorization: Bearer syg_72dc12525c0d6ffc3c930f28a7d43300e5841abc49a4627dccf2c2c33e3a0c57" \
     -H "Content-Type: application/json" \
     "http://localhost:3000/api/v1/applications?workspace_id=test&limit=1"

1. Use MCP Inspector (if available):

The MCP Inspector runs the server as a subprocess. You need to pass the server command and arguments separately:

# Install globally with yarn (Yarn 1.x compatible)
yarn global add @modelcontextprotocol/inspector

# Run the inspector with the server command
# Note: The inspector runs the server internally, so pass the full command
mcp-inspector node tools/onetest-mcp-server/dist/index.js --url http://localhost:3000/api/v1 --one-test-token YOUR_TOKEN_HERE

Alternative: Manual testing without inspector

# Start your server in one terminal
yarn start --url http://localhost:3000/api/v1 --one-test-token YOUR_TOKEN_HERE --verbose

# Test with direct JSON-RPC calls (advanced)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc localhost 3001

Expected Responses

• MCP Server: Should show "OneTest MCP server started successfully" when running with --verbose
• API Test: Should return JSON data or authentication redirect (depending on backend configuration)
• Authentication Issues: If you get Keycloak redirect responses, the backend may require different authentication

Tools

The server provides 7 tools based on the OneTest API:

1. create-test-from-description

Convert natural language test descriptions into executable test scenarios using AI.

Parameters:

• description (string): Natural language description of the test scenario (10-2000 chars)
• applicationId (string): ID of the target application
• workspaceId (string): Blazemeter workspace ID
• testType (string): Type of test to generate (functional | performance, default: functional)

2. execute-test-suite

Execute a test suite and return execution details.

Parameters:

• suiteId (string): ID of the test suite to execute
• workspaceId (string): Blazemeter workspace ID
• environments (string[]): Environment IDs to use for execution (min 1)

3. manage-applications

Manage application lifecycle and configuration.

Parameters:

• action (string): Action to perform (list | create | get | update | delete)
• workspaceId (string): Blazemeter workspace ID
• applicationId (string, optional): Required for get, update, and delete actions
• application (object, optional): Application data for create and update actions

4. manage-test-environments

Configure and manage testing environments.

Parameters:

• action (string): Action to perform (list | create | get | update | delete | list-devices | list-locations)
• workspaceId (string): Blazemeter workspace ID
• applicationId (string, optional): Application ID for filtering
• environmentId (string, optional): Required for get, update, and delete actions
• environment (object, optional): Environment data for create and update actions

5. create-policy-rules

Generate testing policies and rules from requirements using AI.

Parameters:

• policyText (string): Natural language policy document (50-5000 chars)
• existingRules (array, optional): Existing rules to merge with

6. schedule-test-execution

Schedule automated test execution using natural language.

Parameters:

• suiteId (string): Test suite ID to schedule
• schedule (string): Natural language schedule description
• timezone (string): Timezone code (default: UTC)
• environments (string[]): Environment IDs to use

7. upload-test-assets

Upload and manage test assets and files.

Parameters:

• action (string): Action to perform (upload | list | get | delete)
• workspaceId (string): Blazemeter workspace ID
• applicationId (string, optional): Application ID for file association
• fileId (string, optional): Required for get and delete actions
• file (object, optional): File data for upload action

Resources

The server provides 4 resources for browsing OneTest data:

1. test-scenarios

URI: onetest://test-scenarios

Browse test scenarios with filtering options:

• applicationId: Filter by application
• workspaceId: Filter by workspace
• testType: Filter by test type
• limit: Number of results (default: 20)
• offset: Result offset (default: 0)

2. test-results

URI: onetest://test-results

Browse test execution results and history:

• applicationId: Filter by application
• workspaceId: Filter by workspace
• suiteRunId: Filter by suite run
• scenarioId: Filter by scenario
• status: Filter by execution status
• limit: Number of results (default: 20)
• offset: Result offset (default: 0)

3. test-environments

URI: onetest://test-environments

Browse testing environments and devices:

• applicationId: Filter by application
• workspaceId: Filter by workspace
• type: Filter by environment type

4. applications

URI: onetest://applications

Browse registered applications:

• workspaceId: Filter by workspace (required)
• type: Filter by application type

Development

Prerequisites

• Node.js 18+
• TypeScript
• OneTest backend API running

Setup

# Clone the repository
git clone <repository-url>
cd tools/onetest-mcp-server

# Install dependencies
yarn install

# Build the project
yarn build

Development Scripts

# Build the project
yarn build

# Watch mode for development
yarn dev

# Run tests
yarn test
yarn test:watch
yarn test:coverage

# Lint and format
yarn lint
yarn lint:fix
yarn format

# Publishing (for maintainers)
yarn publish          # Publishes to npm with public access

Publishing

The package is automatically published to npm registry when changes are pushed to the main branch. The Jenkins pipeline handles:

• Version checking (ensures version doesn't already exist)
• Building and testing
• Publishing with public access to npm
• GitHub release creation

For manual publishing:

# Ensure you're logged in to npm as okep
yarn login

# Update version in package.json
yarn version --new-version <version>

# Build and test before publishing
yarn prepublishOnly

# Publish to npm
yarn publish

Environment Variables Required:

• NPM_TOKEN: Your npm authentication token (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)

Testing

The project includes comprehensive tests covering:

• API service functionality
• MCP tool implementations
• Server setup and error handling
• Resource fetching and formatting

# Run all tests
yarn test

# Run tests with coverage
yarn test:coverage

# Run tests in watch mode
yarn test:watch

Architecture

onetest-mcp-server/
├── src/
│   ├── types/           # TypeScript type definitions and Zod schemas
│   ├── services/        # API service layer
│   ├── tools/           # MCP tool implementations
│   ├── resources/       # MCP resource implementations
│   ├── __tests__/       # Test files
│   ├── server.ts        # Main MCP server class
│   └── index.ts         # CLI entry point
├── dist/                # Compiled JavaScript output
└── package.json         # Package configuration

Key Components

• OneTestApiService: HTTP client for OneTest backend API
• OneTestMcpServer: Main MCP server implementation
• Tools: Individual MCP tool handlers
• Resources: MCP resource handlers for browsing data
• Types: TypeScript definitions with Zod validation

Error Handling

The server includes comprehensive error handling:

• Input validation using Zod schemas
• HTTP error handling with meaningful messages
• Tool execution error handling
• Resource access error handling
• Graceful degradation for API failures

Security Considerations

• Bearer tokens are passed through command line arguments and HTTP headers
• No authentication credentials are stored permanently in the server
• Sensitive configuration data is filtered from responses
• All API requests include proper headers and timeouts
• Input validation prevents malicious inputs
• Command line tokens may be visible in process lists - consider using environment variables for production

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT

Support

For issues and questions:

• Create an issue in the repository
• Check the OneTest documentation
• Contact the OneTest team

Changelog

1.0.0

• Initial release
• Support for all 7 MCP tools from specification
• Support for all 4 MCP resources
• Comprehensive test coverage
• CLI interface with npx support
• Full TypeScript support with Zod validation