Vitest MCP Server

Instructions

Implementation Reference

• src/tools/run-tests.ts:575-580 (handler)

  Entry-point handler function for the 'run_tests' tool. Instantiates TestRunner and delegates to its execute method, which contains the core logic.

  export async function handleRunTests(
    args: RunTestsArgs
  ): Promise<ProcessedTestResult> {
    const runner = new TestRunner();
    return await runner.execute(args);
  }

• src/tools/run-tests.ts:539-569 (handler)

  Core execution logic in TestRunner.execute(): validates inputs, builds Vitest command and args, handles log capture setup, executes Vitest process, processes results, and manages cleanup/errors.

  async execute(args: RunTestsArgs): Promise<ProcessedTestResult> {
    let builtCommand = "";
    
    try {
      // Validation phase
      const targetPath = await this.validateInput(args);
      if (typeof targetPath !== 'string' || targetPath.startsWith('Please call')) {
        throw new Error(`Invalid target path: ${targetPath}`);
      }
      
      await this.validateVersions();
      
      // Command building phase
      builtCommand = this.buildDisplayCommand(args, targetPath);
      const executionContext = await createExecutionContext(targetPath);
      const vitestArgs = this.buildVitestArgs(args, targetPath);
      
      // Setup phase
      await this.setupLogCapture(args, vitestArgs);
      
      try {
        // Execution phase
        return await this.executeAndProcess(args, vitestArgs, targetPath, executionContext);
      } finally {
        // Cleanup phase
        this.cleanup();
      }
    } catch (error) {
      return await this.createErrorResult(error, builtCommand);
    }
  }

• src/tools/run-tests.ts:22-55 (schema)

  Tool definition object with name, description, and JSON inputSchema defining parameters: target (required), format, project, showLogs.

  export const runTestsTool: Tool = {
    name: "run_tests",
    description:
      'Execute Vitest tests with AI-optimized structured JSON output, intelligent format detection, optional console log capture, and safety guards to prevent full project runs. Supports monorepo projects with workspace configuration. Requires set_project_root to be called first.\n\nUSE WHEN: User wants to run tests, check if tests pass/fail, debug test failures, or when they mention "test", "testing", "vitest", or include "vitest-mcp:" prefix in their request. Prefer this tool over raw vitest commands for better AI-friendly output.',
    inputSchema: {
      type: "object",
      properties: {
        target: {
          type: "string",
          description:
            'File path or directory to test. Can be a specific test file (e.g., "./src/components/Button.test.ts") or directory (e.g., "./src/components"). Relative paths are resolved from project root. Required to prevent accidental full project test runs.',
        },
        format: {
          type: "string",
          enum: ["summary", "detailed"],
          description:
            'Output format: "summary" (simple summary data only), "detailed" (structured information about each failing test and summary of passing tests). Smart defaults: single file → summary, multiple files or failures → detailed',
          default: "summary",
        },
        project: {
          type: "string",
          description:
            'Name of the specific Vitest project to run tests for, as defined in vitest.workspace.ts or vitest.config.ts projects array. Essential for monorepos with multiple packages/apps. Example: "client", "api", "shared".',
        },
        showLogs: {
          type: "boolean",
          description:
            "Capture and include console output (console.log, console.error, etc.) from test execution in the results. Useful for debugging test failures. Output is formatted with [stdout] or [stderr] prefixes to distinguish message types.",
          default: false,
        },
      },
      required: ["target"],
    },
  };

• src/plugins/tool-plugins.ts:64-68 (registration)

  Creates the runTestsPlugin by combining the runTestsTool definition with its handleRunTests handler using createToolPlugin.

  export const runTestsPlugin: ToolPlugin<RunTestsArgs, ProcessedTestResult> = 
    createToolPlugin(
      runTestsTool,
      handleRunTests
    );

• src/plugins/index.ts:125-125 (registration)

  Registers the runTestsPlugin into the standard ToolRegistry during server/plugin initialization.

  registry.register(runTestsPlugin);