@uplinq/mcp-vitest

A Model Context Protocol (MCP) server for Vitest that provides real-time test monitoring and execution with watch-mode support.

Features

✅ Real-time test monitoring - Watch mode detects file changes and re-runs tests automatically
✅ Individual test result reporting - See specific test names, statuses, and error messages
✅ Stable operation - No crashes during watch mode operation
✅ Comprehensive test detection - Handles nested test suites and complex file structures
✅ Rich error reporting - Detailed error messages for failing tests with file paths
✅ MCP integration - Works seamlessly with Claude Code and other MCP clients

Installation

# Install globally
npm install -g @uplinq/mcp-vitest

# Or use with npx
npx @uplinq/mcp-vitest --version

Usage

As MCP Server

Add to your MCP client configuration (e.g., Claude Code):

{
  "mcpServers": {
    "vitest": {
      "command": "npx",
      "args": ["@uplinq/mcp-vitest"],
      "cwd": "/path/to/your/project"
    }
  }
}

Direct Usage

# Start the MCP server
npx @uplinq/mcp-vitest

# Or in a specific directory
cd /path/to/your/vitest-project
npx @uplinq/mcp-vitest

MCP Tools

The server automatically starts Vitest in watch mode when initialized, monitoring file changes and running tests automatically. It provides these tools for MCP clients:

get_test_status

Get current test results including:

• Test discovery status (whether all tests have been discovered and run/skipped at least once)
• Total test counts (passed/failed/skipped)
• Individual test details with Vitest TaskState values and error information
• File-level test information
• Last update timestamps

get_failing_tests

Get a list of all currently failing tests with detailed error information, including:

• Test discovery status (whether all tests have been discovered and run/skipped at least once)
• Detailed error information for each failing test using Vitest's ErrorWithDiff format

Example Output

Get comprehensive test status with real-time results:

{
  "status": "complete",
  "summary": {
    "total": 42,
    "passed": 35,
    "failed": 4,
    "skipped": 3
  },
  "files": {
    "/project/src/utils.test.ts": {
      "total": 8,
      "passed": 6,
      "failed": 2,
      "skipped": 0
    }
  },
  "lastUpdate": "2024-01-15T10:30:00.000Z"
}

Get detailed failing test information:

{
  "status": "complete",
  "failingTests": [
    {
      "id": "test-123",
      "name": "should validate email format",
      "file": "/project/src/utils.test.ts",
      "errors": [
        {
          "name": "AssertionError",
          "message": "Expected 'invalid@' to be valid email"
        }
      ]
    }
  ],
  "count": 1
}

Discovery Status Values

• "discovering" - Vitest is still discovering and running tests for the first time
• "complete" - All tests have been discovered and run/skipped at least once
• "error" - Test discovery failed due to configuration or syntax errors

Test State Values (Vitest TaskState)

Individual tests use Vitest's native TaskState values:

• "pass" - Test executed successfully
• "fail" - Test executed but failed with errors
• "skip" - Test was skipped (e.g., using test.skip())
• "todo" - Test marked as todo (e.g., using test.todo())
• "run" - Test is queued to run or currently running
• "only" - Test marked to run exclusively (e.g., using test.only())
• "queued" - Test is queued for execution

Requirements

• Node.js 18.0.0 or higher
• A project with Vitest configured
• Vitest 3.x

Configuration

The server automatically detects your Vitest configuration. It works with:

• vitest.config.ts/js
• vite.config.ts/js
• Package.json vitest configuration
• Default Vitest settings

Troubleshooting

"Cannot find package 'vitest'" Error

This usually means Vitest isn't installed in your project:

npm install --save-dev vitest

Tests Not Detected

Make sure your test files follow Vitest naming conventions:

• *.test.{js,ts,jsx,tsx}
• *.spec.{js,ts,jsx,tsx}
• Files in __tests__/ directories

Watch Mode Not Working

Ensure your project has test files and Vitest is properly configured:

# Test that Vitest works directly
npx vitest run

# Check your vitest configuration
npx vitest --help

Development

# Clone the repository
git clone <repository-url>
cd mcp-vitest

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run locally
npm run dev

Architecture

The server uses Vitest's Node.js API directly for maximum stability and performance:

• Direct API Integration: Uses createVitest() from vitest/node for reliable test execution
• Real-time Results: Monitors Vitest state changes to provide immediate feedback
• Robust Parsing: Handles nested test suites and complex file structures
• Error Resilience: Graceful handling of syntax errors and test failures

Version History

v0.2.1

• Fix: Move vitest from devDependencies to dependencies to resolve import errors

v0.2.0

• Major: Fixed critical MCP server crashes during watch mode
• Major: Implemented proper test detection showing actual file paths
• Enhancement: Added comprehensive individual test result parsing
• Enhancement: Improved stability by replacing worker threads with direct Vitest API
• Enhancement: Added extensive test coverage for reliability

v0.1.1

• Initial bug fix release

v0.1.0

• Initial implementation with basic watch-mode support

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.