Contributing¶

Contributions are welcome! This guide walks you through forking the repository, setting up a local development environment, and connecting your local build to an MCP client.

Step 1: Fork and clone¶

Fork the repository on GitHub.
Clone your fork:

git clone https://github.com/<your-username>/panel-live-server.git
cd panel-live-server

Create a feature branch:

git checkout -b feature/YourFeature

Step 2: Install¶

pixiuv

Install the environment:

pixi install

Run the post-install step (editable install plus Chromium setup):

pixi run postinstall

Find the pls path:

macOS / Linux:

pixi run which pls
# typically: /path/to/panel-live-server/.pixi/envs/default/bin/pls

Windows:

pixi run where.exe pls
# typically: .pixi\envs\default\Library\bin\pls.exe

Note

Prefix commands with pixi run (e.g. pixi run pytest) to use the pixi env without activating it. pixi run postinstall already installs Chromium automatically.

Create and activate a virtual environment.

macOS / Linux:

uv venv
source .venv/bin/activate

Windows (PowerShell):

uv venv
.venv\Scripts\Activate.ps1

Windows (Command Prompt):

uv venv
.venv\Scripts\activate.bat

Install the package in editable mode:

uv pip install -e ".[dev]"

Install the browser binary needed by the screenshot MCP tool:

playwright install chromium

Find the pls path:

macOS / Linux:

which pls
# typically: /path/to/panel-live-server/.venv/bin/pls

Windows:

where.exe pls
# typically: .venv\Scripts\pls.exe

Note

Re-activate the venv in every new terminal (see above). playwright install chromium is a one-time step that downloads the browser binary (~150 MB) required by the screenshot MCP tool.

Step 3: Install pre-commit hooks¶

pixiuv

pixi run lint-install

pre-commit install

Step 4: Connect to your MCP client¶

Testing your local checkout vs the released PyPI package¶

pls install <client> registers whichever pls ran the command, so how you invoke it decides which build your client ends up using.

To test your local changes (the normal case while contributing), run the command through pixi so it always resolves to the editable copy of the checkout you are editing, not any other pls that might also be on your machine:

pixi run pls install claude    # or: cursor / vscode / claude-code

Check it picked the right one:

pixi run pls --version
# 0.1.0a5.post1.dev52+gda3756c94 -- has a dev/git-hash suffix: editable, tracks your checkout

To test the released PyPI package instead (comparing behaviour, or confirming a bug only shows up in a release, not your branch), install it separately and run its own pls install:

pip install panel-live-server    # or: uv tool install panel-live-server
pls install claude

pls --version
# 0.1.0a5 -- plain version, no dev/git-hash suffix: this is the frozen PyPI build

Registering one replaces the other

Both point the same client at whichever pls you last ran install with, so running the PyPI one after the pixi one switches Claude Desktop (or Cursor, etc.) over to the released build, and vice versa. To register a specific build without relying on which pls happens to run the command, pass it explicitly: pls install claude --command /path/to/pls.

Once you've picked the build to register, add it to your client:

VS CodeCursorClaude DesktopClaude Codeclaude.ai

pixi run pls install vscode

Run it from the project root: VS Code reads .vscode/mcp.json per project, so this writes it relative to your current directory.

To set it up by hand instead, add to .vscode/mcp.json (create if it doesn't exist):

{
  "servers": {
    "panel-live-server": {
      "type": "stdio",
      "command": "/path/to/pls",
      "args": ["mcp"]
    }
  }
}

Use your absolute path

Replace "command": "/path/to/pls" with the path printed above, e.g. "command": "/path/to/panel-live-server/.venv/bin/pls"

pixi run pls install cursor

To set it up by hand instead, add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "panel-live-server": {
      "command": "/path/to/pls",
      "args": ["mcp"]
    }
  }
}

Use your absolute path

Replace "command": "/path/to/pls" with the path printed above, e.g. "command": "/path/to/panel-live-server/.venv/bin/pls"

Open Cursor Settings → MCP and verify the green dot. Use Agent mode in chat.

pixi run pls install claude

To set it up by hand instead, edit the config file for your OS:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "panel-live-server": {
      "command": "/path/to/pls",
      "args": ["mcp"]
    }
  }
}

Use your absolute path

Replace "command": "/path/to/pls" with the path printed above, e.g. "command": "/path/to/panel-live-server/.venv/bin/pls"

Restart Claude Desktop.

pixi run pls install claude-code

Or run the underlying command yourself:

claude mcp add panel-live-server -- /path/to/pls mcp

Use your absolute path

Replace /path/to/pls with the path printed above, e.g. claude mcp add panel-live-server -- /path/to/panel-live-server/.venv/bin/pls mcp

If the server is already registered, remove it first with claude mcp remove panel-live-server.

claude.ai requires HTTP transport and a public URL. You can use any tunneling service (ngrok, Cloudflare, localhost.run, etc.); this example uses Cloudflare.

Terminal 1: start the MCP server:

/path/to/pls mcp --transport http --port 8001

Use your absolute path

Replace /path/to/pls with the path printed above, e.g. /path/to/panel-live-server/.venv/bin/pls mcp --transport http --port 8001

Terminal 2: tunnel for the MCP server:

cloudflared tunnel --url http://localhost:8001

Terminal 3: tunnel for the Panel server:

cloudflared tunnel --url http://localhost:5077

Stop Terminal 1, then set the Panel tunnel URL.

macOS / Linux:

export PANEL_LIVE_SERVER_EXTERNAL_URL=<url-from-terminal-3>

Windows (PowerShell):

$env:PANEL_LIVE_SERVER_EXTERNAL_URL="<url-from-terminal-3>"

And restart:

/path/to/pls mcp --transport http --port 8001

Then go to claude.ai → Settings → Connectors → Add custom connector and enter <url-from-terminal-2>/mcp as the URL.

Step 5: Make changes and run tests¶

pixiuv

pixi run test                        # run all tests
pixi run test-coverage               # tests + coverage report
pixi run lint                        # lint (pre-commit on all files)

pytest tests/                        # run all tests
pytest tests/test_validation.py      # run a single file
pre-commit run --all-files           # lint

Step 6: Submit a pull request¶

Commit your changes:

git commit -m 'Add some feature'

Push to your fork:

git push origin feature/YourFeature

Open a pull request against the main branch on GitHub.

Please ensure your code passes all tests and linting before submitting.