336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
# Current Specification
|
|
|
|
**Status**: 🔧 IN PROGRESS - Playwright MCP Server Initialization Fix
|
|
**Last Updated**: 2026-01-11
|
|
**Previous Work**: Staticcheck Pre-Commit Integration (COMPLETE - Archived)
|
|
|
|
---
|
|
|
|
## Active Project: Playwright MCP Server Initialization Failure
|
|
|
|
**Priority:** 🔴 HIGH
|
|
**Reported:** VS Code MCP Server Error Logs (Exit Code 1)
|
|
**Critical Requirement:** Configure VS Code MCP to properly start Playwright server without exit errors
|
|
|
|
### Problem Statement
|
|
|
|
The Playwright MCP server is failing to initialize with exit code 1. Error logs show:
|
|
```
|
|
2026-01-11 00:35:54.254 [info] Connection state: Error Process exited with code 1
|
|
```
|
|
|
|
The server outputs the Playwright help menu instead of starting properly, indicating it's not receiving proper configuration or arguments when launched by VS Code's MCP system.
|
|
|
|
### Root Cause
|
|
|
|
Investigation revealed the VS Code MCP configuration file is **empty** (0 bytes):
|
|
- **Location**: `/root/.config/Code - Insiders/User/mcp.json`
|
|
- **Size**: 0 bytes (created Dec 12 14:48)
|
|
- **Impact**: Without valid JSON configuration, VS Code cannot properly invoke the Playwright MCP server
|
|
- **Current Behavior**: Server receives invalid/missing arguments → shows help → exits with code 1
|
|
|
|
### Solution Approach
|
|
|
|
Create a properly formatted MCP configuration file that tells VS Code how to start the Playwright MCP server with correct arguments, working directory, and environment variables
|
|
|
|
### Solution Approach
|
|
|
|
Create a properly formatted MCP configuration file that tells VS Code how to start the Playwright MCP server with correct arguments, working directory, and environment variables.
|
|
|
|
### Implementation Plan
|
|
|
|
#### Phase 1: Create MCP Configuration File
|
|
|
|
**File**: `/root/.config/Code - Insiders/User/mcp.json` (currently empty)
|
|
|
|
**Task 1.1**: Write valid JSON configuration
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"playwright-test": {
|
|
"command": "npx",
|
|
"args": [
|
|
"playwright",
|
|
"run-test-mcp-server",
|
|
"--config",
|
|
"playwright.config.js",
|
|
"--headless"
|
|
],
|
|
"env": {
|
|
"NODE_ENV": "test",
|
|
"CI": "false"
|
|
}
|
|
},
|
|
"playwright-browser": {
|
|
"command": "npx",
|
|
"args": [
|
|
"playwright",
|
|
"run-mcp-server",
|
|
"--browser",
|
|
"chromium",
|
|
"--headless"
|
|
],
|
|
"env": {
|
|
"NODE_ENV": "development"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Task 1.2**: Validate JSON syntax
|
|
- Command: `cat /root/.config/Code\ -\ Insiders/User/mcp.json | jq .`
|
|
- Expected: Valid JSON parsing (no errors)
|
|
|
|
**Task 1.3**: Verify file permissions
|
|
- Command: `ls -lah /root/.config/Code\ -\ Insiders/User/mcp.json`
|
|
- Expected: `-rw-r--r--` permissions, size > 0 bytes
|
|
|
|
#### Phase 2: Verify Playwright Dependencies
|
|
|
|
**Task 2.1**: Confirm Playwright installation
|
|
- Command: `npx playwright --version`
|
|
- Expected: `Version 1.57.0`
|
|
- Current Status: ✅ VERIFIED
|
|
|
|
**Task 2.2**: Install browser binaries (if needed)
|
|
- Command: `cd /projects/Charon && npx playwright install chromium`
|
|
- Expected: "chromium downloaded successfully" or "chromium is already installed"
|
|
|
|
**Task 2.3**: Verify Playwright config exists
|
|
- File: `/projects/Charon/playwright.config.js`
|
|
- Current Status: ✅ EXISTS (valid configuration)
|
|
|
|
#### Phase 3: Test MCP Server Startup (Manual)
|
|
|
|
**Task 3.1**: Test server command directly
|
|
- Command: `cd /projects/Charon && npx playwright run-test-mcp-server --config playwright.config.js --headless`
|
|
- Expected: Server starts and waits (no immediate exit)
|
|
- Expected: No help menu displayed
|
|
- Terminate: Press Ctrl+C to stop
|
|
|
|
**Task 3.2**: Verify process persistence
|
|
- Command: `ps aux | grep playwright`
|
|
- Expected: Process running while server is active
|
|
- Expected: No immediate exit after startup
|
|
|
|
#### Phase 4: Reload VS Code
|
|
|
|
**Task 4.1**: Reload window
|
|
- Action: Command Palette → "Developer: Reload Window"
|
|
- Rationale: VS Code reads MCP configuration at startup
|
|
|
|
**Alternative**: Restart VS Code completely
|
|
|
|
#### Phase 5: Verify MCP Server Connection
|
|
|
|
**Task 5.1**: Check VS Code Output panel
|
|
- View → Output → Select "MCP Servers" or "Playwright"
|
|
- Expected: Connection success message
|
|
- Expected: No "exit code 1" errors
|
|
|
|
**Task 5.2**: Verify server status
|
|
- Check: MCP server connection state in VS Code status bar
|
|
- Expected: "Connected" (not "Error")
|
|
|
|
**Task 5.3**: Test Playwright MCP tools
|
|
- Open: Copilot Chat
|
|
- Try: Playwright-related commands or tools
|
|
- Expected: Tools accessible and functional
|
|
|
|
### Success Criteria (Definition of Done)
|
|
|
|
1. [ ] `/root/.config/Code - Insiders/User/mcp.json` contains valid JSON (not empty)
|
|
2. [ ] `mcp.json` has `mcpServers` key with at least one Playwright server definition
|
|
3. [ ] File size > 0 bytes (verified with `ls -lah`)
|
|
4. [ ] JSON is valid (verified with `jq`)
|
|
5. [ ] Playwright version is 1.57.0 (verified with `npx playwright --version`)
|
|
6. [ ] Chromium browser binary is installed
|
|
7. [ ] Manual server start works: `npx playwright run-test-mcp-server --config playwright.config.js`
|
|
8. [ ] Server persists when started (doesn't exit immediately)
|
|
9. [ ] VS Code window has been reloaded after creating `mcp.json`
|
|
10. [ ] No "exit code 1" errors in VS Code MCP server logs
|
|
11. [ ] MCP server connection state is "Connected" (not "Error")
|
|
12. [ ] Playwright MCP tools are accessible in Copilot Chat
|
|
|
|
### Configuration Details
|
|
|
|
#### MCP Server Types
|
|
|
|
Two server configurations are recommended:
|
|
|
|
1. **playwright-test** (Primary - For Testing)
|
|
- Command: `npx playwright run-test-mcp-server`
|
|
- Uses: Project's `playwright.config.js`
|
|
- Mode: Headless
|
|
- Purpose: Test runner interactions, E2E test execution
|
|
|
|
2. **playwright-browser** (Secondary - For Browser Automation)
|
|
- Command: `npx playwright run-mcp-server`
|
|
- Browser: Chromium
|
|
- Mode: Headless
|
|
- Purpose: Direct browser automation tasks
|
|
|
|
#### Environment Variables
|
|
|
|
- **NODE_ENV**: Set to "test" for test server, "development" for browser server
|
|
- **CI**: Set to "false" to ensure interactive features work
|
|
|
|
#### Command Arguments
|
|
|
|
- `--config playwright.config.js`: Points to project's Playwright configuration
|
|
- `--headless`: Runs browser without GUI (required for server environments)
|
|
- `--browser chromium`: Specifies browser type for browser MCP server
|
|
|
|
### Verification Commands
|
|
|
|
```bash
|
|
# Check file exists and size
|
|
ls -lah /root/.config/Code\ -\ Insiders/User/mcp.json
|
|
|
|
# Validate JSON syntax
|
|
cat /root/.config/Code\ -\ Insiders/User/mcp.json | jq .
|
|
|
|
# Verify Playwright version
|
|
npx playwright --version
|
|
|
|
# Test manual server startup
|
|
cd /projects/Charon && npx playwright run-test-mcp-server --config playwright.config.js --headless
|
|
|
|
# Check running processes
|
|
ps aux | grep playwright
|
|
```
|
|
|
|
### Common Pitfalls to Avoid
|
|
|
|
1. **Invalid JSON**: No trailing commas, proper quote escaping
|
|
2. **Wrong Command Path**: Use `npx` not absolute paths
|
|
3. **Missing Config Reference**: Always specify `--config playwright.config.js`
|
|
4. **Forget to Reload**: VS Code must reload after config changes
|
|
5. **Browser Not Installed**: Run `npx playwright install chromium`
|
|
|
|
### Troubleshooting Guide
|
|
|
|
#### Issue: "Command not found"
|
|
**Solution**: `cd /projects/Charon && npm install`
|
|
|
|
#### Issue: "Browser not installed"
|
|
**Solution**: `npx playwright install --with-deps chromium`
|
|
|
|
#### Issue: Server still exits with code 1
|
|
**Diagnosis**:
|
|
```bash
|
|
# Check JSON validity
|
|
cat /root/.config/Code\ -\ Insiders/User/mcp.json | jq .
|
|
# If error: Fix JSON syntax errors
|
|
```
|
|
|
|
#### Issue: VS Code doesn't recognize config
|
|
**Solution**:
|
|
1. Verify file location is exact: `/root/.config/Code - Insiders/User/mcp.json`
|
|
2. Reload VS Code: Command Palette → "Developer: Reload Window"
|
|
3. Check Output panel for MCP logs
|
|
|
|
### Expected Outcomes
|
|
|
|
After successful implementation:
|
|
|
|
- ✅ Playwright MCP Server Status: **Running**
|
|
- ✅ Connection State: **Connected** (not Error)
|
|
- ✅ Exit Code: N/A (server persists)
|
|
- ✅ Available Tools: Playwright test execution, browser automation
|
|
- ✅ Copilot Integration: Playwright commands work in chat
|
|
|
|
### Performance Benchmarks
|
|
|
|
- **File Size**: ~400 bytes (minimal JSON config)
|
|
- **Startup Time**: < 5 seconds for server to be ready
|
|
- **Memory Usage**: ~50-100 MB per MCP server instance
|
|
- **Configuration Reload**: < 2 seconds after VS Code reload
|
|
|
|
### Risk Assessment
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| Invalid JSON syntax | HIGH | Use `jq` to validate before reload |
|
|
| Browser binaries missing | MEDIUM | Run `npx playwright install` first |
|
|
| VS Code doesn't reload config | LOW | Explicitly reload window via Command Palette |
|
|
| Wrong file path | HIGH | Double-check path matches VS Code Insiders location |
|
|
| Playwright not installed | MEDIUM | Verify with `npx playwright --version` |
|
|
|
|
### Implementation Timeline
|
|
|
|
1. **Create mcp.json**: 2 minutes
|
|
2. **Verify Playwright installation**: 2 minutes
|
|
3. **Test server startup**: 3 minutes
|
|
4. **Reload VS Code**: 1 minute
|
|
5. **Verify connection**: 2 minutes
|
|
|
|
**Total Estimated Time**: 10 minutes
|
|
|
|
### References
|
|
|
|
- **Playwright Documentation**: https://playwright.dev/docs/intro
|
|
- **Playwright MCP Commands**: /projects/Charon/node_modules/playwright/lib/program.js (lines 149-159)
|
|
- **VS Code MCP Configuration**: https://code.visualstudio.com/docs/copilot/customization
|
|
- **Project Playwright Config**: /projects/Charon/playwright.config.js
|
|
- **MCP Server Discovery**: Investigated node_modules/playwright/lib/mcp/ directory
|
|
- **Agent Instructions Reference**: .github/instructions/agents.instructions.md (lines 544-624)
|
|
|
|
### Next Steps
|
|
|
|
1. **Immediate**: Create `mcp.json` with recommended configuration
|
|
2. **Verify**: Test manual server startup to ensure it works
|
|
3. **Reload**: Restart VS Code to apply changes
|
|
4. **Validate**: Check MCP server connection status in Output panel
|
|
5. **Test**: Use Playwright MCP tools in Copilot Chat to confirm integration
|
|
|
|
---
|
|
|
|
## Alternative Configurations
|
|
|
|
### Minimal Configuration (Single Server)
|
|
|
|
If only one server is needed:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"playwright": {
|
|
"command": "npx",
|
|
"args": ["playwright", "run-test-mcp-server"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Advanced Configuration (Custom Port)
|
|
|
|
For specific port binding:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"playwright": {
|
|
"command": "npx",
|
|
"args": [
|
|
"playwright",
|
|
"run-test-mcp-server",
|
|
"--config",
|
|
"playwright.config.js",
|
|
"--port",
|
|
"9323",
|
|
"--host",
|
|
"localhost"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
**Plan Complete - Ready for Implementation**
|
|
|
|
**Note**: This specification follows [Spec-Driven Workflow v1](.github/instructions/spec-driven-workflow-v1.instructions.md) format.
|