🚀 Tox Testing MCP Server

A test server based on the Model Context Protocol (MCP) for executing the tox command in Python projects to run pytest tests. This server provides a convenient way to run and manage Python tests via MCP.

✨ Features

Tools

run_tox_tests - Execute the tox test command, supporting multiple modes and options.
- Supported execution modes:
  - all: Run all tests or tests in a specified group.
  - file: Run tests in a specific file.
  - case: Run a specific test case.
  - directory: Run all tests in a specified directory.
- Supported test groups:
  - clients: Client-related tests.
  - api: API endpoint tests.
  - auth: Authentication tests.
  - uploads: Upload functionality tests.
  - routes: Route handler tests.

🚧 Development

Install dependencies

npm install

Build the server

npm run build

Automatic rebuild during development

npm run watch

📦 Installation

To use it in VSCode, add the server configuration to the MCP settings file at: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "tox-testing": {
      "command": "node",
      "args": ["/path/to/tox-testing/build/index.js"],
      "env": {
        "TOX_APP_DIR": "/path/to/your/python/project",
        "TOX_TIMEOUT": "600"
      }
    }
  }
}

Configuration Options

env.TOX_TIMEOUT: (Optional) The maximum waiting time for test execution in seconds. If a test runs longer than this timeout, it will be terminated. The default value is 600 seconds (10 minutes).
env.TOX_APP_DIR: (Required) The directory containing the tox.ini file. The tox command is executed in this directory. The path should point to the root directory of the Python project that contains the tox.ini file.

Timeout is especially important for:

Preventing test processes from hanging.
Managing long-running integration tests.
Ensuring that the CI/CD pipeline does not get stuck.

💻 Usage Examples

The server provides a tool run_tox_tests that can be used in different modes:

Tool Parameters

// Run all tests
{
  "mode": "all"
}

// Run tests in a specified group
{
  "mode": "all",
  "group": "api"
}

// Run tests in a specific file
{
  "mode": "file",
  "testFile": "tests/test_api.py"
}

// Run a specific test case
{
  "mode": "case",