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.

Assemble the payload for the response header. Empty dict when nothing ran.

Collapse consecutive identical lines into a single (xN) entry.

Browser consoles repeat: one failing tile prefetch can log the same message per tile. Without this, a single fault fills the whole budget and crowds out the messages that would identify it.

Inverse of :func:encode. Returns {} rather than raising on junk.

Base64-encode payload so it is safe to put in an HTTP header.

Return and forget the output recorded for snippet_id.

Store text as the captured output of snippet_id.

Called with whatever the snippet wrote to stdout/stderr. Repeated calls for the same id append, so a partial write before an exception is not lost.

Format payload as the text block handed to the agent.

Clip text to limit, keeping the tail.

The end is the informative part — a traceback's final line, or the last thing printed before something went wrong.

limit defaults to config.diagnostics_max_chars, resolved at call time. It cannot be a default argument value: that would bind whatever the config held at import and ignore any later reset_config().

Return every section name a --prompts file may set.

Return the MCP server instructions with any configured overrides applied.

Return template (or one block of it) with configured overrides applied.

Fill capture's report fields in from a decoded :func:encode_meta payload.

Screenshot url using a shared headless browser.

Both full_page and do default to the cheapest honest answer — one image of what is on screen, nothing clicked — and the returned :class:Capture reports what that left out. Ask for more only when the question needs it.

Parameters:

Returns:

Raises:

Capture a single PNG of url. Thin wrapper over :func:capture_pages.

Validate a do script before a browser is involved.

Every problem here is a typo in the caller's own message, so it is worth catching before the cost of a page load — and worth answering with the shape that would have worked rather than only with what did not.

Raises:

Inverse of :func:encode_meta. Returns {} rather than raising on junk.

Base64-encode capture's report so it is safe to put in an HTTP header.

Control names are dropped from the end until the result fits _MAX_META_BYTES; the tile counts are fixed-size and always survive. A dashboard whose labels are paragraphs must cost the caller some names, never the image.

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.

Name one image: which screen of a tall page it is. "" when it is the only one.

MCP server lifespan - eagerly start the Panel server.

Change part of a visualization without resending the whole snippet.

Use this instead of resending the full code when you are adjusting something small — a colour, a title, a width, one line of a layout. Rewriting a 200-line snippet to change one argument costs you the entire snippet in output tokens, every round.

old_str must appear EXACTLY ONCE, matching character for character including indentation. Code is stored exactly as you sent it, so what you wrote is what is stored. If the string appears more than once, include surrounding lines until it is unique.

Works on a draft and on something the user has already been shown:

· A DRAFT is edited in place and the same id comes back. · A SHOWN snippet is FORKED — a new draft is created carrying your change and its id comes back, while the version the user is looking at does not move. Showing the fork adds a new entry to their feed; the old one stays.

Either way the edited code is run before this returns, so the id you get back is ready to hand over: show(draft_id=...) directly. Screenshot it first only if you need to SEE the change — a layout you are unsure of, not a colour you named.

Typical loops: user tweak → show returns an id → edit(id, old, new) → show(draft_id=<new id>) unsure → edit(id, old, new) → screenshot(draft_id=<new id>) → show(draft_id=<new id>)

For a small snippet, or a change touching most of the code, just resend it — that is fine and often simpler.

Parameters:

Returns:

Run Python and read its text output — no picture, no browser.

Use this when the answer you want is a VALUE, not an appearance: what a function returns, whether an option is accepted, what columns a DataFrame has, what range Bokeh actually computed. It executes in the same environment as show and screenshot, so the plotting packages are all importable, and returns whatever the code printed plus the repr of its last expression.

Prefer this over screenshot for anything textual. Rendering a value into a Markdown pane so it can be read back out of a PNG costs a browser launch and an image, and answers nothing the text would not have.

════════════════════════════════════════════════════════════════════════ DO NOT use this to answer questions about how something LOOKS ════════════════════════════════════════════════════════════════════════ Where a peak sits, which bar is tallest, what colour a series is, whether the legend overlaps — those must go through screenshot, because the rendered plot and the raw data frequently disagree (axes invert, categories sort, heatmap rows flip, values get binned). Recomputing an appearance from the data is the specific mistake screenshot exists to prevent. This tool is for facts about objects, not about pixels.

Nothing here reaches the user: no feed entry, no chat message, no stored snippet. It is yours to use as freely as you need.

Typical uses: · check an API → hv.opts.Points(autohide_toolbar=True) · inspect a rendered model → hv.render(plot).x_range.start · confirm data shape → df.dtypes, len(df), df.columns.tolist() · verify availability → import geoviews; geoviews.__version__

Parameters:

Returns:

See a visualization as a PNG — returns the image to you (the LLM), not to the user.

════════════════════════════════════════════════════════════════════════ TWO WAYS TO CALL THIS — pick one: ════════════════════════════════════════════════════════════════════════

1. screenshot(code=...) — CHECK YOUR OWN WORK BEFORE THE USER SEES IT. Renders the code and returns the picture to you alone. Nothing is added to the chat and nothing is added to the user's feed. Use it to look at a draft, fix what is wrong, and look again — as many rounds as you need. When it finally looks right, call show(draft_id=...) once, passing the draft id reported alongside the image, to hand that exact draft to the user. Do not paste the code into show again.

Do NOT call show just to get a snippet_id to screenshot. That puts every half-finished draft in front of the user, which is exactly what this parameter exists to prevent.

1. screenshot(draft_id=...) — LOOK AT A DRAFT AGAIN AFTER EDITING IT. Re-renders a draft you already have, picking up any edit calls made since. Still yours alone; nothing reaches the user.

2. screenshot(snippet_id=...) — LOOK AT SOMETHING THE USER ALREADY HAS. Pass the snippet_id that show returned. Use it to answer a follow-up question about how an already-shown visualization LOOKS. It does not create or modify anything.

Either way this is NOT a substitute for show — a screenshot is a still picture for you; only show gives the user the live, interactive page.

════════════════════════════════════════════════════════════════════════ 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).

════════════════════════════════════════════════════════════════════════ DRIVING THE APP BEFORE YOU LOOK: ════════════════════════════════════════════════════════════════════════ By default you get one screen exactly as it loaded: nothing clicked, nothing scrolled. A page taller than the window, and anything that only appears after an interaction, are missing from that picture the same silent way an empty chart is — so the reply TELLS you what is on the page and whether content continues past the fold.

Read that line and decide. You know the question; this tool does not. · full_page=True → the whole scrollable page, as a few readable screen-sized images rather than one shrunken strip · do=[...] → a short script run before the picture is taken:

do=[{"click": "Reports"}]                                 # open a tab
do=[{"select": "Region", "value": "West"}]                # pick a dropdown option
do=[{"fill": "Search", "value": "acme"}, {"key": "Enter"}] # type, then submit
do=[{"click": "Box Zoom"}, {"drag": [300, 200, 500, 350]}] # zoom into a plot

Each step names what to act on — the text on it, its tooltip, or its label — not a CSS selector, and not a widget type. This reaches anything: a Tabs strip, a Button, a Select, a RadioButtonGroup, or a Bokeh toolbar icon (icons carry no visible text, only a tooltip — "click": "Box Zoom" finds one by that tooltip). Steps run in order, each settling before the next.

{"drag": [x0, y0, x1, y1]} is viewport pixels, not a name — the one step for a canvas or a plot region that has nothing to click by name. A crowded scatter plot rendered with datashader often needs exactly this: click the plot's "Box Zoom" tool, then drag a box over the crowded area, to see whether the individual points resolve once zoomed. The tool is not active by default — clicking it first is part of the script, not optional.

A step that matches nothing, or matches more than one thing, is refused before any picture is taken, and the message names what IS on the page — read it and try again with a more specific name.

Nothing is clicked unless you name it. A Select wired to filter data and a Select wired to switch pages look identical until you act on one; this tool never decides that for you.

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 loops: · building something → screenshot(code=...) → revise → screenshot(code=...) → show(draft_id=...) · small adjustment → edit(id, old, new) → show(draft_id=<new id>) · visual follow-up → show (returns id) → screenshot(snippet_id=id)

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 — this tool is for FINISHED work; calling it puts the visualization in front of the user. To check your own output first, call screenshot(code=...) instead — that renders the code and returns the picture to you alone, with nothing appearing in the chat or the user's feed. Iterate there as long as you need, then finish with show.

IMPORTANT — if you reached the final version through screenshot(code=...), call show(draft_id=...) with the draft id that screenshot reported, NOT show(code=...) with the code pasted again. The draft has already been rendered and checked, so promoting it costs nothing and cannot introduce a difference between what you looked at and what the user gets.

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.

Note that tool received chars characters of code.

A call with chars=0 still counts as a call. That case is the point of the measurement rather than a degenerate one: a promotion moves a finished visualization to the user while sending no code at all, and it is only visible as a saving if those calls are counted alongside the ones that do carry a payload.

Parameters:

Clear the counters. For tests, and for starting a fresh measurement.

Return the current counts, safe to serialize into a response.

Returns:

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