Skip to main content
Glama

Vitest Migrator MCP (vitest-migrator-mcp)

A Model Context Protocol (MCP) Server that provides automated AST codemods, multi-project test runner scaffolding, and self-learning diagnostic tools for migrating JavaScript/TypeScript packages from legacy test runners (Karma, Webpack, Mocha) to Vitest (Node and Playwright Chromium browser testing).


Prerequisites

  • Node.js: >= 18.0.0 (Node 20 or Node 22 recommended)

  • Package Manager: npm, yarn, or pnpm

  • Supported OS: Linux, macOS, Windows (WSL / Native)


Related MCP server: MCP Server - Test Migration (WDIO to Playwright)

Installation & Setup

1. Clone and Build Locally

# Clone the repository
git clone https://github.com/Manvi1203/vitest-migrator-mcp.git
cd vitest-migrator-mcp

# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

This generates the executable entry point at dist/index.js.


Connecting to MCP Clients

The server communicates via standard I/O (stdio). You can register it in any MCP-compatible AI assistant or editor.

A. Claude Desktop

Add the server to your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vitest-migrator": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/vitest-migrator-mcp/dist/index.js"]
    }
  }
}

B. Cursor / VS Code (Cline / Roo Code / MCP Extension)

Add to your MCP configuration file (mcp.json or Extension settings):

{
  "mcpServers": {
    "vitest-migrator": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/vitest-migrator-mcp/dist/index.js"]
    }
  }
}

C. Gemini CLI / Jetski / Antigravity

Add to your workspace or global mcp_config.json:

{
  "mcpServers": {
    "vitest-migrator": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/vitest-migrator-mcp/dist/index.js"]
    }
  }
}

Exposed MCP Tools Reference

The server exposes 7 specialized tools designed for test suite analysis, transformation, and verification:

Tool

Parameters

Description

vitest_classify_package

packagePath: string

Inspects package.json, test directories, and karma configs to classify the package tier (tier1: standard unit, tier2: emulator/integration, tier3: complex multi-target/platform aliased).

vitest_scaffold_config

packagePath: string, tier?: string

Scaffolds unified vitest.config.mjs (Node + Chromium projects), src/types/vitest-globals.d.ts, and test/setup.ts, and updates package.json test scripts with Playwright guards.

vitest_apply_ast_codemods

packagePath: string

Executes deterministic AST transformations (ts-morph) to fix type-only re-exports (export type), chained Mocha .timeout(ms), this.test.fullTitle(), and CommonJS require() imports.

vitest_run_verification

packagePath: string, target: "vitest-browser" | "vitest-node" | "mocha-node"

Executes the test suite in headless mode and parses test execution outputs into structured JSON pass/fail diagnostics.

vitest_lookup_knowledge_bank

errorMessage: string

Matches runtime errors against indexed error signatures and returns root cause explanations and recommended code transforms.

vitest_record_learning

errorPattern: string, rule: string, rootCause: string, fixStrategy: "AST_TRANSFORM" | "AI_PROMPT"

Dynamically adds newly discovered error patterns and resolution strategies to data/knowledge-bank.json.

vitest_list_knowledge_rules

(none)

Returns all active rules and diagnostic patterns stored in the knowledge base.


Step-by-Step Package Migration Workflow

When migrating a package with an AI agent or automated script, follow this structured pipeline:

flowchart TD
    A[1. vitest_classify_package] --> B[2. vitest_scaffold_config]
    B --> C[3. vitest_apply_ast_codemods]
    C --> D[4. vitest_run_verification]
    D -->|Pass| E[5. Complete]
    D -->|Fail| F[6. vitest_lookup_knowledge_bank]
    F --> G[7. Apply Fix & vitest_record_learning]
    G --> D

1. Classify the Package

Inspect complexity, target runtime, and emulator dependencies:

{
  "name": "vitest_classify_package",
  "arguments": {
    "packagePath": "/path/to/my-monorepo/packages/auth"
  }
}

2. Scaffold Configs & Dependencies

Generate multi-project configurations and package scripts:

{
  "name": "vitest_scaffold_config",
  "arguments": {
    "packagePath": "/path/to/my-monorepo/packages/auth",
    "tier": "tier3"
  }
}

3. Run Deterministic AST Codemods

Automatically rewrite syntax that differs between Karma/Webpack and Vitest ESM:

{
  "name": "vitest_apply_ast_codemods",
  "arguments": {
    "packagePath": "/path/to/my-monorepo/packages/auth"
  }
}

4. Execute Verification Loop

Run browser and Node unit tests headlessly:

{
  "name": "vitest_run_verification",
  "arguments": {
    "packagePath": "/path/to/my-monorepo/packages/auth",
    "target": "vitest-browser"
  }
}

5. Diagnose & Record Fixes

If a test failure occurs, query the Knowledge Bank or save the solution:

{
  "name": "vitest_lookup_knowledge_bank",
  "arguments": {
    "errorMessage": "TypeError: Cannot redefine property: getAuth"
  }
}

Architecture & File Layout

vitest-migrator-mcp/
├── data/
│   └── knowledge-bank.json      # Persistent error signatures and fix rules
├── src/
│   ├── index.ts                 # MCP Server entrypoint (stdio protocol handler)
│   ├── templates/               # Boilerplate templates injected during scaffolding
│   │   ├── setup.ts.tpl         # Browser test setup (Chai, Sinon, Mocha aliases)
│   │   ├── setup.node.ts.tpl    # Node test setup
│   │   ├── vitest.config.mjs.tpl# Multi-project runner config
│   │   └── vitest-globals.d.ts.tpl # Ambient typing definitions
│   └── tools/
│       ├── classifier.ts        # Package analysis logic
│       ├── scaffolder.ts        # Config & package.json injector
│       ├── codemods.ts          # ts-morph AST transformations
│       ├── runner.ts            # Test execution and stdout parser
│       └── knowledgeBank.ts     # Diagnostic knowledge lookup and rule persistence
├── package.json
└── tsconfig.json

Development & Maintenance

Build from Source

npm run build

Watch Mode

npm run watch

Test Stdio Directly

You can run the server directly in terminal to verify startup:

node dist/index.js

License

Apache-2.0

Available Tools

7 tools
vitest_apply_ast_codemodsA

Executes TypeScript AST transformations using ts-morph to fix isolated ESM type exports, Mocha timeouts, and require() calls.

Inputs: packagePath (required).

vitest_classify_packageB

Analyzes a package in the repository to determine its Vitest migration tier (simple unit vs emulator/integration vs multi-target platform aliases).

Inputs: packagePath (required).

vitest_list_knowledge_rulesA

Lists all currently known migration rules stored in the Knowledge Bank.

Inputs: no named parameters.

vitest_lookup_knowledge_bankA

Queries the permanent Knowledge Bank for known error signatures and returns diagnosis, root cause, and fix template.

Inputs: errorMessage (required).

vitest_record_learningA

Records a newly resolved error pattern, root cause, and fix template into the permanent Knowledge Bank.

Inputs: fixRule (required), rootCause (required), errorSignature (required), name, +1 more.

vitest_run_verificationB

Runs test verification for Vitest Browser, Vitest Node, or legacy Mocha Node / Karma Browser in the target package.

Inputs: packagePath (required), target.

vitest_scaffold_configB

Deterministically generates vitest.config.browser.mjs, test/setup.ts, and adds package.json test:vitest:browser script.

Inputs: packagePath (required), tier.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, from classification to scaffolding to AST transforms to verification. The only mild ambiguity is between lookup_knowledge_bank and list_knowledge_rules, though descriptions clarify that one searches error signatures while the other lists stored rules.

    Naming Consistency5/5

    All tools follow a consistent snake_case pattern with a vitest_ prefix followed by a verb and object: classify_package, scaffold_config, apply_ast_codemods, run_verification. The naming is uniform and predictable across the entire tool set.

    Tool Count5/5

    Seven tools is well-scoped for a Vitest migration server, covering assessment, scaffolding, transformation, verification, and knowledge management without bloat. Each tool contributes a distinct step in the migration workflow.

    Completeness4/5

    The tool set covers the core migration lifecycle: classify, scaffold, apply codemods, verify, and consult/extend knowledge. Minor gaps exist around managing migration state or deleting/updating knowledge rules, but agents can complete the primary workflow without dead endings.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      C
      quality
      D
      maintenance
      Enables comprehensive analysis of JavaScript/TypeScript project testing setups by detecting frameworks like Jest, Vitest, and Cypress, analyzing test coverage metrics, and generating actionable recommendations for improving test quality. Provides detailed insights into test structure, dependencies, and coverage thresholds with visual feedback.
      3
      1
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to safely upgrade JavaScript and TypeScript projects through dependency analysis, upgrade path detection, breaking change identification, codemod application, and PR summary generation.
      14
      22 npm
      MIT