Cursor Test MCP – AI Test Engineer

License: MIT
Node.js Version: >=18.0.0

A Model Context Protocol (MCP) server that enables AI assistants in Cursor IDE to manage and understand project tests through automated test framework detection, execution, and analysis.

Features

• Framework Detection: Automatically detects test frameworks (Jest, Vitest, Mocha, pytest)
• Test Execution: Runs tests with timeout and output truncation
• Coverage Analysis: Reads and analyzes coverage reports
• Test Skeleton Generation: Generates test file skeletons for different frameworks
• Output Summarization: Parses and structures test output for AI understanding
• Error Handling: Robust error handling with detailed error messages

Quick Start

Installation

git clone https://github.com/your-username/cursor-test-mcp.git
cd cursor-test-mcp
npm install
npm run build

Or use the install script:

./install.sh

Manual Configuration

Create or edit ~/.cursor/mcp.json for global configuration:

{
  "mcpServers": {
    "cursor-test-mcp": {
      "command": "node",
      "args": ["/path/to/cursor-test-mcp/dist/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "info",
        "PROJECT_ROOT": "/optional/project/path"
      }
    }
  }
}

Note
If you already have other MCP servers defined, just add the cursor-test-mcp entry inside the existing mcpServers object.

After installation:

1. Restart Cursor
2. Enable cursor-test-mcp in the MCP settings

Available Tools

Framework Detection

Tool	Description
test_detect_framework	Detect the test framework and default test command

Test Execution

Tool	Description
test_run	Run tests and return summarized results

Coverage Analysis

Tool	Description
test_read_coverage	Read coverage summary and analyze lowest-covered files

Test Generation

Tool	Description
test_generate_skeleton	Generate test file skeleton for a given subject

Output Analysis

Tool	Description
test_summarize_output	Parse and structure raw test output

Tool Details

test_detect_framework

Detects the most likely test framework and default test command in the current project.

Input:

{
  "projectPath": "string (optional, absolute path)"
}

Behavior:

• If projectPath is not provided:
  • First checks PROJECT_ROOT environment variable
  • Falls back to process.cwd() (current working directory)
• Analyzes package.json, lock files, and pytest config files
• Detects Jest / Vitest / Mocha / pytest or generic npm test

Example Prompts:

• "Detect the test framework and show me the default test command for this project."
• "Bu projede hangi test framework'ü kullanılıyor, komutu ne olur?"

test_run

Runs the project's tests and returns a summarized result.

Input:

{
  "projectPath": "string (optional, absolute path)",
  "command": "string (optional, e.g. 'npm test', 'pytest -q')",
  "timeoutSeconds": "number (optional, default 180, max 3600)",
  "maxOutputLength": "number (optional, default 8000, max 200000)"
}

Behavior:

• If command is not provided, automatically detects and uses the default test command
• Truncates output to last maxOutputLength characters (optimized for AI consumption)
• Kills the command on timeout and returns "timed out" information

Example Prompts:

• "Run the tests for this project, summarize the output, and explain likely root causes for failures."
• "Tüm testleri çalıştır, son çıktıyı özetle ve hangi testler patlamış olabilir analiz et."

test_read_coverage

Reads a JSON coverage summary and returns overall coverage and lowest-covered files.

Input:

{
  "projectPath": "string (optional, absolute path)",
  "coverageFile": "string (optional, e.g. 'coverage/coverage-summary.json')",
  "topNLowestFiles": "number (optional, default 10, max 50)"
}

Behavior:

• If coverageFile is not provided, tries common Jest/Vitest locations
• Reads lines/statements/functions/branches coverage from total field
• Returns the first topNLowestFiles files with lowest line coverage

Example Prompts:

• "Read the Jest coverage summary and tell me which 5 files have the lowest line coverage."
• "Coverage özetini oku ve satır coverage'ı en düşük olan 5 dosyayı söyle."

test_generate_skeleton

Generates a test file skeleton (describe/it blocks) for a given subject and framework style.

Input:

{
  "framework": "string (optional, 'jest' | 'vitest' | 'mocha', default: 'jest')",
  "testFilePath": "string (required, e.g. 'src/utils/math.test.ts')",
  "subjectName": "string (required, e.g. 'sum' or 'ImageProcessor')",
  "description": "string (optional, high-level description)"
}

Behavior:

• Generates describe / it or assert based skeleton depending on framework
• Includes file path and subject name in describe blocks
• Returns skeleton as string (file writing decision left to user)

Example Prompts:

• "Generate a Jest test skeleton for src/utils/math.ts focusing on the sum function."
• "src/utils/math.ts içindeki sum fonksiyonu için Jest test iskeleti üret."

test_summarize_output

Parses raw test output (Jest/Vitest/Mocha/Pytest style) and returns a structured summary of failing tests and high-level stats.

Input:

{
  "rawOutput": "string (required, raw test output or CI log chunk)",
  "maxFailures": "number (optional, default 50, max 200)"
}

Behavior:

• Extracts file names from FAIL ... lines
• Extracts Jest/Vitest failure names from ● suite › test lines
• Captures Test Suites: and Tests: summary lines
• Guesses framework type (frameworkGuess field)
• Returns failures list with file, title, and rawBlock for each error

Example Prompts:

• "Given this Jest output, group the failing tests by file and explain each failure briefly."
• "Bu Jest çıktısına göre fail olan testleri dosyaya göre grupla ve her birinin neden patladığını kısaca açıkla."

Usage Examples

Detect Framework

"Detect the test framework and show me the default test command for this project."
"Bu projede hangi test framework'ü kullanılıyor?"

Run Tests

"Run all tests now and summarize the failing ones for me."
"Şimdi testleri çalıştır, eğer hata varsa bana kısa bir özet çıkar."

Read Coverage

"Read the coverage report and show files with lowest coverage."
"Coverage raporunu oku ve en düşük coverage'a sahip dosyaları göster."

Generate Test Skeleton

"Generate a Jest test skeleton for src/utils/math.ts focusing on the sum function."
"`src/utils/math.ts` içindeki `sum` fonksiyonu için Jest test iskeleti üret."

CLI Commands

node dist/index.js --help    # Show help
node dist/index.js           # Start MCP server (used by Cursor)

Project Structure

cursor-test-mcp/
├── src/
│   ├── index.ts              # Entry point with CLI
│   ├── server.ts             # MCP Server implementation
│   ├── tools/
│   │   └── test-tools.ts     # All test-related tools
│   └── utils/
│       └── logger.ts         # Logging utility
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
├── install.sh                # Installation script
├── LICENSE
└── README.md

Supported Frameworks

The test_detect_framework tool supports detection for:

Node.js:

• Jest (via jest or ts-jest dependencies)
• Vitest (via vitest dependency)
• Mocha (via mocha dependency)
• Generic npm/yarn/pnpm test scripts

Python:

• pytest (via pytest.ini, pyproject.toml, or requirements.txt)

Package Managers:

• npm (default)
• yarn (detected via yarn.lock or .yarnrc)
• pnpm (detected via pnpm-lock.yaml)

Error Handling

The server includes robust error handling:

• Timeout Management: Configurable timeout (default 180s, max 3600s) for test commands
• Output Truncation: Long outputs are truncated to prevent AI context overflow
• Detailed Errors: Error messages include hints for resolution
• Graceful Shutdown: Proper cleanup on SIGINT/SIGTERM signals
• Framework Detection Fallback: Returns "unknown" framework if detection fails

Environment Variables

Variable	Description	Required
LOG_LEVEL	Log level (debug, info, warn, error, default: info)	No
PROJECT_ROOT	Default project root directory (optional)	No
MCP_MODE	MCP transport mode (should be stdio for Cursor)	No

If PROJECT_ROOT is set, tests will run in that directory when projectPath is not provided.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Development Notes

• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Entry Point: src/index.ts → src/server.ts
• Tools: src/tools/test-tools.ts
• Logger: src/utils/logger.ts

To contribute:

1. Clone the repository or work in the existing directory
2. Add new MCP tools based on your test/coverage scenarios (test_*)
3. Build with npm run build and test in Cursor

Reference Validation Scenario

This MCP was manually validated on a complex Jest project with:

• Multiple test files (tests/math.test.ts, tests/userService.test.ts)
• Both successful and intentionally failing tests
• Async tests and domain errors (e.g., USER_INACTIVE, USER_NOT_ADMIN)
• Jest --coverage generated coverage/coverage-summary.json

Tool Results:

• test_detect_framework → Correctly detected Jest + npm test command
• test_run → Correctly carried 2 fail / 13 pass / 15 total information and error messages
• test_read_coverage → Returned global coverage and lowest coverage files matching Jest console table
• test_summarize_output → Correctly grouped failing tests by file and test name

This scenario can be used as a reference to demonstrate that MCP tools behave as expected in realistic and challenging projects.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Alican Kiraz - Inspiration from the MCP ecosystem
• n8n - Workflow automation platform (for MCP pattern reference)
• Anthropic - Model Context Protocol
• Cursor - AI-powered IDE