fix: update golangci-lint entry command and enhance current specification for Playwright MCP server initialization

2026-01-11 06:09:21 +00:00
parent efd8a5d0f3
commit 10902e37a0
2 changed files with 299 additions and 50 deletions
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -33,10 +33,7 @@ repos:
        pass_filenames: false
      - id: golangci-lint-fast
        name: golangci-lint (Fast Linters - BLOCKING)
-        entry: >
-          bash -c 'command -v golangci-lint >/dev/null 2>&1 ||
-          { echo "ERROR: golangci-lint not found. Install: https://golangci-lint.run/usage/install/"; exit 1; };
-          cd backend && golangci-lint run --config .golangci-fast.yml ./...'
+        entry: bash -c 'command -v golangci-lint >/dev/null 2>&1 || (echo "ERROR golangci-lint not found. Install at https://golangci-lint.run/usage/install/" && exit 1); cd backend && golangci-lint run --config .golangci-fast.yml ./...'
        language: system
        files: '\.go$'
        exclude: '_test\.go$'
--- a/docs/plans/current_spec.md
+++ b/docs/plans/current_spec.md
@@ -1,83 +1,335 @@
 # Current Specification

-**Status**: 🆕 AVAILABLE - Ready for New Work
+**Status**: 🔧 IN PROGRESS - Playwright MCP Server Initialization Fix
 **Last Updated**: 2026-01-11
 **Previous Work**: Staticcheck Pre-Commit Integration (COMPLETE - Archived)

 ---

-## No Active Project
+## Active Project: Playwright MCP Server Initialization Failure

-This file is ready for your next specification. When starting a new project:
-
-1. Update the **Status** line with priority and brief description
-2. Add a **Problem Statement** section
-3. Define clear **Success Criteria**
-4. Create an **Implementation Plan** with phases and tasks
-5. Follow [Spec-Driven Workflow v1](.github/instructions/spec-driven-workflow-v1.instructions.md)
-
---
-
-## Template Structure
-
-```markdown
-# Current Specification
-
-**Status**: 🔧 IN PROGRESS - [Brief Description]
-**Last Updated**: YYYY-MM-DD
-**Previous Work**: [Previous Project Name] - Archived
-
---
-
-## Active Project: [Project Name]
-
-**Priority:** [🔴 HIGH / 🟡 MEDIUM / 🟢 LOW]
-**Reported:** [Issue source or user feedback]
-**Critical Requirement:** [Main goal in one sentence]
+**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

-[Clear description of the problem being solved]
+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

-[High-level approach chosen]
+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: [Phase Name]
- Task 1.1: [Description]
- Task 1.2: [Description]
+#### Phase 1: Create MCP Configuration File

-#### Phase 2: [Phase Name]
- Task 2.1: [Description]
- Task 2.2: [Description]
+**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. [ ] Criterion 1
-2. [ ] Criterion 2
-3. [ ] Criterion 3
+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

-[Actual measurements and targets]
+- **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

-[Identified risks and mitigations]
+| 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

 ---

-## Archive Location
+## Alternative Configurations

-**Current Specification:**
- This file: `docs/plans/current_spec.md`
+### Minimal Configuration (Single Server)

-**After Implementation:**
- Archive to: `docs/plans/archive/[project_name]_YYYY-MM-DD.md`
+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.