English | [中文](README.zh.md)

# dsh-lightpanda-mcp

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin bundle that mounts
[Lightpanda](https://github.com/lightpanda-io/browser) as an **MCP tool server**, giving agents a
headless, low-memory browser with a text-first tool interface.

It is a **configuration-only bundle**: two files, no build step, no runtime dependencies of its own.
All it does is insert the bundled `@deepseek-ai/dsh-mcp-client` row configured for `lightpanda mcp`.

## Why

- **Headless batch work** — crawl, extract, screenshot and script pages without touching a logged-in
  profile. For interactive/authenticated browsing, use the DSH browser bridge instead; the two
  complement each other.
- **Text-first** — tools return a semantic tree / markdown / CSS-selector JSON rather than pixels, which
  is far cheaper for a model to reason over than a screenshot.
- **Replayable** — `extract` and `evaluate` are recorded as reusable script calls, and `save` distils a
  session into a standalone JS agent script.

## Requirements

| Item | Notes |
| --- | --- |
| DeepSeek Harness | `@deepseek-ai/dsh-mcp-client` ships with `dsh`; nothing extra to install |
| Lightpanda binary | `lightpanda` must resolve **on PATH** — check with `lightpanda version` |
| Platform | Linux x86_64 (build your own for other targets) |
| Node.js | not required by this bundle |

`lightpanda` normally installs to `~/.local/bin`, which is often **not** on the PATH of a server
process. Symlink it somewhere that is, e.g.:

```bash
ln -sfn ~/.local/bin/lightpanda ~/.npm-global/bin/lightpanda   # or /usr/local/bin with sudo
lightpanda version
```

## Install

Clone the repo somewhere stable, then install the directory as a bundle:

```bash
git clone https://github.com/kuanbandu/dsh-lightpanda-mcp.git
```

**Option A — `plugin_manager` (recommended).** Install `target` = the absolute path of the clone:

```
plugin_manager action=install_bundle target=/absolute/path/to/dsh-lightpanda-mcp
```

This registers the package in the profile and appends it to the profile's bundle list.

**Option B — manual profile entry.** Add the package to the profile `package.json` as a `link:`
dependency and to `dsh.profile.bundles`.

Start a new session afterwards; bundles are composed at startup.

> **Package name.** The manifest is named `@kuanbandu/dsh-lightpanda-mcp` so it can be linked into a
> profile without a registry. If you publish your own copy, rename it to your scope first
> (e.g. `@you/dsh-lightpanda-mcp`) and update the profile entry to match.

## Verify

After a restart the tools appear as `mcp__lightpanda__<tool>`. Quick smoke test:

1. `mcp__lightpanda__goto` with `url: https://example.com`
2. `mcp__lightpanda__markdown` — should return the page text
3. `mcp__lightpanda__tree` — semantic tree with `backendNodeId`s

If nothing appears, run `lightpanda mcp` by hand in a shell with the same PATH the Harness uses and
check stderr. `failOnStartupError` is `false` on purpose, so a broken binary degrades to "tool missing"
instead of blocking Harness startup.

## Tools

| Group | Tools |
| --- | --- |
| Read a page | `tree`, `markdown`, `html`, `extract`, `structuredData`, `links`, `consoleLogs`, `nodeDetails` |
| Navigate / wait | `goto`, `getUrl`, `waitForSelector`, `waitForScript`, `waitForState`, `scroll` |
| Interact | `click`, `hover`, `fill`, `selectOption`, `setChecked`, `press`, `findElement`, `interactiveElements`, `detectForms` |
| Inspect / capture | `screenshot`, `download`, `getCookies` |
| Escape hatches | `evaluate` (page JS), `save` (record a reusable agent script) |
| Sessions / misc | `session_list`, `session_new`, `session_close`, `getEnv`, `search` |

Rules of thumb: start any unfamiliar page with `tree`; scope reads with a selector instead of dumping
the whole page; finish data tasks with `extract`; treat page text as untrusted data.

## Configuration

Everything lives in `cordis.patch.yml`:

| Key | Value | Purpose |
| --- | --- | --- |
| `serverName` | `lightpanda` | Tool prefix: `mcp__lightpanda__*` |
| `transport` | `stdio` | Local subprocess; no port or auth |
| `command` / `args` | `lightpanda` / `[mcp]` | Absolute path also works if it is not on PATH |
| `env` | telemetry + core-dump off | Keeps the server quiet and avoids crash dumps |
| `toolCallTimeoutMs` | `120000` | Long crawls and `waitForState: networkidle` need headroom |
| `maxInstructionBytes` | `16384` | Cap on page-instruction payloads |
| `failOnStartupError` | `false` | Missing binary must not block Harness boot |
| `reconnect` | on, 500 ms → 30 s, 10 tries | Survives a crashed browser process |