holoviz-mcp 0.0.1a0__py3-none-any.whl → 0.0.1a2__py3-none-any.whl

holoviz_mcp/hvplot_mcp/server.py

@@ -0,0 +1,152 @@
+"""[hvPlot](https://hvplot.holoviz.org/) MCP Server.
+
+This MCP server provides tools, resources, and prompts for using hvPlot to develop quick, interactive
+plots in Python using best practices.
+
+Use this server to:
+- List available hvPlot plot types (e.g., 'line', 'scatter', 'bar', ...)
+- Get docstrings and function signatures for hvPlot plot types
+- Access hvPlot documentation and best practices
+"""
+
+from typing import Literal
+from typing import Optional
+from typing import Union
+
+from fastmcp import Context
+from fastmcp import FastMCP
+
+# Create the FastMCP server
+mcp = FastMCP(
+    name="hvplot",
+    instructions="""
+    [hvPlot](https://hvplot.holoviz.org/) MCP Server.
+
+    This MCP server provides tools, resources, and prompts for using hvPlot to develop quick, interactive plots
+    in Python using best practices. Use this server to:
+
+    - List available hvPlot plot types
+    - Get docstrings and function signatures for hvPlot plot types
+    - Access hvPlot documentation and best practices""",
+)
+
+
+def _help(
+    plot_type: Optional[str] = None, docstring: bool = True, generic: bool = True, style: Union[Literal["matplotlib", "bokeh", "plotly"], bool] = True
+) -> tuple[str, str]:
+    """Retrieve hvPlot docstring and function signature for a plot type."""
+    import holoviews as hv
+    from hvplot.plotting.core import hvPlot
+    from hvplot.util import _get_doc_and_signature
+
+    if isinstance(style, str):
+        hv.extension(style)
+    else:
+        hv.extension("bokeh")
+
+    doc, sig = _get_doc_and_signature(cls=hvPlot, kind=plot_type, docstring=docstring, generic=generic, style=style)
+    return doc, sig
+
+
+@mcp.tool
+async def list_plot_types(ctx: Context) -> list[str]:
+    """
+    List all available hvPlot plot types supported in the current environment.
+
+    Use this tool to discover what plot types you can generate with hvPlot.
+
+    Note: The plot types are also called "kinds".
+
+    Parameters
+    ----------
+    ctx : Context
+        FastMCP context (automatically provided by the MCP framework).
+
+    Returns
+    -------
+    list[str]
+        Sorted list of all plot type names (e.g., 'line', 'scatter', 'bar', ...).
+
+    Examples
+    --------
+    >>> list_plot_types()
+    ['area', 'bar', 'box', 'contour', ...]
+    """
+    from hvplot.converter import HoloViewsConverter
+
+    return sorted(HoloViewsConverter._kind_mapping)
+
+
+@mcp.tool
+async def get_docstring(
+    ctx: Context, plot_type: str, docstring: bool = True, generic: bool = True, style: Union[Literal["matplotlib", "bokeh", "plotly"], bool] = True
+) -> str:
+    """
+    Get the hvPlot docstring for a specific plot type, including available options and usage details.
+
+    Use this tool to retrieve the full docstring for a plot type, including generic and style options.
+    Equivalent to `hvplot.help(plot_type)` in the hvPlot API.
+
+    Parameters
+    ----------
+    ctx : Context
+        FastMCP context (automatically provided by the MCP framework).
+    plot_type : str
+        The type of plot to provide help for (e.g., 'line', 'scatter').
+    docstring : bool, default=True
+        Whether to include the docstring in the output.
+    generic : bool, default=True
+        Whether to include generic plotting options shared by all plot types.
+    style : str or bool, default=True
+        Plotting backend to use for style options. If True, automatically infers the backend.
+
+    Returns
+    -------
+    str
+        The docstring for the specified plot type, including all relevant options and usage information.
+
+    Examples
+    --------
+    >>> get_docstring(plot_type='line')
+    """
+    doc, _ = _help(plot_type=plot_type, docstring=docstring, generic=generic, style=style)
+    return doc
+
+
+@mcp.tool
+async def get_signature(
+    ctx: Context, plot_type: str, docstring: bool = True, generic: bool = True, style: Union[Literal["matplotlib", "bokeh", "plotly"], bool] = True
+) -> str:
+    """
+    Get the function signature for a specific hvPlot plot type.
+
+    Use this tool to retrieve the Python function signature for a plot type, showing all accepted arguments and their defaults.
+
+    Parameters
+    ----------
+    ctx : Context
+        FastMCP context (automatically provided by the MCP framework).
+    plot_type : str
+        The type of plot to provide help for (e.g., 'line', 'scatter').
+    docstring : bool, default=True
+        Whether to include the docstring in the output (ignored here, included for API compatibility).
+    generic : bool, default=True
+        Whether to include generic plotting options shared by all plot types (ignored here, included for API compatibility).
+    style : str or bool, default=True
+        Plotting backend to use for style options. If True, automatically infers the backend (ignored here).
+
+    Returns
+    -------
+    str
+        The function signature for the specified plot type.
+
+    Examples
+    --------
+    >>> get_signature(plot_type='line')
+    """
+    _, sig = _help(plot_type=plot_type, docstring=docstring, generic=generic, style=style)
+    return str(sig)
+
+
+if __name__ == "__main__":
+    mcp.run()

holoviz_mcp/panel_mcp/__init__.py

@@ -0,0 +1,17 @@
+"""
+Panel MCP Server Package.
+
+This package provides Model Context Protocol (MCP) tools for working with Panel,
+the Python library for creating interactive web applications and dashboards.
+
+The package includes:
+- Component discovery and introspection tools
+- Parameter information extraction
+- URL proxying utilities for remote environments
+- Data models for component metadata
+
+Main modules:
+- server: MCP server implementation with Panel-specific tools
+- data: Component metadata collection and utilities
+- models: Pydantic models for component information
+"""

holoviz_mcp/panel_mcp/data.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""
+Data collection module for Panel component metadata.
+
+This module provides functionality to collect metadata about Panel UI components,
+including their documentation, parameter schema, and module information. It supports
+collecting information from panel.viewable.Viewable subclasses across different
+Panel-related packages.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from panel.viewable import Viewable
+
+from .models import ComponentDetails
+from .models import ParameterInfo
+
+
+def find_all_subclasses(cls: type) -> set[type]:
+    """
+    Recursively find all subclasses of a given class.
+
+    This function performs a depth-first search through the class hierarchy
+    to find all classes that inherit from the given base class, either directly
+    or through inheritance chains.
+
+    Parameters
+    ----------
+    cls : type
+        The base class to find subclasses for.
+
+    Returns
+    -------
+    set[type]
+        Set of all subclasses found recursively, not including the base class itself.
+    """
+    subclasses = set()
+    for subclass in cls.__subclasses__():
+        subclasses.add(subclass)
+        subclasses.update(find_all_subclasses(subclass))
+    return subclasses
+
+
+def collect_component_info(cls: type) -> ComponentDetails:
+    """
+    Collect comprehensive information about a Panel component class.
+
+    Extracts metadata including docstring, parameter information, method signatures,
+    and other relevant details from a Panel component class. Handles parameter
+    introspection safely, converting non-serializable values appropriately.
+
+    Parameters
+    ----------
+    cls : type
+        The Panel component class to analyze.
+
+    Returns
+    -------
+    ComponentDetails
+        A complete model containing all collected component information.
+    """
+    # Extract docstring
+    docstring = cls.__doc__ if cls.__doc__ else ""
+
+    # Extract description (first sentence from docstring)
+    description = ""
+    if docstring:
+        # Clean the docstring and get first sentence
+        cleaned_docstring = docstring.strip()
+        if cleaned_docstring:
+            # Find first sentence ending with period, exclamation, or question mark
+            import re
+
+            sentences = re.split(r"[.!?]", cleaned_docstring)
+            if sentences:
+                description = sentences[0].strip()
+                # Remove leading/trailing whitespace and normalize spaces
+                description = " ".join(description.split())
+
+    # Extract parameters information
+    parameters = {}
+    if hasattr(cls, "param"):
+        for param_name in cls.param:
+            # Skip private parameters
+            if param_name.startswith("_"):
+                continue
+
+            param_obj = cls.param[param_name]
+            param_data = {}
+
+            # Get common parameter attributes (skip private ones)
+            for attr in ["default", "doc", "allow_None", "constant", "readonly", "per_instance"]:
+                if hasattr(param_obj, attr):
+                    value = getattr(param_obj, attr)
+                    # Handle non-JSON serializable values
+                    try:
+                        json.dumps(value)
+                        param_data[attr] = value
+                    except (TypeError, ValueError):
+                        param_data[attr] = "NON_JSON_SERIALIZABLE_VALUE"
+
+            # Get type-specific attributes
+            param_type = type(param_obj).__name__
+            param_data["type"] = param_type
+
+            # For Selector parameters, get options
+            if hasattr(param_obj, "objects"):
+                try:
+                    json.dumps(param_obj.objects)
+                    param_data["objects"] = param_obj.objects
+                except (TypeError, ValueError):
+                    param_data["objects"] = "NON_JSON_SERIALIZABLE_VALUE"
+
+            # For Number parameters, get bounds
+            if hasattr(param_obj, "bounds"):
+                try:
+                    json.dumps(param_obj.bounds)
+                    param_data["bounds"] = param_obj.bounds
+                except (TypeError, ValueError):
+                    param_data["bounds"] = "NON_JSON_SERIALIZABLE_VALUE"
+
+            # For String parameters, get regex
+            if hasattr(param_obj, "regex"):
+                try:
+                    json.dumps(param_obj.regex)
+                    param_data["regex"] = param_obj.regex
+                except (TypeError, ValueError):
+                    param_data["regex"] = "NON_JSON_SERIALIZABLE_VALUE"
+
+            # Create ParameterInfo model
+            parameters[param_name] = ParameterInfo(**param_data)
+
+    # Get __init__ method signature
+    init_signature = ""
+    if hasattr(cls, "__init__"):
+        try:
+            import inspect
+
+            sig = inspect.signature(cls.__init__)  # type: ignore[misc]
+            init_signature = str(sig)
+        except Exception as e:
+            init_signature = f"Error getting signature: {e}"
+
+    # Read reference guide content
+    # Create and return ComponentInfo model
+    return ComponentDetails(
+        name=cls.__name__,
+        description=description,
+        project=cls.__module__.split(".")[0],
+        module_path=f"{cls.__module__}.{cls.__name__}",
+        init_signature=init_signature,
+        docstring=docstring,
+        parameters=parameters,
+    )
+
+
+def get_components(parent=Viewable) -> list[ComponentDetails]:
+    """
+    Get detailed information about all Panel component subclasses.
+
+    Discovers all subclasses of the specified parent class (typically Viewable),
+    filters out private classes, and collects comprehensive metadata for each.
+    Results are sorted alphabetically by module path for consistency.
+
+    Parameters
+    ----------
+    parent : type, optional
+        The parent class to search for subclasses. Defaults to panel.viewable.Viewable.
+
+    Returns
+    -------
+    list[ComponentDetails]
+        List of detailed component information models, sorted by module path.
+    """
+    all_subclasses = find_all_subclasses(parent)
+
+    # Filter to only those in panel_material_ui package and exclude private classes
+    subclasses = [cls for cls in all_subclasses if not cls.__name__.startswith("_")]
+
+    # Collect component information
+    component_data = [collect_component_info(cls) for cls in subclasses]
+
+    # Sort by module_path for consistent ordering
+    component_data.sort(key=lambda x: x.module_path)
+    return component_data
+
+
+def save_components(data: list[ComponentDetails], filename: str) -> str:
+    """
+    Save component data to a JSON file.
+
+    Serializes a list of ComponentDetails objects to JSON format for persistence.
+    The JSON is formatted with indentation for human readability.
+
+    Parameters
+    ----------
+    data : list[ComponentDetails]
+        Component data to save, typically from get_components().
+    filename : str
+        Path where the JSON file should be created.
+
+    Returns
+    -------
+    str
+        Absolute path to the created file.
+    """
+    filepath = Path(filename)
+
+    # Convert Pydantic models to dict for JSON serialization
+    json_data = [component.model_dump() for component in data]
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        json.dump(json_data, f, indent=2, ensure_ascii=False)
+
+    return str(filepath)
+
+
+def load_components(filepath: str) -> list[ComponentDetails]:
+    """
+    Load component data from a JSON file.
+
+    Reads and deserializes component data that was previously saved using
+    save_components(). Validates the file exists before attempting to load.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the saved component data JSON file.
+
+    Returns
+    -------
+    list[ComponentDetails]
+        Loaded component data as Pydantic model instances.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    """
+    file_path = Path(filepath)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        json_data = json.load(f)
+
+    # Convert JSON data back to Pydantic models
+    return [ComponentDetails(**item) for item in json_data]
+
+
+def to_proxy_url(url: str, jupyter_server_proxy_url: str = "") -> str:
+    """
+    Convert localhost URLs to Jupyter server proxy URLs when applicable.
+
+    This function handles URL conversion for environments where localhost access
+    needs to be proxied (like JupyterHub, Binder, etc.). It supports both
+    'localhost' and '127.0.0.1' addresses and preserves paths and query parameters.
+
+    Parameters
+    ----------
+    url : str
+        The original URL to potentially convert. Can be any URL, but only
+        localhost and 127.0.0.1 URLs will be converted.
+    jupyter_server_proxy_url : str, optional
+        Base URL for the Jupyter server proxy. If None or empty, no conversion
+        is performed. Defaults to the configured proxy URL.
+
+    Returns
+    -------
+    str
+        The converted proxy URL if applicable, otherwise the original URL.
+        Proxy URLs maintain the original port, path, and query parameters.
+
+    Examples
+    --------
+    >>> to_proxy_url("http://localhost:5007/app")
+    "https://hub.example.com/user/alice/proxy/5007/app"
+
+    >>> to_proxy_url("https://external.com/page")
+    "https://external.com/page"  # No conversion for external URLs
+    """
+    if jupyter_server_proxy_url and jupyter_server_proxy_url.strip():
+        # Check if this is a localhost or 127.0.0.1 URL
+        if url.startswith("http://localhost:"):
+            # Parse the URL to extract port, path, and query
+            url_parts = url.replace("http://localhost:", "")
+        elif url.startswith("http://127.0.0.1:"):
+            # Parse the URL to extract port, path, and query
+            url_parts = url.replace("http://127.0.0.1:", "")
+        else:
+            # Not a local URL, return original
+            proxy_url = url
+            return proxy_url
+
+        # Find the port (everything before the first slash or end of string)
+        if "/" in url_parts:
+            port = url_parts.split("/", 1)[0]
+            path_and_query = "/" + url_parts.split("/", 1)[1]
+        else:
+            port = url_parts
+            path_and_query = "/"
+
+        # Validate that port is a valid number
+        if port and port.isdigit() and 1 <= int(port) <= 65535:
+            # Build the proxy URL
+            proxy_url = f"{jupyter_server_proxy_url}{port}{path_and_query}"
+        else:
+            # Invalid port, return original URL
+            proxy_url = url
+    else:
+        proxy_url = url
+    return proxy_url

holoviz_mcp/panel_mcp/models.py

@@ -0,0 +1,124 @@
+"""Pydantic models for Panel component metadata collection.
+
+This module defines the data models used to represent Panel UI component information,
+including parameter details, component summaries, and search results.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Optional
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+
+class ParameterInfo(BaseModel):
+    """
+    Information about a Panel component parameter.
+
+    This model captures parameter metadata including type, default value,
+    documentation, and type-specific attributes like bounds or options.
+    """
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields we don't know about
+
+    # Common attributes that most parameters have
+    type: str = Field(description="The type of the parameter, e.g., 'Parameter', 'Number', 'Selector'.")
+    default: Optional[Any] = Field(default=None, description="The default value for the parameter.")
+    doc: Optional[str] = Field(default=None, description="Documentation string for the parameter.")
+    # Optional attributes that may not be present
+    allow_None: Optional[bool] = Field(default=None, description="Whether the parameter accepts None values.")
+    constant: Optional[bool] = Field(default=None, description="Whether the parameter is constant (cannot be changed after initialization).")
+    readonly: Optional[bool] = Field(default=None, description="Whether the parameter is read-only.")
+    per_instance: Optional[bool] = Field(default=None, description="Whether the parameter is per-instance or shared across instances.")
+
+    # Type-specific attributes (will be present only for relevant parameter types)
+    objects: Optional[Any] = Field(default=None, description="Available options for Selector-type parameters.")
+    bounds: Optional[Any] = Field(default=None, description="Value bounds for Number-type parameters.")
+    regex: Optional[str] = Field(default=None, description="Regular expression pattern for String-type parameters.")
+
+
+class ComponentSummary(BaseModel):
+    """
+    High-level information about a Panel UI component.
+
+    This model provides a compact representation of a component without
+    detailed parameter information or docstrings. Used for listings and
+    quick overviews.
+    """
+
+    module_path: str = Field(description="Full module path of the component, e.g., 'panel.widgets.Button' or 'panel_material_ui.Button'.")
+    name: str = Field(description="Name of the component, e.g., 'Button' or 'TextInput'.")
+    project: str = Field(description="Project name of the component, e.g., 'panel' or 'panel_material_ui'.")
+    description: str = Field(description="Short description of the component's purpose and functionality.")
+
+
+class ComponentSummarySearchResult(ComponentSummary):
+    """
+    Component summary with search relevance scoring.
+
+    Extends ComponentSummary with a relevance score for search results,
+    allowing proper ranking and filtering of search matches.
+
+    """
+
+    relevance_score: int = Field(default=0, description="Relevance score for search results")
+
+    @classmethod
+    def from_component(cls, component: ComponentDetails, relevance_score: int) -> ComponentSummarySearchResult:
+        """
+        Create a search result from a component and relevance score.
+
+        Parameters
+        ----------
+        component : ComponentDetails
+            The component to create a search result from.
+        relevance_score : int
+            The relevance score (0-100) for this search result.
+
+        Returns
+        -------
+        ComponentSummarySearchResult
+            A search result summary of the component.
+        """
+        return cls(
+            module_path=component.module_path, name=component.name, project=component.project, description=component.description, relevance_score=relevance_score
+        )
+
+
+class ComponentDetails(ComponentSummary):
+    """
+    Complete information about a Panel UI component.
+
+    This model includes all available information about a component:
+    summary information, initialization signature, full docstring,
+    and detailed parameter specifications.
+
+    """
+
+    init_signature: str = Field(description="Signature of the component's __init__ method.")
+    docstring: str = Field(description="Docstring of the component, providing detailed information about its usage.")
+    parameters: dict[str, ParameterInfo] = Field(
+        description="Dictionary of parameters for the component, where keys are parameter names and values are ParameterInfo objects."
+    )
+
+    def to_base(self) -> ComponentSummary:
+        """
+        Convert to a basic component summary.
+
+        Strips away detailed information to create a lightweight
+        summary suitable for listings and overviews.
+
+        Returns
+        -------
+        ComponentSummary
+            A summary version of this component.
+        """
+        return ComponentSummary(
+            module_path=self.module_path,
+            name=self.name,
+            project=self.project,
+            description=self.description,
+        )