start_environment

Creates a temporary local test environment for WordPress/WooCommerce testing with customizable PHP, plugin, and theme configurations.

Instructions

Start a local QIT test environment. Creates a temporary, ephemeral environment for testing.

⚠️ QIT CLI not detected. QIT CLI not found. Please install it using one of these methods:

Via Composer (recommended): composer require woocommerce/qit-cli --dev
Set QIT_CLI_PATH environment variable: export QIT_CLI_PATH=/path/to/qit
Ensure 'qit' is available in your system PATH

For more information, visit: https://github.com/woocommerce/qit-cli

Input Schema

TableJSON Schema

Name	Required	Description
`environment_type`	No	Type of environment to create: 'e2e' or 'performance'
`php_version`	No	PHP version to use (e.g., '8.1', '8.2', '8.3')
`wp_version`	No	WordPress version to use (e.g., '6.4', '6.5', 'stable', 'rc')
`wc_version`	No	WooCommerce version to use (e.g., '8.5', '9.0', 'latest')
`plugins`	No	Plugins to install (slug, path, or URL)
`themes`	No	Themes to install (slug, path, or URL)
`test_packages`	No	Test packages to set up environment from
`utilities`	No	Utility packages for environment setup
`volumes`	No	Docker volumes to mount (host:container format)
`php_extensions`	No	PHP extensions to enable
`env_vars`	No	Environment variables to set (key-value pairs)
`object_cache`	No	Enable Redis object cache
`tunnel`	No	Enable tunnelling method (cloudflare, ngrok)
`config`	No	Path to qit.json configuration file
`skip_setup`	No	Skip running setup phases even if qit-test.json is found
`skip_activating_plugins`	No	Skip activating plugins during environment setup
`skip_activating_themes`	No	Skip activating themes during environment setup
`json`	No	Return output in JSON format

Implementation Reference

src/tools/environment.ts:86-163 (handler)

The async handler function that implements the core logic of the 'start_environment' tool by mapping input arguments to QIT CLI flags, building the 'qit env:up' command arguments, and executing it via executeAndFormat with a 10-minute timeout.

handler: async (args: {
  environment_type?: (typeof environmentTypes)[number];
  php_version?: string;
  wp_version?: string;
  wc_version?: string;
  plugins?: string[];
  themes?: string[];
  test_packages?: string[];
  utilities?: string[];
  volumes?: string[];
  php_extensions?: string[];
  env_vars?: Record<string, string>;
  object_cache?: boolean;
  tunnel?: (typeof tunnelMethods)[number];
  config?: string;
  skip_setup?: boolean;
  skip_activating_plugins?: boolean;
  skip_activating_themes?: boolean;
  json?: boolean;
}) => {
  // Use canonical flag names from the trunk QIT CLI
  // These support aliases (--wp, --woo) for backwards compatibility
  const flags: Record<string, string | boolean | undefined> = {
    environment_type: args.environment_type,
    php_version: args.php_version,
    wordpress_version: args.wp_version,
    woocommerce_version: args.wc_version,
    object_cache: args.object_cache,
    tunnel: args.tunnel,
    config: args.config,
    "skip-setup": args.skip_setup,
    skip_activating_plugins: args.skip_activating_plugins,
    skip_activating_themes: args.skip_activating_themes,
    json: args.json,
  };

  const cmdArgs = buildArgs("env:up", [], flags);

  // Add array-based flags
  if (args.plugins?.length) {
    for (const plugin of args.plugins) {
      cmdArgs.push("--plugin", plugin);
    }
  }
  if (args.themes?.length) {
    for (const theme of args.themes) {
      cmdArgs.push("--theme", theme);
    }
  }
  if (args.test_packages?.length) {
    for (const pkg of args.test_packages) {
      cmdArgs.push("--test-package", pkg);
    }
  }
  if (args.utilities?.length) {
    for (const util of args.utilities) {
      cmdArgs.push("--utility", util);
    }
  }
  if (args.volumes?.length) {
    for (const volume of args.volumes) {
      cmdArgs.push("--volume", volume);
    }
  }
  if (args.php_extensions?.length) {
    for (const ext of args.php_extensions) {
      cmdArgs.push("--php_extension", ext);
    }
  }
  if (args.env_vars) {
    for (const [key, value] of Object.entries(args.env_vars)) {
      cmdArgs.push("--env", `${key}=${value}`);
    }
  }

  // Environment startup can take a while
  return executeAndFormat(cmdArgs, { timeout: 600000 });
},

src/tools/environment.ts:12-85 (schema)

Zod inputSchema object defining the structure and descriptions of all input parameters for the start_environment tool, including environment_type, php_version, wp_version, plugins, themes, tunnel options, and more.

inputSchema: z.object({
  environment_type: z
    .enum(environmentTypes)
    .optional()
    .describe("Type of environment to create: 'e2e' or 'performance'"),
  php_version: z
    .string()
    .optional()
    .describe("PHP version to use (e.g., '8.1', '8.2', '8.3')"),
  wp_version: z
    .string()
    .optional()
    .describe("WordPress version to use (e.g., '6.4', '6.5', 'stable', 'rc')"),
  wc_version: z
    .string()
    .optional()
    .describe("WooCommerce version to use (e.g., '8.5', '9.0', 'latest')"),
  plugins: z
    .array(z.string())
    .optional()
    .describe("Plugins to install (slug, path, or URL)"),
  themes: z
    .array(z.string())
    .optional()
    .describe("Themes to install (slug, path, or URL)"),
  test_packages: z
    .array(z.string())
    .optional()
    .describe("Test packages to set up environment from"),
  utilities: z
    .array(z.string())
    .optional()
    .describe("Utility packages for environment setup"),
  volumes: z
    .array(z.string())
    .optional()
    .describe("Docker volumes to mount (host:container format)"),
  php_extensions: z
    .array(z.string())
    .optional()
    .describe("PHP extensions to enable"),
  env_vars: z
    .record(z.string())
    .optional()
    .describe("Environment variables to set (key-value pairs)"),
  object_cache: z
    .boolean()
    .optional()
    .describe("Enable Redis object cache"),
  tunnel: z
    .enum(tunnelMethods)
    .optional()
    .describe("Enable tunnelling method (cloudflare, ngrok)"),
  config: z
    .string()
    .optional()
    .describe("Path to qit.json configuration file"),
  skip_setup: z
    .boolean()
    .optional()
    .describe("Skip running setup phases even if qit-test.json is found"),
  skip_activating_plugins: z
    .boolean()
    .optional()
    .describe("Skip activating plugins during environment setup"),
  skip_activating_themes: z
    .boolean()
    .optional()
    .describe("Skip activating themes during environment setup"),
  json: z
    .boolean()
    .optional()
    .describe("Return output in JSON format"),
}),

src/tools/environment.ts:8-164 (registration)

The 'start_environment' tool object definition, specifying name, description, inputSchema, and handler function, exported as part of the environmentTools object.

start_environment: {
  name: "start_environment",
  description:
    "Start a local QIT test environment. Creates a temporary, ephemeral environment for testing.",
  inputSchema: z.object({
    environment_type: z
      .enum(environmentTypes)
      .optional()
      .describe("Type of environment to create: 'e2e' or 'performance'"),
    php_version: z
      .string()
      .optional()
      .describe("PHP version to use (e.g., '8.1', '8.2', '8.3')"),
    wp_version: z
      .string()
      .optional()
      .describe("WordPress version to use (e.g., '6.4', '6.5', 'stable', 'rc')"),
    wc_version: z
      .string()
      .optional()
      .describe("WooCommerce version to use (e.g., '8.5', '9.0', 'latest')"),
    plugins: z
      .array(z.string())
      .optional()
      .describe("Plugins to install (slug, path, or URL)"),
    themes: z
      .array(z.string())
      .optional()
      .describe("Themes to install (slug, path, or URL)"),
    test_packages: z
      .array(z.string())
      .optional()
      .describe("Test packages to set up environment from"),
    utilities: z
      .array(z.string())
      .optional()
      .describe("Utility packages for environment setup"),
    volumes: z
      .array(z.string())
      .optional()
      .describe("Docker volumes to mount (host:container format)"),
    php_extensions: z
      .array(z.string())
      .optional()
      .describe("PHP extensions to enable"),
    env_vars: z
      .record(z.string())
      .optional()
      .describe("Environment variables to set (key-value pairs)"),
    object_cache: z
      .boolean()
      .optional()
      .describe("Enable Redis object cache"),
    tunnel: z
      .enum(tunnelMethods)
      .optional()
      .describe("Enable tunnelling method (cloudflare, ngrok)"),
    config: z
      .string()
      .optional()
      .describe("Path to qit.json configuration file"),
    skip_setup: z
      .boolean()
      .optional()
      .describe("Skip running setup phases even if qit-test.json is found"),
    skip_activating_plugins: z
      .boolean()
      .optional()
      .describe("Skip activating plugins during environment setup"),
    skip_activating_themes: z
      .boolean()
      .optional()
      .describe("Skip activating themes during environment setup"),
    json: z
      .boolean()
      .optional()
      .describe("Return output in JSON format"),
  }),
  handler: async (args: {
    environment_type?: (typeof environmentTypes)[number];
    php_version?: string;
    wp_version?: string;
    wc_version?: string;
    plugins?: string[];
    themes?: string[];
    test_packages?: string[];
    utilities?: string[];
    volumes?: string[];
    php_extensions?: string[];
    env_vars?: Record<string, string>;
    object_cache?: boolean;
    tunnel?: (typeof tunnelMethods)[number];
    config?: string;
    skip_setup?: boolean;
    skip_activating_plugins?: boolean;
    skip_activating_themes?: boolean;
    json?: boolean;
  }) => {
    // Use canonical flag names from the trunk QIT CLI
    // These support aliases (--wp, --woo) for backwards compatibility
    const flags: Record<string, string | boolean | undefined> = {
      environment_type: args.environment_type,
      php_version: args.php_version,
      wordpress_version: args.wp_version,
      woocommerce_version: args.wc_version,
      object_cache: args.object_cache,
      tunnel: args.tunnel,
      config: args.config,
      "skip-setup": args.skip_setup,
      skip_activating_plugins: args.skip_activating_plugins,
      skip_activating_themes: args.skip_activating_themes,
      json: args.json,
    };

    const cmdArgs = buildArgs("env:up", [], flags);

    // Add array-based flags
    if (args.plugins?.length) {
      for (const plugin of args.plugins) {
        cmdArgs.push("--plugin", plugin);
      }
    }
    if (args.themes?.length) {
      for (const theme of args.themes) {
        cmdArgs.push("--theme", theme);
      }
    }
    if (args.test_packages?.length) {
      for (const pkg of args.test_packages) {
        cmdArgs.push("--test-package", pkg);
      }
    }
    if (args.utilities?.length) {
      for (const util of args.utilities) {
        cmdArgs.push("--utility", util);
      }
    }
    if (args.volumes?.length) {
      for (const volume of args.volumes) {
        cmdArgs.push("--volume", volume);
      }
    }
    if (args.php_extensions?.length) {
      for (const ext of args.php_extensions) {
        cmdArgs.push("--php_extension", ext);
      }
    }
    if (args.env_vars) {
      for (const [key, value] of Object.entries(args.env_vars)) {
        cmdArgs.push("--env", `${key}=${value}`);
      }
    }

    // Environment startup can take a while
    return executeAndFormat(cmdArgs, { timeout: 600000 });
  },
},

src/tools/index.ts:10-19 (registration)
Central aggregation of all tool sets (including environmentTools with start_environment) into the allTools object, which is imported and used by the MCP server for tool registration.
```
export const allTools = {
  ...authTools,
  ...testExecutionTools,
  ...testResultsTools,
  ...groupsTools,
  ...environmentTools,
  ...packagesTools,
  ...configTools,
  ...utilitiesTools,
};
```

src/server.ts:25-38 (registration)

MCP server request handler for listing tools, which iterates over allTools to produce the list of available tools including start_environment with their schemas.

server.setRequestHandler(ListToolsRequestSchema, async () => {
  // Check if QIT CLI is available
  const cliInfo = detectQitCli();

  const tools = Object.entries(allTools).map(([_, tool]) => ({
    name: tool.name,
    description: cliInfo
      ? tool.description
      : `${tool.description}\n\n⚠️ QIT CLI not detected. ${getQitCliNotFoundError()}`,
    inputSchema: zodToJsonSchema(tool.inputSchema),
  }));

  return { tools };
});

QIT MCP Server