From 3a1a1b576ae274ae0d2cbad2b10c1749fdd89951 Mon Sep 17 00:00:00 2001
From: Scott Taylor <scott.c.taylor@mac.com>
Date: Tue, 5 May 2026 10:31:55 -0400
Subject: [PATCH] fix MCP path resolution, CDP connection limit, Playwright
 signature
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three small unrelated factual corrections, grouped because they are
all docs-only one-liners.

1. MCP path resolution (addresses point 2 of #10)
   - Claude Code CLI form: "$(command -v lightpanda)" resolves the
     absolute path at install time, regardless of where the binary
     lives.
   - JSON config form: literal /absolute/path/to/lightpanda
     placeholder with instruction to fill it in via
     command -v lightpanda. No per-OS examples (those would
     presuppose the install method, which varies).

   This does NOT close #10 — only the second bullet of greenrd's
   issue. Point 1 (the 'skills' field in marketplace.json) is a
   different file this PR doesn't touch.

2. CDP connection limit
   The Important Notes bullet said 'Only 1 CDP connection per process'.
   Current Lightpanda defaults to 16 and exposes --cdp-max-connections
   N to tune it. Updates the bullet and adds the flag to the
   lightpanda serve options list.

3. Playwright connectOverCDP signature
   Both Playwright overloads (string and object) work in playwright-core
   1.58, but Playwright's own JSDoc Usage examples and published docs
   use the string form (chromium.connectOverCDP('ws://...')). This is
   a style preference, not a bug — happy to drop or split out.
---
 SKILL.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/SKILL.md b/SKILL.md
index f0a65d6..25e7dcd 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -51,7 +51,8 @@ The MCP server is the simplest way for agents to use Lightpanda. It exposes purp
 ### Setup for Claude Code
 
 ```bash
-claude mcp add lightpanda -- $HOME/.local/bin/lightpanda mcp
+# Make sure Lightpanda is installed first (see Install above).
+claude mcp add lightpanda -- "$(command -v lightpanda)" mcp
 ```
 
 ### Setup for other MCP clients
@@ -62,14 +63,14 @@ Add to your MCP client configuration:
 {
   "mcpServers": {
     "lightpanda": {
-      "command": "$HOME/.local/bin/lightpanda",
+      "command": "/absolute/path/to/lightpanda",
       "args": ["mcp"]
     }
   }
 }
 ```
 
-Replace `$HOME` with the actual path (e.g., `/home/username` or `/Users/username`).
+`$HOME` doesn't expand inside JSON config strings, so use a literal absolute path. Get it from `command -v lightpanda` after install.
 
 ### Available MCP Tools
 
@@ -153,6 +154,7 @@ Options:
 - `--log-level info|debug|warn|error` — Set logging verbosity
 - `--log-format pretty|logfmt` — Output format for logs
 - `--obey-robots` — Fetch and obey robots.txt
+- `--cdp-max-connections N` — Max simultaneous CDP connections (default 16)
 
 ### Using with playwright-core
 
@@ -162,9 +164,7 @@ Connect using `playwright-core` (not the full `playwright` package):
 const { chromium } = require('playwright-core');
 
 (async () => {
-  const browser = await chromium.connectOverCDP({
-    endpointURL: 'ws://127.0.0.1:9222',
-  });
+  const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');
 
   const context = await browser.newContext({});
   const page = await context.newPage();
@@ -246,7 +246,7 @@ await client.send('LP.clickNode', { backendNodeId });
 
 * For web searches, use DuckDuckGo instead of Google. Google blocks Lightpanda due to browser fingerprinting.
 * Lightpanda is under heavy development and may have occasional issues. It executes JavaScript, making it suitable for dynamic websites and SPAs.
-* **CDP connection limits:** Only 1 CDP connection per process. Each connection supports 1 context and 1 page. For parallel browsing, start multiple processes on different ports — Lightpanda starts instantly, so this is fast.
+* **CDP connection limits:** Up to 16 simultaneous CDP connections per process by default (configurable via `--cdp-max-connections`). Each connection supports 1 context and 1 page. For higher parallelism, raise the flag or start multiple processes on different ports — Lightpanda starts instantly, so spawning extra processes is also fast.
 * **CDP state management:** The browser resets all state on CDP connection close. Keep the WebSocket connection open throughout a session. On each connection, always create a new context and page, and close both when done.
 * The MCP server handles connection management automatically — these CDP limits don't apply when using MCP tools.