cypress-mcp 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +75 -0
- package/README.md +180 -0
- package/bin/cypress-mcp.mjs +3 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +1972 -0
- package/dist/index.js.map +1 -0
- package/package.json +78 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
Business Source License 1.1
|
|
2
|
+
|
|
3
|
+
Parameters
|
|
4
|
+
|
|
5
|
+
Licensor: JADEV GROUP SARL (BE1027.114.687)
|
|
6
|
+
Rue du Laekenved 7, 1080 Bruxelles, Belgique
|
|
7
|
+
Licensed Work: cypress-mcp 0.1.0
|
|
8
|
+
The Licensed Work is (c) 2026 JADEV GROUP SARL.
|
|
9
|
+
Additional Use Grant: You may make use of the Licensed Work, provided that
|
|
10
|
+
you do not use the Licensed Work for a Commercial
|
|
11
|
+
Production Purpose.
|
|
12
|
+
|
|
13
|
+
A "Commercial Production Purpose" means use of the
|
|
14
|
+
Licensed Work in a production environment within a
|
|
15
|
+
for-profit organization or as part of a commercial
|
|
16
|
+
product or service. The following uses are expressly
|
|
17
|
+
permitted without a commercial license:
|
|
18
|
+
|
|
19
|
+
- Individual use (personal projects, learning, research)
|
|
20
|
+
- Academic and educational use
|
|
21
|
+
- Open source projects (under OSI-approved licenses)
|
|
22
|
+
- Evaluation and testing (non-production)
|
|
23
|
+
- Non-profit organizations
|
|
24
|
+
|
|
25
|
+
Change Date: 2029-03-25
|
|
26
|
+
Change License: Apache License, Version 2.0
|
|
27
|
+
|
|
28
|
+
For information about alternative licensing arrangements for the Licensed Work,
|
|
29
|
+
please contact: info@jadev-group.com | +32 474 33 92 71
|
|
30
|
+
|
|
31
|
+
Notice
|
|
32
|
+
|
|
33
|
+
Business Source License 1.1 (BUSL-1.1)
|
|
34
|
+
|
|
35
|
+
Terms
|
|
36
|
+
|
|
37
|
+
The Licensor hereby grants you the right to copy, modify, create derivative
|
|
38
|
+
works, redistribute, and make non-production use of the Licensed Work. The
|
|
39
|
+
Licensor may make an Additional Use Grant, above, permitting limited production
|
|
40
|
+
use.
|
|
41
|
+
|
|
42
|
+
Effective on the Change Date, or the fourth anniversary of the first publicly
|
|
43
|
+
available distribution of a specific version of the Licensed Work under this
|
|
44
|
+
License, whichever comes first, the Licensor hereby grants you rights under
|
|
45
|
+
the terms of the Change License, and the rights granted in the paragraph
|
|
46
|
+
above terminate.
|
|
47
|
+
|
|
48
|
+
If your use of the Licensed Work does not comply with the requirements
|
|
49
|
+
currently in effect as described in this License, you must purchase a
|
|
50
|
+
commercial license from the Licensor, its affiliated entities, or authorized
|
|
51
|
+
resellers, or you must refrain from using the Licensed Work.
|
|
52
|
+
|
|
53
|
+
All copies of the original and modified Licensed Work, and derivative works
|
|
54
|
+
of the Licensed Work, are subject to this License. This License applies
|
|
55
|
+
separately for each version of the Licensed Work and the Change Date may vary
|
|
56
|
+
for each version of the Licensed Work released by Licensor.
|
|
57
|
+
|
|
58
|
+
You must conspicuously display this License on each original or modified copy
|
|
59
|
+
of the Licensed Work. If you receive the Licensed Work in original or
|
|
60
|
+
modified form from a third party, the terms and conditions set forth in this
|
|
61
|
+
License apply to your use of that work.
|
|
62
|
+
|
|
63
|
+
Any use of the Licensed Work in violation of this License will automatically
|
|
64
|
+
terminate your rights under this License for the current and all other
|
|
65
|
+
versions of the Licensed Work.
|
|
66
|
+
|
|
67
|
+
This License does not grant you any right in any trademark or logo of
|
|
68
|
+
Licensor or its affiliates (provided that you may use a trademark or logo of
|
|
69
|
+
Licensor as expressly required by this License).
|
|
70
|
+
|
|
71
|
+
TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
|
|
72
|
+
AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
|
|
73
|
+
EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
|
|
74
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
|
|
75
|
+
TITLE.
|
package/README.md
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# cypress-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/cypress-mcp)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://github.com/jams4code/cypress-mcp/actions/workflows/ci.yml)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
|
|
8
|
+
MCP server that gives AI coding agents full control over Cypress test execution.
|
|
9
|
+
|
|
10
|
+
Run, debug, and iterate on E2E tests directly from Claude Code, Cursor, Windsurf, or any MCP-compatible agent — without switching to a terminal.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
| Package Manager | Command |
|
|
15
|
+
|----------------|---------|
|
|
16
|
+
| **npx** (no install) | `npx cypress-mcp --cwd /path/to/project` |
|
|
17
|
+
| **npm** | `npm install -g cypress-mcp` |
|
|
18
|
+
| **pnpm** | `pnpm add -g cypress-mcp` |
|
|
19
|
+
| **yarn** | `yarn global add cypress-mcp` |
|
|
20
|
+
| **bun** | `bun add -g cypress-mcp` |
|
|
21
|
+
| **From GitHub** | `npx github:jams4code/cypress-mcp` |
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
Register with your MCP client:
|
|
26
|
+
|
|
27
|
+
**Claude Code:**
|
|
28
|
+
```bash
|
|
29
|
+
claude mcp add cypress-mcp -- npx cypress-mcp --cwd /path/to/project
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**Cursor / VS Code:**
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"mcpServers": {
|
|
36
|
+
"cypress": {
|
|
37
|
+
"command": "npx",
|
|
38
|
+
"args": ["cypress-mcp", "--cwd", "/path/to/your/project"]
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
**Windsurf:**
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"mcpServers": {
|
|
48
|
+
"cypress": {
|
|
49
|
+
"command": "npx",
|
|
50
|
+
"args": ["cypress-mcp", "--cwd", "/path/to/your/project"]
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Why
|
|
57
|
+
|
|
58
|
+
AI agents can write Cypress tests but can't run them. Every change requires you to switch to terminal, run `npx cypress run`, wait, copy the output back. This kills iteration speed.
|
|
59
|
+
|
|
60
|
+
**cypress-mcp** closes the loop. The agent runs specs, reads failures, views screenshots, inspects crash context, reruns the last command, and discovers the test suite — all within the conversation.
|
|
61
|
+
|
|
62
|
+
## Tools (11)
|
|
63
|
+
|
|
64
|
+
### Core Loop
|
|
65
|
+
|
|
66
|
+
| Tool | What it does |
|
|
67
|
+
|------|-------------|
|
|
68
|
+
| `cypress_run_spec` | Run a spec file headless, get structured JSON results |
|
|
69
|
+
| `cypress_run_test` | Run a single test by name (grep filter) |
|
|
70
|
+
| `cypress_rerun_last` | Replay the exact last run without rebuilding arguments |
|
|
71
|
+
| `cypress_list_specs` | List all spec files with test counts |
|
|
72
|
+
|
|
73
|
+
### Debug
|
|
74
|
+
|
|
75
|
+
| Tool | What it does |
|
|
76
|
+
|------|-------------|
|
|
77
|
+
| `cypress_get_failure_context` | Compact debugging bundle: error, stack, spec excerpt, screenshots, next actions |
|
|
78
|
+
| `cypress_get_screenshot` | Find failure screenshots by spec or test name |
|
|
79
|
+
| `cypress_get_last_run` | Full results of the most recent run |
|
|
80
|
+
|
|
81
|
+
### Discovery
|
|
82
|
+
|
|
83
|
+
| Tool | What it does |
|
|
84
|
+
|------|-------------|
|
|
85
|
+
| `cypress_discover` | Map the entire test suite: specs, test names, counts |
|
|
86
|
+
| `cypress_analyze_spec` | Deep-parse a spec: describe blocks, visits, intercepts, fixtures |
|
|
87
|
+
|
|
88
|
+
### Setup
|
|
89
|
+
|
|
90
|
+
| Tool | What it does |
|
|
91
|
+
|------|-------------|
|
|
92
|
+
| `cypress_get_env` | Show cypress.env.json (secrets masked) |
|
|
93
|
+
| `cypress_doctor` | Health check: config, binary, specs, support file, directories |
|
|
94
|
+
|
|
95
|
+
## How It Works
|
|
96
|
+
|
|
97
|
+
```mermaid
|
|
98
|
+
graph LR
|
|
99
|
+
A[AI Agent] -->|stdio JSON-RPC| B[cypress-mcp]
|
|
100
|
+
B -->|child_process.spawn| C[Cypress Runtime]
|
|
101
|
+
C -->|JSON reporter| B
|
|
102
|
+
B -->|structured result| A
|
|
103
|
+
|
|
104
|
+
style A fill:#1a1a2e,stroke:#e94560,color:#fff
|
|
105
|
+
style B fill:#16213e,stroke:#0f3460,color:#fff
|
|
106
|
+
style C fill:#0f3460,stroke:#533483,color:#fff
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
- **stdio transport** — the agent spawns the server as a child process
|
|
110
|
+
- **Serial execution** — one Cypress run at a time, no concurrency
|
|
111
|
+
- **Structured output** — JSON results with failure details, diffs, screenshot paths
|
|
112
|
+
- **Config-aware** — auto-detects `cypress.config.*`, follows relative imports, respects custom paths
|
|
113
|
+
- **Cross-platform** — Windows, macOS, Linux
|
|
114
|
+
|
|
115
|
+
## Agent Workflow
|
|
116
|
+
|
|
117
|
+
```mermaid
|
|
118
|
+
graph TD
|
|
119
|
+
D[cypress_discover] -->|map test suite| E[cypress_analyze_spec]
|
|
120
|
+
E -->|understand spec| F[cypress_run_spec]
|
|
121
|
+
F -->|tests fail| G[cypress_get_failure_context]
|
|
122
|
+
G -->|error + excerpt + screenshots| H[Fix the code]
|
|
123
|
+
H -->|iterate| I[cypress_rerun_last]
|
|
124
|
+
I -->|still failing| G
|
|
125
|
+
I -->|passing| J[Done]
|
|
126
|
+
F -->|tests pass| J
|
|
127
|
+
|
|
128
|
+
style D fill:#1a1a2e,stroke:#e94560,color:#fff
|
|
129
|
+
style F fill:#16213e,stroke:#0f3460,color:#fff
|
|
130
|
+
style G fill:#e94560,stroke:#fff,color:#fff
|
|
131
|
+
style I fill:#0f3460,stroke:#533483,color:#fff
|
|
132
|
+
style J fill:#2d6a4f,stroke:#40916c,color:#fff
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Configuration
|
|
136
|
+
|
|
137
|
+
Works out of the box for standard Cypress projects. For custom setups, create `cypress-mcp.config.json`:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"defaultBrowser": "chrome",
|
|
142
|
+
"defaultTimeout": 600000,
|
|
143
|
+
"cypressConfigFile": "config/cypress.config.ts",
|
|
144
|
+
"specPattern": ["e2e/**/*.cy.ts"],
|
|
145
|
+
"supportFile": "support/e2e.ts",
|
|
146
|
+
"titleFilterSupport": true,
|
|
147
|
+
"screenshotsDir": "cypress/screenshots"
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Supported Versions
|
|
152
|
+
|
|
153
|
+
- Cypress 12.x — 15.x
|
|
154
|
+
- Node.js 18+
|
|
155
|
+
- Windows, macOS, Linux
|
|
156
|
+
|
|
157
|
+
## Registry Status
|
|
158
|
+
|
|
159
|
+
| Registry | Package | Status |
|
|
160
|
+
|----------|---------|--------|
|
|
161
|
+
| **npm** | [`cypress-mcp`](https://www.npmjs.com/package/cypress-mcp) | Published |
|
|
162
|
+
| **GitHub** | [`jams4code/cypress-mcp`](https://github.com/jams4code/cypress-mcp) | Source |
|
|
163
|
+
|
|
164
|
+
## Development
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
git clone https://github.com/jams4code/cypress-mcp.git
|
|
168
|
+
cd cypress-mcp
|
|
169
|
+
npm install
|
|
170
|
+
npm run build
|
|
171
|
+
npm test
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## License
|
|
175
|
+
|
|
176
|
+
[Business Source License 1.1](LICENSE) — free for individuals, education, and open source. Commercial production use requires a license. See [LICENSING.md](LICENSING.md) for details.
|
|
177
|
+
|
|
178
|
+
Converts to Apache 2.0 on March 25, 2029.
|
|
179
|
+
|
|
180
|
+
Licensed by [JADEV GROUP SARL](https://jadev-group.com) (BE1027.114.687), Brussels, Belgium.
|
package/dist/index.d.ts
ADDED