@shiplightai/mcp2 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/README.md +128 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +5221 -0
- package/dist/index.js.map +1 -0
- package/package.json +36 -0
package/README.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# @shiplightai/mcp2
|
|
2
|
+
|
|
3
|
+
MCP server for browser UI exploration. Provides tools to launch browser sessions, navigate pages, inspect the DOM, perform actions, and collect locators — designed for coding agents that explore UI then write Playwright tests with [`@shiplightai/sdk`](https://www.npmjs.com/package/@shiplightai/sdk).
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @shiplightai/mcp2
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
### Claude Code
|
|
14
|
+
|
|
15
|
+
Add to your Claude Code MCP config (`~/.claude/settings.json`):
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"mcpServers": {
|
|
20
|
+
"shiplight": {
|
|
21
|
+
"command": "shiplight-mcp2"
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Claude Desktop
|
|
28
|
+
|
|
29
|
+
Add to your Claude Desktop config:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"shiplight": {
|
|
35
|
+
"command": "npx",
|
|
36
|
+
"args": ["-y", "@shiplightai/mcp2"]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Cursor / Windsurf
|
|
43
|
+
|
|
44
|
+
Add to your MCP config (`.cursor/mcp.json` or equivalent):
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"shiplight": {
|
|
50
|
+
"command": "npx",
|
|
51
|
+
"args": ["-y", "@shiplightai/mcp2"]
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Tools
|
|
58
|
+
|
|
59
|
+
### Session Management (5)
|
|
60
|
+
|
|
61
|
+
| Tool | Description |
|
|
62
|
+
|------|-------------|
|
|
63
|
+
| `new_session` | Launch a browser session with optional device emulation |
|
|
64
|
+
| `save_storage_state` | Save cookies/localStorage for session reuse |
|
|
65
|
+
| `close_session` | Close a browser session |
|
|
66
|
+
| `close_all` | Close all browser sessions |
|
|
67
|
+
| `get_session_state` | Get current URL and session type |
|
|
68
|
+
|
|
69
|
+
### Browser Interaction (7)
|
|
70
|
+
|
|
71
|
+
| Tool | Description |
|
|
72
|
+
|------|-------------|
|
|
73
|
+
| `navigate` | Navigate to a URL |
|
|
74
|
+
| `get_page_info` | Get page URL and title (lightweight) |
|
|
75
|
+
| `inspect_page` | Screenshot + DOM with element indices |
|
|
76
|
+
| `act` | Perform browser actions using element indices |
|
|
77
|
+
| `get_locator` | Extract Playwright locator for an element |
|
|
78
|
+
| `update_variables` | Set session variables for browser tasks |
|
|
79
|
+
| `clear_execution_history` | Clear action history for a session |
|
|
80
|
+
|
|
81
|
+
### Debug (4)
|
|
82
|
+
|
|
83
|
+
| Tool | Description |
|
|
84
|
+
|------|-------------|
|
|
85
|
+
| `get_browser_console_logs` | Get console logs (errors, warnings) |
|
|
86
|
+
| `get_browser_network_logs` | Get network request logs |
|
|
87
|
+
| `clear_logs` | Clear console and network logs |
|
|
88
|
+
| `get_artifact` | Retrieve screenshots or DOM snapshots |
|
|
89
|
+
|
|
90
|
+
## Resources
|
|
91
|
+
|
|
92
|
+
The server exposes two resources for coding agents:
|
|
93
|
+
|
|
94
|
+
- **`shiplight://schemas/action-entity`** — Parameter docs for all browser actions
|
|
95
|
+
- **`shiplight://docs/agent-sdk`** — API documentation for `@shiplightai/sdk`, including a workflow guide for turning UI exploration into test code
|
|
96
|
+
|
|
97
|
+
## Workflow
|
|
98
|
+
|
|
99
|
+
1. **Explore** — Use `inspect_page` + `act` to navigate the app
|
|
100
|
+
2. **Collect locators** — Use `get_locator` on elements you want to test
|
|
101
|
+
3. **Write tests** — Use the locators in Playwright tests, with `@shiplightai/sdk` for AI-powered assertions and self-healing
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
import { test, expect } from '@playwright/test';
|
|
105
|
+
import { createAgent, configureSdk } from '@shiplightai/sdk';
|
|
106
|
+
|
|
107
|
+
configureSdk({ env: { GOOGLE_API_KEY: process.env.GOOGLE_API_KEY! } });
|
|
108
|
+
|
|
109
|
+
test('checkout flow', async ({ page }) => {
|
|
110
|
+
const agent = createAgent({ model: 'gemini-2.5-pro' });
|
|
111
|
+
|
|
112
|
+
await page.goto('https://myshop.example.com');
|
|
113
|
+
await page.getByRole('button', { name: 'Add to Cart' }).click();
|
|
114
|
+
await agent.assert(page, 'Item was added to cart');
|
|
115
|
+
await agent.run(page, 'Complete checkout with test data');
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Environment Variables
|
|
120
|
+
|
|
121
|
+
| Variable | Default | Description |
|
|
122
|
+
|----------|---------|-------------|
|
|
123
|
+
| `WEB_AGENT_MODEL` | `gemini-2.5-pro` | AI model for browser agent |
|
|
124
|
+
| `TERMINATION_TIMEOUT` | (none) | Session auto-close timeout in ms |
|
|
125
|
+
|
|
126
|
+
## License
|
|
127
|
+
|
|
128
|
+
MIT
|
package/dist/index.d.ts
ADDED