vitest-migrator-mcp
Provides tools for migrating JavaScript/TypeScript test suites to Vitest, including package classification, Vitest configuration and setup scaffolding, AST-based codemods, and headless test execution for verification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vitest-migrator-mcp Migrate the auth package from Karma to Vitest and fix any issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, orpnpmSupported 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 buildThis 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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 |
|
| Inspects |
|
| Scaffolds unified |
|
| Executes deterministic AST transformations ( |
|
| Executes the test suite in headless mode and parses test execution outputs into structured JSON pass/fail diagnostics. |
|
| Matches runtime errors against indexed error signatures and returns root cause explanations and recommended code transforms. |
|
| Dynamically adds newly discovered error patterns and resolution strategies to |
| (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 --> D1. 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.jsonDevelopment & Maintenance
Build from Source
npm run buildWatch Mode
npm run watchTest Stdio Directly
You can run the server directly in terminal to verify startup:
node dist/index.jsLicense
Apache-2.0
Available Tools
7 toolsvitest_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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Test analytics for AI agents: test history, flaky tests, failure clusters, coverage.
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
Approved test intent, reviewed Playwright automation and run evidence, inside your editor.
Ship production-ready TypeScript code in half the time, at half the cost.
Related MCP Servers
- FlicenseCqualityDmaintenanceEnables 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.31-
- AlicenseAqualityDmaintenanceEnables migration of test automation projects from WebDriverIO to Playwright using AST-based transformations. Provides tools for analyzing tests, converting syntax, refactoring to Page Object Model, and generating migration reports.9MIT
- AlicenseAqualityDmaintenanceProvides automated analysis, audit, and code generation to migrate Nuxt 2/3 projects to Nuxt 3/4, with orchestrated multi-server workflow support.2310 npm5MIT
- AlicenseBqualityDmaintenanceEnables AI agents to safely upgrade JavaScript and TypeScript projects through dependency analysis, upgrade path detection, breaking change identification, codemod application, and PR summary generation.1422 npmMIT