Vitest MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

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

  Main handler function for the "run_tests" tool. Instantiates TestRunner and delegates execution.
  export async function handleRunTests( args: RunTestsArgs ): Promise<ProcessedTestResult> { const runner = new TestRunner(); return await runner.execute(args); }
• src/tools/run-tests.ts:22-55 (schema)

  Tool definition object including name, description, and inputSchema for the "run_tests" tool.
  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)

  Creation of the runTestsPlugin using the tool definition and handler function.
  export const runTestsPlugin: ToolPlugin<RunTestsArgs, ProcessedTestResult> = createToolPlugin( runTestsTool, handleRunTests );
• src/plugins/index.ts:123-126 (registration)

  Registration of runTestsPlugin (and other standard plugins) to the central ToolRegistry in createStandardToolRegistry.
  registry.register(setProjectRootPlugin); registry.register(listTestsPlugin); registry.register(runTestsPlugin); registry.register(analyzeCoveragePlugin);
• src/tools/run-tests.ts:539-569 (helper)

  TestRunner.execute method containing the core logic: validation, command construction, log capture setup, Vitest execution, result processing, and cleanup.
  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); } }