Documentation
¶
Overview ¶
Package lp provides web page reading via lightpanda browser with MCP (default) or CDP (deprecated) transport.
Architecture ¶
url(req) +---------------+ stdio +-------------+
-------->| MCP Client +--------->| lightpanda |
| (mcp.go) | | mcp |
<--------+ |<---------+ |
markdown +---------------+ markdown +-------------+
The package uses LightPanda's native MCP server by default (lightpanda mcp subcommand, stdio transport). The older CDP transport (lightpanda serve + chromedp) remains available via the lightpanda_transport = "cdp" config key but is deprecated and will be removed in v0.10.0.
MCP transport advantages over CDP:
- Self-contained: no need for a running serve process
- Simpler: no WebSocket, no chromedp dependency
- Same engine: calls the same Zig conversion code internally
Transport Configuration ¶
Config key (~/.dscli/config.dscli):
lightpanda_transport = mcp # "mcp" (default) or "cdp" (deprecated)
Remote vs Local ¶
This distinction only applies to the CDP transport. With MCP, every call spawns a local lightpanda mcp subprocess. For geo-restricted sites, use LightPanda Cloud's MCP/SSE endpoint when available.
CDP-only config keys (deprecated) ¶
These keys are only used when lightpanda_transport = "cdp":
lightpanda-local-url = ws://127.2.2.9:9227 lightpanda-remote-url = wss://euwest.cloud.lightpanda.io/ws lightpanda-remote-token = <token>
Usage ¶
import "github.com/dscli/dscli/internal/lp" markdown, err := lp.Get(ctx, "https://example.com")
Package lp provides LightPanda integration for web page interaction.
MCP tool integration for the toolcall framework. The init function registers callbacks with toolcall so that MCP tools (markdown, semantic_tree, evaluate, goto, etc.) are included in GetAllTools and dispatched via a persistent MCPClient singleton in HandleToolCall.
Index ¶
- Constants
- Variables
- func DefaultCookiePath() string
- func Get(ctx context.Context, rawURL string) (string, error)
- func GetRemote(ctx context.Context, rawURL string) (string, error)
- func NetworkCheck(rawURL string) error
- func NewChromium(ctx context.Context) (context.Context, func(), error)
- func ReadCodeFromStdin() (string, error)
- func WebChat(ctx context.Context, message string) (string, error)
- type MCPClient
- func (c *MCPClient) CallTool(ctx context.Context, name string, args map[string]any) (string, error)
- func (c *MCPClient) Close() error
- func (c *MCPClient) Evaluate(ctx context.Context, script, url string) (string, error)
- func (c *MCPClient) GetMarkdown(ctx context.Context, url string) (string, error)
- func (c *MCPClient) GetSemanticTree(ctx context.Context, url string) (string, error)
- func (c *MCPClient) ListTools(ctx context.Context) ([]*mcp.Tool, error)
- type MCPToolError
Constants ¶
const ( // TransportMCP uses the LightPanda native MCP server (default). This // spawns "lightpanda mcp" as a subprocess and communicates over stdio. TransportMCP = "mcp" // TransportCDP uses the Chrome DevTools Protocol. This requires // "lightpanda serve" to be running (it will be auto-started if needed). // Deprecated: will be removed in v0.10.0. TransportCDP = "cdp" )
Transport constants for lightpanda_transport config key.
Variables ¶
var ErrLoginRequired = errors.New("login required — open visible browser to complete login")
ErrLoginRequired is returned when the browser is not logged in to DeepSeek. Callers should trigger a visible login flow and retry.
Functions ¶
func DefaultCookiePath ¶
func DefaultCookiePath() string
DefaultCookiePath returns the default path for the DeepSeek cookie file.
func Get ¶
Get fetches a web page via lightpanda CDP and returns its markdown content.
It automatically routes to remote lightpanda for geo-restricted hosts (listed in remoteHosts), and uses local lightpanda for all other URLs. If remote is not configured, even remoteHosts fall back to local.
If local lightpanda is not running but the lightpanda command is available, Get will auto-start lightpanda serve in the background before fetching.
Config keys used (from ~/.dscli/config.dscli):
- lightpanda-local-url (default: ws://127.2.2.9:9227)
- lightpanda-remote-url (default: "")
- lightpanda-remote-token (default: "")
Get fetches a web page via lightpanda CDP and returns its markdown content.
It automatically routes to remote lightpanda for geo-restricted hosts (listed in remoteHosts), and uses local lightpanda for all other URLs. If remote is not configured, even remoteHosts fall back to local.
If local lightpanda is not running but the lightpanda command is available, Get will auto-start lightpanda serve in the background before fetching.
Config keys used (from ~/.dscli/config.dscli):
- lightpanda-local-url (default: ws://127.2.2.9:9227)
- lightpanda-remote-url (default: "")
- lightpanda-remote-token (default: "")
func GetRemote ¶
GetRemote fetches a web page via remote lightpanda CDP regardless of the target host. Returns an error if remote is not configured.
Unlike Get, GetRemote skips the host-based routing and local lightpanda auto-start — it always uses the configured remote endpoint.
Config keys used:
- lightpanda-remote-url (required)
- lightpanda-remote-token (optional)
func NetworkCheck ¶ added in v0.8.5
NetworkCheck verifies that the target URL's host is reachable via TCP before launching a browser. This avoids wasting time on a truly down network — Chrome would otherwise report ERR_INTERNET_DISCONNECTED and fail after a much longer timeout.
The check connects directly from the host, bypassing Chrome's network stack, so it only fails when the host actually has no connectivity. On URL parse errors the check is skipped (assume reachable).
func NewChromium ¶ added in v0.8.5
NewChromium creates a new chromedp ExecAllocator backed by a local Chrome/Chromium browser. The caller must call the returned cancel func to shut down the browser when done.
Usage:
ctx, cancel, err := NewChromium(parentCtx)
if err != nil { return err }
defer cancel()
tabCtx, tabCancel := chromedp.NewContext(ctx)
defer tabCancel()
func ReadCodeFromStdin ¶
ReadCodeFromStdin reads a verification code from stdin with a prompt. In non-interactive environments (stdin not a terminal), it falls back to polling codeFilePath every 2 seconds for up to 5 minutes.
func WebChat ¶
WebChat sends a message to chat.deepseek.com via a local Chrome/Chromium browser and returns the assistant's text response.
The browser is launched fresh for each call and closed after the response is received. Cookies persist via the shared Chrome profile directory, so prior login state is available across calls.
If ctx carries context.KeepKey set to true, WebChat attempts to continue the last saved conversation (loaded from the profile directory) rather than starting a new one. New conversations automatically enable expert mode (V4 Pro).
Types ¶
type MCPClient ¶ added in v0.8.6
type MCPClient struct {
// contains filtered or unexported fields
}
MCPClient wraps a LightPanda MCP session. It manages the lifecycle of a lightpanda mcp subprocess, providing a simple interface for web page content extraction via MCP tools.
The client is safe for concurrent use (calls are serialized through an internal mutex because stdio transport cannot safely multiplex writes).
func NewMCPClient ¶ added in v0.8.6
NewMCPClient starts lightpanda mcp and connects to it.
It looks up the lightpanda binary via exec.LookPath, spawns it with the "mcp" subcommand, and establishes an MCP session. The caller must call Close when done.
func (*MCPClient) CallTool ¶ added in v0.8.6
CallTool calls a tool by name with the given arguments. This is a generic version of GetMarkdown/GetSemanticTree/Evaluate that allows calling any tool exposed by the MCP server. The caller is responsible for calling Close after finishing.
func (*MCPClient) Close ¶ added in v0.8.6
Close shuts down the MCP session and kills the subprocess.
func (*MCPClient) Evaluate ¶ added in v0.8.6
Evaluate runs JavaScript in the page context and returns the result. If url is non-empty, the page navigates there first before evaluation.
func (*MCPClient) GetMarkdown ¶ added in v0.8.6
GetMarkdown navigates to a URL and returns the page content as markdown. If the returned markdown is empty and no error occurred, it means the page loaded but had no extractable text content.
func (*MCPClient) GetSemanticTree ¶ added in v0.8.6
GetSemanticTree navigates to a URL and returns the page's simplified semantic DOM tree, optimized for AI reasoning about page structure.
type MCPToolError ¶ added in v0.8.6
type MCPToolError struct {
Tool string // name of the tool that failed
Content []mcp.Content // original response content, preserved for debugging
}
MCPToolError is returned when an MCP tool call completes with IsError=true. Unlike a transport-level error (which would be returned as a Go error directly), this indicates the tool ran but its operation failed (e.g., URL unreachable).
func (*MCPToolError) Error ¶ added in v0.8.6
func (e *MCPToolError) Error() string
Source Files