This MCP server enables AI agents to run and manage Cypress tests.
Run a specific Cypress spec with optional browser, headed mode, and grep filtering.
Run all tests in a project.
Stop the currently running test.
Get current test execution status and recent output.
Retrieve full console output with optional line limit and text filter.
List available spec files with optional name filter.
List or get the latest screenshots from test failures.
Clear screenshots and videos from a project.
Read live console output (cypress://output/live) and status (cypress://status) resources.
Provides tools to run Cypress tests, monitor execution, retrieve results, manage screenshots and videos, and list spec files, enabling AI agents to control Cypress test runners.
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., "@cypress-runner-mcp Run login tests in Chrome browser"
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.
A Model Context Protocol (MCP) server that enables AI agents (like Claude, GPT, etc.) to interact with and control Cypress test runners. This allows AI assistants to run tests, monitor execution, retrieve results, and manage test artifacts directly.
✅ Run Cypress tests via AI commands
📊 Real-time test monitoring with live output
🎯 Flexible test execution (single spec, filtered tests, or entire suites)
📸 Screenshot and video management for test failures
🔍 Test discovery - automatically list all available spec files
⏹️ Process control - start, stop, and monitor test runs
🌐 Multi-browser support (Chrome, Firefox, Edge, Electron)
🔄 Background execution - tests run asynchronously
📝 Detailed status reporting with exit codes and duration
Related MCP server: QA Testing MCP Server
Node.js >= 18.0.0
npm or pnpm or yarn
Cypress installed in your project
An MCP-compatible client (e.g., Cursor IDE, Claude Desktop)
# Clone the repository
git clone https://github.com/guyco6742/cypress-runner-mcp.git
cd cypress-runner-mcp
# Install dependencies (choose one)
npm install
# or
pnpm install
# or
yarn installnpm run buildThis compiles TypeScript to JavaScript in the dist/ folder.
Add this configuration to your .cursor/mcp.json:
{
"mcpServers": {
"cypress-mcp": {
"command": "node",
"args": ["/absolute/path/to/cypress-mcp-server/dist/index.js"],
"env": {
"CYPRESS_WORKSPACE": "/absolute/path/to/your/cypress/project"
}
}
}
}Add this to your Claude Desktop MCP config file:
macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"cypress-mcp": {
"command": "node",
"args": ["/absolute/path/to/cypress-mcp-server/dist/index.js"],
"env": {
"CYPRESS_WORKSPACE": "/absolute/path/to/your/cypress/project"
}
}
}
}CYPRESS_WORKSPACE: (Required) Absolute path to your Cypress project root directory
After configuration, restart Cursor IDE or Claude Desktop for changes to take effect.
cypress_run_specRun a specific Cypress test spec file.
Parameters:
spec (required): Path to spec file relative to workspace (e.g., cypress/e2e/login.cy.ts)
browser (optional): Browser to use (chrome, firefox, electron, edge) - default: chrome
headed (optional): Run with visible browser window - default: true
grep (optional): Run only tests matching this pattern (test title filter)
Example:
Run the login test in Chrome with headed modecypress_run_allRun all Cypress tests in a project.
Parameters:
project (required): Project name or path
browser (optional): Browser to use - default: chrome
Example:
Run all tests in the e2e projectcypress_stopStop the currently running Cypress test.
Example:
Stop the current testcypress_statusGet current test execution status with recent output.
Parameters:
outputLines (optional): Number of recent output lines to include - default: 30
Example:
What's the status of the running test?cypress_outputGet the full console output from the current or last test run.
Parameters:
lines (optional): Number of lines to return from the end - default: 100
filter (optional): Filter output to lines containing this text
Example:
Show me the test output filtered for "error"cypress_list_specsList all available Cypress spec files in a project.
Parameters:
project (required): Project name or path
filter (optional): Filter specs by name pattern
Example:
List all spec files in the e2e project containing "login"cypress_screenshotsList or get screenshots from test failures.
Parameters:
project (optional): E2E project name
latest (optional): Get only the most recent screenshot
Example:
Show me the latest screenshot from test failurescypress_clear_artifactsClear screenshots and videos from previous test runs.
Parameters:
project (required): Project name to clear artifacts from
Example:
Clear all test artifacts from the e2e projectThe server exposes these resources that can be read by AI agents:
cypress://output/liveReal-time console output from running Cypress tests.
MIME Type: text/plain
cypress://statusCurrent test execution status (JSON format).
MIME Type: application/json
Response Structure:
{
"isRunning": true,
"currentSpec": "cypress/e2e/login.cy.ts",
"startTime": "2024-01-25T10:30:00.000Z",
"lastExitCode": null,
"outputLines": 42
}User: "Run the login test in Chrome"
AI Agent:
Calls cypress_list_specs to find available tests
Calls cypress_run_spec with spec: "cypress/e2e/login.cy.ts"
Reports test has started
User: "Check the status of the current test"
AI Agent:
Calls cypress_status
Returns formatted status with recent output
User: "Show me why the test failed"
AI Agent:
Calls cypress_output with filter: "error"
Calls cypress_screenshots with latest: true
Provides error output and screenshot location
User: "Run only the authentication tests in Firefox"
AI Agent:
Calls cypress_run_spec with:
spec: "cypress/e2e/auth.cy.ts"
browser: "firefox"
grep: "authentication"
cypress-mcp-server/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript (generated)
├── .gitignore # Git ignore rules
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── README.md # This file
├── LICENSE # MIT License
└── SETUP.md # Detailed setup guidenpm run devThis uses ts-node to run TypeScript directly without compilation.
npm run buildnpm startnpm testSolution: Ensure Cypress is installed in your workspace:
cd /path/to/your/cypress/project
npm install cypress --save-devSolution: On Unix systems, make sure the script is executable:
chmod +x dist/index.jsSolution: Check the following:
Verify CYPRESS_WORKSPACE environment variable is set correctly
Ensure the workspace path exists and contains Cypress config
Check that Node.js version is >= 18.0.0
Review server logs in your MCP client
Solution: Reinstall dependencies:
rm -rf node_modules package-lock.json
npm install
npm run buildContributions are welcome! Please follow these steps:
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
Use TypeScript strict mode
Follow existing code formatting
Add comments for complex logic
Update documentation for new features
This project is licensed under the MIT License - see the LICENSE file for details.
Built with Model Context Protocol SDK
Designed for Cypress test automation
Inspired by the need for AI-assisted testing workflows
If you encounter issues or have questions:
Check the Troubleshooting section
Search existing issues
Create a new issue with details
Support for Cypress component testing
Integration with CI/CD pipelines
Test report generation
Custom assertion helpers
Multi-project support
Video streaming for live test viewing
Test code generation from natural language
Made with ❤️ for the testing community
Clear screenshots and videos from previous test runs
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Which e2e project to clear artifacts from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It clearly indicates a destructive action ('Clear') and scopes what is affected ('screenshots and videos from previous test runs'). However, it does not warn that the action is irreversible or describe any side effects beyond deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundant phrasing. It efficiently communicates the action and target, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is largely sufficient: it names the action, the artifact types, the timing scope, and the required project parameter. It falls short only in not providing explicit usage context or alternative routing, which is a minor gap for such a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single 'project' parameter with 100% coverage. The tool description adds no additional meaning about the parameter beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Clear') and a specific resource ('screenshots and videos from previous test runs'), making the tool's function immediately obvious. It distinguishes itself clearly from sibling tools like cypress_screenshots (which likely retrieves artifacts) and the run-based tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or typical invocation contexts. The phrase 'previous test runs' implies cleanup before fresh runs, but no explicit when/when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available Cypress spec files in a project
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter specs by name pattern | |
| project | Yes | Which e2e project to list specs from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It states the core action and scope, and 'list' implies a read-only operation, but it does not explicitly confirm absence of side effects, describe return format, or note behavior when the project is invalid. This is adequate for a simple listing tool but still leaves operational ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly written sentence with no filler. It is front-loaded and conveys the essential purpose immediately; every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a low-complexity, two-parameter tool, the description is minimally sufficient. However, with no output schema and no annotations, it does not describe the return shape or error behavior, and the filter parameter's effect on 'all available' is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters with 100% coverage. The description adds little beyond restating 'project' and generically 'all available'; it does not clarify how the optional filter affects results or what 'available' means in terms of discovery.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('Cypress spec files') with a clear scope ('in a project'). This clearly distinguishes it from sibling tools that run, stop, or check status of Cypress tests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as cypress_run_spec or cypress_run_all. It does not state exclusions, prerequisites, or typical invocation context; the only usage signal is implicit in the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full console output from the current or last test run
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | Number of lines to return from the end (default: 100) | |
| filter | No | Filter output to lines containing this text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. 'Get' implies a read-only operation and 'full console output' describes what is returned, but it does not clarify behavior when no test run exists, whether output is streamed or buffered, or whether retrieving output has side effects. Basic behavior is present but not deeply disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the core purpose, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and no output schema, the description covers the essential context: what is retrieved and from when. It would benefit from noting the output format or behavior when no run output is available, but nothing critical is missing for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters with meaningful descriptions ('lines' and 'filter'). The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('full console output'), and a clear temporal scope ('current or last test run'). It also differentiates from sibling tools like cypress_status or cypress_screenshots by focusing on console output rather than status or artifacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the tool retrieves output from the current or last test run, which implies it is useful after or during a Cypress run. It does not explicitly name alternatives or exclusions, but the temporal context is unambiguous enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run all Cypress tests in a project
| Name | Required | Description | Default |
|---|---|---|---|
| browser | No | Browser to use (default: chrome) | |
| project | Yes | Which e2e project to run (adjust based on your project structure) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries full burden of behavioral disclosure. It only states the operation with no note on side effects, async behavior, artifacts, or safety. For a test runner that may spawn long-running processes, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word earns its place and the core function is immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should cover what happens after invocation—return value, async vs blocking behavior, and relation to cypress_status/stop. It doesn't, so an agent may not know how to monitor or stop the run.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3 applies. Tool description adds no extra meaning beyond the schema, but the schema's project and browser descriptions are sufficient for selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Run' and resource 'all Cypress tests', clearly distinguishing it from sibling cypress_run_spec which targets a single spec. The phrase 'in a project' scopes the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to choose this tool over cypress_run_spec, status, or stop. The function implies it is for executing the full suite, but it doesn't state conditions, exclusions, or alternatives, leaving some inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a specific Cypress test spec file. Returns immediately and runs in background.
| Name | Required | Description | Default |
|---|---|---|---|
| grep | No | Run only tests matching this pattern (test title grep) | |
| spec | Yes | Path to spec file relative to workspace (e.g., cypress/e2e/example.cy.ts) | |
| headed | No | Run with visible browser window (default: true for debugging) | |
| browser | No | Browser to use (default: chrome) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It does disclose a key behavior: "Returns immediately and runs in background." However, it omits other useful behavioral context such as side effects (artifacts/screenshots), how completion is signaled, and how results can be retrieved through sibling tools. The provided behavior is helpful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It communicates both the core purpose and the key background-execution behavior in just a few words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for initiating a run against a given spec path, and the async behavior is mentioned. However, with no output schema and no mention of how to check status or retrieve results, an agent is left without some context needed for a fully informed invocation. It covers the essentials but not the surrounding workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully documents all four parameters. The description itself adds no parameter-level details beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ("Run") and resource ("a specific Cypress test spec file"), and the word "specific" distinguishes it from the sibling cypress_run_all. This gives an agent a clear, unambiguous understanding of what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for running a single spec file rather than all specs, and the background-execution note hints at non-blocking use. However, it does not explicitly name alternatives like cypress_run_all, cypress_status, or cypress_output, nor does it explain when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List or get screenshots from test failures
| Name | Required | Description | Default |
|---|---|---|---|
| latest | No | Get only the most recent screenshot | |
| project | No | E2E project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, whether it accesses local files or a remote artifact store, what happens when there are no screenshots, or whether 'latest' affects the behavior beyond the schema description. The description provides minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler or redundancy. It front-loads the main action and resource immediately. While it is quite terse, every word contributes to the core purpose, which fits the conciseness criterion, even though the substance is limited.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should at least indicate what the tool returns, such as file paths, image data, or a list of artifact locations. It also does not clarify whether 'project' is required, what happens when no screenshots exist, or how 'latest' interacts with the listing behavior. The description is too sparse for an agent to call this tool confidently in a non-obvious scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented in the schema. The tool description adds only the 'test failures' context, which relates to both parameters but does not meaningfully enhance understanding of 'latest' or 'project'. The baseline of 3 is appropriate because the schema already carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List or get') and resource ('screenshots from test failures'), which clearly identifies the tool's domain and distinguishes it from siblings like cypress_output or cypress_list_specs. It is not a tautology and gives the agent a usable idea of what the tool does, though 'List or get' is slightly ambiguous about whether these are two modes or two operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'from test failures' implies the tool is appropriate when the agent needs screenshots generated by failed tests, giving some usage context. However, it does not explicitly state when to prefer this tool over related siblings like cypress_output or cypress_clear_artifacts, nor does it provide any when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current test execution status, including if tests are running and recent output
| Name | Required | Description | Default |
|---|---|---|---|
| outputLines | No | Number of recent output lines to include (default: 30) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool returns status and recent output, without mentioning whether it is purely read-only, how the output is structured, or any side effects. This is minimal disclosure for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and key included information. It is front-loaded with the primary action and adds no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity tool with one optional parameter and no output schema. The description gives a high-level idea of what is returned, but lacks detail on the response format or specific status values. It is adequate for a simple status check but leaves some ambiguity around return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the outputLines parameter is already fully documented in the schema. The description adds no additional meaning about the parameter, but the schema carries that weight, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a status query ('Get current test execution status') and specifies what it covers ('if tests are running and recent output'). It is distinguishable from execution-oriented siblings like cypress_run_all and cypress_stop, though it overlaps somewhat with cypress_output since it also returns recent output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. The overlap with cypress_output is not addressed, and there are no stated conditions for choosing status over other siblings. Usage context is only implied by the word 'status'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop the currently running Cypress test
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the behavioral disclosure burden. It clarifies that the action is stopping a running test but does not disclose side effects such as whether artifacts are affected, whether the operation is idempotent, or what happens when no test is running.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single clear sentence that immediately states the action and target. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter command, this description is largely enough to know what it does, but it omits edge-case behavior and any return value expectations. Since there is no output schema or annotations, additional detail on what happens when no test is running would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the empty input schema already covers everything. The description adds no extra parameter semantics, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('stop') and a clear resource ('currently running Cypress test'). This differentiates it from sibling tools like cypress_run_spec, cypress_run_all, and cypress_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the condition for use—that a test is currently running—but provides no explicit guidance on when to use it over alternatives or what to do if no test is running. This is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0cypress_clear_artifactscypress_list_specscypress_outputcypress_run_allcypress_run_speccypress_screenshotscypress_statuscypress_stopScored across 8 tools
Each tool targets a distinct part of the Cypress workflow: running, stopping, checking status, getting output, listing specs, and managing artifacts. Status and output overlap slightly since status mentions recent output, but their intended separation is clear.
All tools share the cypress_ prefix and mostly follow a verb_noun pattern like cypress_run_spec and cypress_list_specs. cypress_status and cypress_output are noun-oriented rather than verb-oriented, but the overall pattern remains predictable.
Eight tools is well-scoped for a Cypress runner server. Each tool covers a necessary part of the execution lifecycle without redundancy or bloat.
The surface covers running specs, running all tests, stopping, checking status, retrieving output, listing specs, and managing failure artifacts. Minor gaps exist around detailed result reporting or video retrieval, but core workflows are fully supported.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Give your AI agents the tools to build, manage, and run automation workflows.
Agentic testing: HyperExecute jobs, test failure triage, SmartUI visual diffs, a11y audits
