Charon/docs/plans/current_spec.md

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

{
  "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

# 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:

# 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:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["playwright", "run-test-mcp-server"]
    }
  }
}

Advanced Configuration (Custom Port)

For specific port binding:

{
  "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 format.