panel-live-server¶

Start the Panel server.

Download the Chromium browser the screenshot MCP tool needs.

Playwright ships its browser binary separately from the Python package, so a pip or uv install does not fetch it automatically. Run this once after installing (pixi users get it via pixi run postinstall). It lands in the same environment that runs pls.

List all Python packages installed in the current environment.

Optionally filter by a substring, e.g. pls list packages panel to show only packages whose name contains "panel".

Entry point for the pls command.

Panel Live Server - Execute and visualize Python code snippets.

Start as an MCP server for AI assistants.

The MCP server exposes the show tool for executing and displaying Python visualizations. A Panel visualization server starts automatically on a per-environment port (override with PANEL_LIVE_SERVER_PORT) — run pls status to see the address, then visit its /feed in a browser to watch visualizations appear in real time.

Note: the --port flag here controls the MCP HTTP/SSE listener, NOT the Panel visualization server port. For stdio transport, --port is unused.

Start the Panel Live Server directly.

The server provides a web interface for executing Python code snippets and visualizing the results. Visit http://:/feed to see visualizations as they are created.

Note: pls serve and pls mcp launched from the same environment resolve to the same per-environment default port, so a browser opened here shows the visualizations the MCP server renders. Set PANEL_LIVE_SERVER_PORT (or --port) to override.

Check whether the Panel server is running.

Queries the health endpoint and reports the server status.

Print version and exit.

Return the Panel server port for the active Python environment.

An explicit PANEL_LIVE_SERVER_PORT always wins. Otherwise the port is derived deterministically from the interpreter (sys.prefix) so that each environment gets its own server.

This is what keeps pls executing snippets against the packages the user expects: the Panel server subprocess runs in the same interpreter as pls itself, but a single fixed port would let an MCP client launched from one environment silently adopt a server already running in another. That server executes code against its installed packages, so an import the user just installed alongside pls shows up as missing. A per-environment port means different environments no longer collide on one server.

Get or create the config instance.

Reset config (for testing).

Get or create the SnippetDatabase instance.

This function implements lazy initialization with a global cache. The database instance is created once and reused across the application.

Parameters:

Returns:

Reset the database instance.

This is primarily for testing purposes to ensure a clean state.

Capture a PNG screenshot of url using a shared headless browser.

Returns:

Raises:

Download the headless Chromium browser the screenshot tool needs.

Playwright ships its browser binary separately from the Python package, so pip/uv installs do not fetch it automatically. This shells out to <this-interpreter> -m playwright install chromium so the browser always lands in the same environment that is running pls — avoiding the common trap where the binary is installed under a different interpreter.

Returns:

Return True if the Chromium binary Playwright needs is present.

This is a cheap check — it does not launch a browser. It uses Playwright's sync API, so call it from a worker thread (e.g. asyncio.to_thread), not directly inside a running event loop.

MCP server lifespan - eagerly start the Panel server.

See an EXISTING visualization — returns a PNG image of it to you (the LLM).

Pass the snippet_id that show returned; this tool screenshots that already-rendered /view page and hands you the picture so you can answer a follow-up question about how it LOOKS. It does NOT create or modify anything and is NOT a substitute for show — the user already has the interactive visualization in their browser.

════════════════════════════════════════════════════════════════════════ CRITICAL RULE — answering questions ABOUT a visualization's appearance: ════════════════════════════════════════════════════════════════════════ When the user asks where something is, which element is biggest/smallest, what color/position/shape something has, or anything about how the chart LOOKS, you MUST call this tool and answer from the returned image.

You MUST NOT answer such questions by reading the code, recomputing from the raw data, or re-running the snippet in a Python tool. THAT IS CHEATING AND IS USUALLY WRONG, because the rendered plot is NOT the same as the raw data: - heatmaps flip/reverse the row order (Row 0 often renders at the BOTTOM) - axes get inverted, categories get sorted, histograms bin/group values - color mapping, stacking, and layout change what is visually "highest" The raw-data answer and the on-screen answer frequently DISAGREE. The image is the only ground truth for a question about appearance — so look at it.

Do not add np.random.seed(...) or otherwise make data deterministic just so you can recompute it; read the answer off the actual picture.

════════════════════════════════════════════════════════════════════════ IMAGE QUALITY — when the picture is not enough: ════════════════════════════════════════════════════════════════════════ After receiving the screenshot, check whether it is clear enough to answer: - Is the chart blurry or pixelated? - Is the relevant detail (a label, a tick value, a legend entry) too small to read confidently? - Is the area of interest clipped or off-screen?

If YES — the image is not reliable enough — do NOT guess from it. Instead, answer the question directly from the code and data (compute the value, read the label, inspect the structure). A code-derived answer is better than a wrong guess from a bad image.

If the image is fine, always prefer it over recomputing (see CRITICAL RULE above — rendered output and raw data frequently disagree).

WHEN TO USE — a follow-up question about an already-shown visualization that can only be answered by seeing it (random/dynamic data, or visual position): · wave/line chart → "where does it peak?", "where is the lowest dip?" · bar chart → "which bar is the tallest?", "which category leads?" · scatter plot → "where are the outliers?", "how spread out are the points?" · heatmap → "which cell has the highest value?" · pie/donut chart → "which slice is the largest?" · histogram → "where is the distribution centered?" · any chart → "what color is X?", "what does the legend say?"

Typical loop: show (returns id) → screenshot(snippet_id=id) when the user asks something visual you can't read off the code.

Parameters:

Returns:

Display Python code as a live, interactive visualization.

Runs static validation (syntax, security, packages, extensions) in ~50 ms, stores the snippet, and returns the visualization URL. The iframe loads immediately via Panel's WebSocket — the user sees a loading indicator then the rendered visualization, with no prior validate() call needed.

Always call this tool when the user asks to show, display, plot, or visualize anything.

IMPORTANT — pass the Python code DIRECTLY as the code argument. Do NOT write it to a file in the user's project first, do NOT create scripts, notebooks, or examples/ files, and do NOT run it in a separate shell. This tool executes the code itself; creating files is unwanted side-effect clutter in the user's repository.

IMPORTANT — always provide a short name (e.g. "Temperature chart") so the visualization is easy to find in the feed.

IMPORTANT — after calling this tool, always present the returned url to the user as a clickable Markdown link: [Show Visualization](url)

Parameters:

Returns:

Return the HTML resource used by the show MCP App.

Create a banner indicating alpha/experimental software.

Execute Python code in a proper module namespace.

Creates a types.ModuleType following Bokeh's pattern, registers it in sys.modules, executes code, and optionally cleans up. This ensures Panel decorators (@pn.cache, @pn.depends) and function references work properly by using module.dict as a single namespace for both globals and locals.

Parameters:

Returns:

Raises:

Examples:

>>> namespace = execute_in_module(
...     "x = 1\ny = 2\nz = x + y",
...     "my_module"
... )
>>> namespace['z']
3

Extract the last expression from code for jupyter method.

Parameters:

Returns:

Infer Panel extensions required for code execution.

Maps common packages/types to their Panel extensions: - pandas DataFrame/Series -> "tabulator" - plotly figures -> "plotly" - bokeh models -> (none, default) - matplotlib figures -> (none, uses pngpane) - altair charts -> "vega" - deck.gl -> "deckgl"

Parameters:

Returns:

Find package requirements from code.

Uses Panel's built-in find_requirements function to detect package dependencies.

Parameters:

Returns:

Generate a relative URL for viewing a visualization by ID.

Parameters:

Returns:

Prepend conda/pixi environment DLL directories to env["PATH"].

On Windows, compiled extensions such as numpy require <env>/Library/bin and <env>/DLLs to be on PATH so Windows can locate the native DLLs at import time. These entries are added automatically when a shell activates the environment (e.g. via conda activate or pixi run), but external launchers such as MCP clients typically do not activate the environment.

This function is idempotent: if the entries are already present in env["PATH"] they are not duplicated.

It operates on any str → str mapping so it can patch both os.environ (for the current process) and a freshly copied dict (for a subprocess env= argument).

Parameters:

Returns:

Execute code in a thread with a timeout to catch runtime errors.

Runs code in a separate thread so the caller is not blocked indefinitely by long-running or hanging code. The thread is a daemon — on timeout it continues running until the process exits (threads cannot be forcibly killed).

Parameters:

Returns:

Validate that required Panel Javascript extensions are loaded in the code.

Parameters:

Raises:

Return an error string if code has a syntax error, else None.

Parameters:

Returns:

Examples:

>>> ast_check("x = 1")
>>> ast_check("if True")
'expected \':\' (line 1, col 8)'

Check that all packages imported by code are installed.

Parses imports via AST and calls importlib.util.find_spec() for each top-level module name. Stdlib modules are skipped. Returns an error string for the first missing package, or None if everything is available.

Parameters:

Returns:

Examples:

>>> check_packages("import os\\nimport json") is None
True
>>> check_packages("import numpy") is None
True
>>> "HoloViz" in (check_packages("import _totally_fake_pkg_xyz") or "")
True

Run import blocklist and ruff security checks on code.

First performs a fast AST-based blocked-import scan (does not depend on ruff being installed), then runs ruff for deeper static analysis.

Raises SecurityError if any violations are found. Returns None silently if the code is clean or ruff is not installed.

Parameters:

Raises:

Examples:

>>> ruff_check("x = 1")
>>> ruff_check("import pickle")
SecurityError: ...

Autoformat code via ruff format and return the result.

Returns code unchanged if ruff is not installed or formatting fails.

Parameters:

Returns:

Examples:

>>> ruff_format("x=1+2") == "x = 1 + 2\\n"
True