vitest-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides AI-optimized Vitest testing tools. The server offers structured JSON output, intelligent test targeting, coverage analysis, and safety guards to prevent accidental full test suite runs.

Development Commands

Building and Development

• npm run build - Compile TypeScript to JavaScript in dist/ folder and make executable
• npm run dev - Watch mode compilation with TypeScript
• npm start - Run the compiled MCP server
• npm run lint - Run ESLint on TypeScript source files
• npm test - Run the project's own test suite using Vitest
• npm run prepare - Build before publishing (runs automatically on install)

Development Mode (Self-Testing)

When developing the MCP server itself, you can enable development mode to test it on its own repository:

1. Set the environment variable in .env.development:

   VITEST_MCP_DEV_MODE=true
   

2. Build and run the server:

   npm run build
   npm start
   

3. Use the tools on the repository itself:

   set_project_root({ path: "/path/to/vitest-mcp" })  // Now allowed in dev mode
   run_tests({ target: "./src/tools" })
   

This bypasses the self-protection check that normally prevents the MCP server from running on itself.

Testing Commands

• IMPORTANT: Always use the project's own MCP tools for testing, not raw vitest commands
• set_project_root({ path: "/absolute/path/to/project" }) - Required first step
• run_tests({ target: "./src/components", format: "detailed" }) - Run specific tests
• analyze_coverage({ target: "./src", threshold: 80 }) - Coverage analysis
• list_tests({ directory: "./src" }) - Find test files

Single Test Execution

When working on a specific test file, use:

run_tests({ 
  target: "./src/tools/__tests__/list-tests.test.ts",
  format: "detailed" 
})