@uplinq/mcp-vitest/README.md

MCP server for Vitest with watch-mode support for fast test feedback

# @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

```bash
# 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):

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

### Direct Usage

```bash
# 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:

```json
{
  "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:

```json
{
  "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:

```bash
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:

```bash
# Test that Vitest works directly
npx vitest run

# Check your vitest configuration
npx vitest --help
```

## Development

```bash
# 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.