holoviz-mcp 0.4.0__py3-none-any.whl

holoviz_mcp/__init__.py

@@ -0,0 +1,18 @@
+"""Accessible imports for the holoviz_mcp package."""
+
+import importlib.metadata
+import warnings
+
+from holoviz_mcp.server import main
+from holoviz_mcp.server import mcp
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError as e:  # pragma: no cover
+    warnings.warn(f"Could not determine version of {__name__}\n{e!s}", stacklevel=2)
+    __version__ = "unknown"
+
+__all__: list[str] = ["mcp"]
+
+if __name__ == "__main__":
+    main()

holoviz_mcp/apps/__init__.py

@@ -0,0 +1 @@
+"""Here for technical reasons."""

holoviz_mcp/apps/configuration_viewer.py

@@ -0,0 +1,116 @@
+"""An app to view the holoviz-mcp configuration using Panel and Panel Material UI best practices.
+
+- Uses parameter-driven architecture for reactivity and maintainability
+- Uses a Panel template for layout and branding
+- Uses only Panel Material UI components for UI widgets
+- Separates config loading logic from UI logic
+- Responsive and modern design
+"""
+
+import json
+
+import panel as pn
+import panel_material_ui as pmui
+import param
+
+from holoviz_mcp.config.loader import HoloVizMCPConfig
+from holoviz_mcp.config.loader import get_config
+from holoviz_mcp.config.loader import get_config_loader
+
+pn.extension("jsoneditor")
+
+
+class ConfigViewer(param.Parameterized):
+    """
+    A Panel Material UI app for viewing holoviz-mcp configuration.
+
+    Features:
+        - Parameter-driven reactivity
+        - Modern, responsive UI using Panel Material UI
+        - Separation of config loading and UI logic
+        - Supports dark and light themes
+    """
+
+    config_source = param.Selector(objects=["Combined", "Default", "User"], default="Combined", doc="Which configuration to show")
+    dark_theme = param.Boolean(default=False, doc="Use dark theme for the JSON editor", allow_refs=True)
+
+    def __init__(self, **params):
+        """
+        Initialize the ConfigViewer.
+
+        Loads environment config and config loader.
+        """
+        super().__init__(**params)
+        self._env_config = HoloVizMCPConfig()
+        self._loader = get_config_loader()
+
+    @param.depends("config_source")
+    def _config_json(self):
+        """Get the selected configuration as a JSON string."""
+        if self.config_source == "Combined":
+            return get_config().model_dump_json(indent=2)
+        elif self.config_source == "Default":
+            default_config_file = self._env_config.default_dir / "config.yaml"
+            default_config = self._loader._load_yaml_file(default_config_file)
+            return json.dumps(default_config, indent=2)
+        elif self.config_source == "User":
+            user_config_file = self._env_config.user_dir / "config.yaml"
+            user_config = self._loader._load_yaml_file(user_config_file)
+            return json.dumps(user_config, indent=2)
+        return json.dumps({"error": "Unknown config source"}, indent=2)
+
+    @param.depends("dark_theme")
+    def _theme(self):
+        """Get the theme for the JSON editor ('dark' or 'light')."""
+        return "dark" if self.dark_theme else "light"
+
+    def view(self):
+        """Get the main view for the configuration viewer app."""
+        selector = pmui.RadioButtonGroup.from_param(
+            self.param.config_source,
+            color="primary",
+            orientation="horizontal",
+            sx={"mb": 2},
+        )
+        json_pane = pn.pane.JSON(
+            self._config_json,
+            name="holoviz-mcp config",
+            theme=self._theme,
+            sizing_mode="stretch_width",
+        )
+        card = pmui.Paper(
+            pmui.Column(
+                pmui.Typography(
+                    "HoloViz MCP Configuration Viewer",
+                    variant="h5",
+                    sx={"fontWeight": 700, "mb": 2},
+                ),
+                selector,
+                json_pane,
+            ),
+            elevation=3,
+            sx={"maxWidth": "900px", "margin": "auto", "padding": "32px"},
+        )
+        return pmui.Container(card)
+
+    def _update_source(self, selector):
+        """Update the config source from the selector widget."""
+        self.config_source = selector.value
+
+    @classmethod
+    def create_app(cls):
+        """Create and return the Panel Material UI app page."""
+        viewer = cls()
+        page = pmui.Page(
+            title="HoloViz MCP - Configuration Viewer",
+            main=[viewer.view()],
+            site_url="./",
+        )
+        viewer.dark_theme = page.param.dark_theme
+        return page
+
+
+if __name__ == "__main__":
+    ConfigViewer.create_app().show(port=5007, open=True, dev=True)
+elif pn.state.served:
+    ConfigViewer.create_app().servable()

holoviz_mcp/apps/holoviz_get_best_practices.py

@@ -0,0 +1,173 @@
+"""Panel app for exploring the HoloViz MCP holoviz_get_best_practices tool.
+
+Uses panel-material-ui widgets and Page layout.
+"""
+
+import panel as pn
+import panel_material_ui as pmui
+import param
+
+from holoviz_mcp.holoviz_mcp.data import get_best_practices
+from holoviz_mcp.holoviz_mcp.data import list_best_practices
+
+pn.extension()
+
+ABOUT = """
+## Best Practices Tool
+
+This tool provides best practices and guidelines for using HoloViz projects with Large Language Models (LLMs).
+
+### What Are Best Practices?
+
+Best practices are curated guidelines that help LLMs (and developers) write better code using HoloViz libraries. Each best practices document includes:
+
+- **Hello World Examples**: Annotated starter code showing proper usage patterns
+- **DO/DON'T Guidelines**: Clear rules for what to do and what to avoid
+- **Code Patterns**: Common idioms and recommended approaches
+- **LLM-Specific Guidance**: How to structure prompts and responses effectively
+
+### Available Projects
+
+This tool currently provides best practices for:
+
+- **panel**: Core Panel library for building web apps and dashboards
+- **panel-material-ui**: Material Design UI components for Panel applications
+- **holoviz**: General HoloViz ecosystem guidelines
+
+### How to Use
+
+Select a project in the sidebar to view its best practices.
+The content is displayed in Markdown format and includes code examples you can reference when building applications.
+
+### Learn More
+
+For more information about this project, including setup instructions and advanced configuration options,
+visit: [HoloViz MCP](https://marcskovmadsen.github.io/holoviz-mcp/).
+"""
+
+
+class BestPracticesConfiguration(param.Parameterized):
+    """
+    Configuration for the best practices viewer.
+
+    Parameters correspond to the project selection for viewing best practices.
+    """
+
+    project = param.Selector(
+        default=None,
+        objects=[],
+        doc="Select a project to view its best practices",
+    )
+
+    content = param.String(default="", doc="Markdown content of the selected best practices", precedence=-1)
+
+    def __init__(self, **params):
+        """Initialize the BestPracticesConfiguration with available projects."""
+        super().__init__(**params)
+        self._load_projects()
+
+        if pn.state.location:
+            pn.state.location.sync(self, parameters=["project"])
+
+    def _load_projects(self):
+        """Load available best practices projects."""
+        try:
+            projects = list_best_practices()
+            self.param.project.objects = projects
+            if projects and self.project is None:
+                self.project = projects[0]  # Default to first project
+        except Exception as e:
+            self.param.project.objects = []
+            self.content = f"**Error loading projects:** {e}"
+
+    @param.depends("project", watch=True, on_init=True)
+    def _update_content(self):
+        """Update content when project selection changes."""
+        if self.project is None or not isinstance(self.project, str):
+            self.content = "Please select a project to view its best practices."
+            return
+
+        try:
+            self.content = get_best_practices(str(self.project))
+        except FileNotFoundError as e:
+            self.content = f"**Error:** {e}"
+        except Exception as e:
+            self.content = f"**Error loading best practices:** {e}"
+
+
+class BestPracticesViewer(pn.viewable.Viewer):
+    """
+    A Panel Material UI app for viewing HoloViz best practices.
+
+    Features:
+        - Parameter-driven reactivity
+        - Modern, responsive UI using Panel Material UI
+        - Integration with HoloViz MCP holoviz_get_best_practices tool
+    """
+
+    title = param.String(default="HoloViz MCP - holoviz_get_best_practices Tool Demo", doc="Title of the best practices viewer")
+    config: BestPracticesConfiguration = param.Parameter(doc="Configuration for the best practices viewer")  # type: ignore
+
+    def __init__(self, **params):
+        """Initialize the BestPracticesViewer with default configuration."""
+        params["config"] = params.get("config", BestPracticesConfiguration())
+        super().__init__(**params)
+
+    def _config_panel(self):
+        """Create the configuration panel for the sidebar."""
+        return pmui.widgets.RadioButtonGroup.from_param(self.config.param.project, sizing_mode="stretch_width", orientation="vertical", button_style="outlined")
+
+    def __panel__(self):
+        """Create the Panel layout for the best practices viewer."""
+        with pn.config.set(sizing_mode="stretch_width"):
+            # About button and dialog
+            about_button = pmui.IconButton(
+                label="About",
+                icon="info",
+                description="Click to learn about the Best Practices Tool.",
+                sizing_mode="fixed",
+                color="light",
+                margin=(10, 0),
+            )
+            about = pmui.Dialog(ABOUT, close_on_click=True, width=0)
+            about_button.js_on_click(args={"about": about}, code="about.data.open = true")
+
+            # GitHub button
+            github_button = pmui.IconButton(
+                label="Github",
+                icon="star",
+                description="Give HoloViz-MCP a star on GitHub",
+                sizing_mode="fixed",
+                color="light",
+                margin=(10, 0),
+                href="https://github.com/MarcSkovMadsen/holoviz-mcp",
+                target="_blank",
+            )
+
+            return pmui.Page(
+                title=self.title,
+                site_url="./",
+                sidebar=[self._config_panel()],
+                sidebar_width=350,
+                header=[pn.Row(pn.Spacer(), about_button, github_button, align="end")],
+                main=[
+                    pmui.Container(
+                        about,
+                        pn.Column(
+                            pn.pane.Markdown(
+                                self.config.param.content,
+                                sizing_mode="stretch_both",
+                                styles={"padding": "20px"},
+                            ),
+                            scroll=True,
+                            sizing_mode="stretch_both",
+                        ),
+                        width_option="xl",
+                        sizing_mode="stretch_both",
+                    )
+                ],
+            )
+
+
+if pn.state.served:
+    BestPracticesViewer().servable()

holoviz_mcp/apps/holoviz_search.py

@@ -0,0 +1,319 @@
+"""A search application for exploring the HoloViz MCP holoviz_search tool."""
+
+import panel as pn
+import panel_material_ui as pmui
+import param
+
+from holoviz_mcp.holoviz_mcp.data import DocumentationIndexer
+from holoviz_mcp.holoviz_mcp.models import Document
+
+URL_CSS = """
+#url, .url {
+    display: inline-block;
+    margin-bottom: 8px;
+    border: 1.5px solid #e0e0e0;
+    border-radius: 10px;
+    overflow: hidden;
+    padding: 10px;
+    width: 100%;
+    margin-top: 10px;
+}
+#iframe {
+    height: calc(100% - 100px);
+    width: 100%;
+    border: 1.5px solid #e0e0e0;
+    border-radius: 10px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.07);
+    overflow: hidden;
+}
+"""
+
+ALL = "ALL"
+
+ABOUT = """
+## Documentation Search Tool
+
+This tool provides powerful semantic search capabilities across the extended HoloViz documentation.
+
+### Search Parameters
+
+- **`query`**: Your search text - the tool uses semantic similarity to find the most relevant documents
+- **`project`**: Filter results by specific project (e.g., "panel", "hvplot", "datashader") or search across all projects
+- **`max_results`**: Control the number of results returned (1-50 documents)
+- **`content`**: Choose whether to include full document content or just metadata for faster responses
+
+### What's Indexed
+
+By default, the complete HoloViz ecosystem documentation is indexed and searchable, including:
+
+- [Panel](https://panel.holoviz.org), [HvPlot](https://hvplot.holoviz.org), [Datashader](https://datashader.holoviz.org), [HoloViews](https://holoviews.org), [GeoViews](https://geoviews.org)
+- [Param](https://param.holoviz.org), [Colorcet](https://colorcet.holoviz.org), and core HoloViz guides
+
+The system is extensible and can be configured to include additional projects like Altair, Bokeh, Pandas, Plotly, Polars or even your own custom documentation.
+
+### Why Use This Tool?
+
+Unlike simple keyword search, this tool understands context and meaning, helping you discover relevant information even when you don't know the exact terminology used in the documentation.
+
+For LLMs this tool provides a structured way to access and retrieve relevant documentation, when using the HoloViz ecosystem.
+
+### Learn More
+
+For more information about this project, including setup instructions and advanced configuration options, visit: [HoloViz MCP](https://marcskovmadsen.github.io/holoviz-mcp/).
+"""  # noqa: E501
+
+
+@pn.cache
+def _get_indexer() -> DocumentationIndexer:
+    """Get or create the global DocumentationIndexer instance."""
+    return DocumentationIndexer()
+
+
+class SearchConfiguration(param.Parameterized):
+    """
+    Configuration for the search application.
+
+    Parameters correspond to the arguments of the search_documentation function.
+    """
+
+    query = param.String(default="What is HoloViz?", doc="Search text for semantic similarity search across the documentation")
+
+    project = param.Selector(
+        default=ALL,
+        objects=[ALL, "panel", "hvplot", "datashader", "holoviews", "geoviews", "param", "colorcet", "holoviz"],
+        doc="Filter results to a specific project. Select 'all' for all projects.",
+    )
+
+    max_results = param.Integer(default=5, bounds=(1, 50), doc="Maximum number of search results to return")
+
+    content = param.Boolean(
+        default=True, label="Include Full Content", doc="Include full document content in results. Disable for faster and simpler responses with metadata only."
+    )
+
+    search = param.Event(doc="Event to trigger search when parameters change")
+
+    results = param.List(item_type=Document, doc="Search results as a list of Documents", precedence=-1)
+
+    def __init__(self, **params):
+        """Initialize the SearchConfiguration with default values."""
+        super().__init__(**params)
+
+        if pn.state.location:
+            pn.state.location.sync(self, parameters=["query", "project", "content", "max_results"])
+
+        if self.query:
+            self.param.trigger("search")
+
+    @param.depends("search", watch=True)
+    async def _update_results(self):
+        indexer = _get_indexer()
+        project = self.project if self.project != ALL else None
+        self.results = await indexer.search(self.query, project=project, content=self.content, max_results=self.max_results)
+
+
+async def _update_projects(self):
+    self.config.param.project.objects = [ALL] + await _get_indexer().list_projects()  # Ensure indexer is initialized
+
+
+class DocumentsMenuList(pn.viewable.Viewer):
+    """
+    A Menu for selecting a Document.
+
+    This menu allows users to select a Document from a list of Documents.
+    """
+
+    value = param.ClassSelector(
+        default=None,
+        class_=Document,
+        allow_None=True,
+        doc="""
+        Last clicked Document.""",
+    )
+
+    documents = param.List(item_type=Document, doc="List of Documents to display in the menu", allow_refs=True)
+
+    def __panel__(self):
+        """Create the Panel layout."""
+        menu = pmui.MenuList(items=self._items)
+        pn.bind(self._update_value, menu.param.active, watch=True)
+        return menu
+
+    @param.depends("documents", watch=True)
+    def _reset_value(self):
+        """Reset the value when the documents change."""
+        if self.documents:
+            self.value = self.documents[0]
+        else:
+            self.value = None
+
+    def _update_value(self, event):
+        if event and self.documents:
+            index = event[0]
+            self.value = self.documents[index]
+        else:
+            self.value = None
+
+    @staticmethod
+    def _to_secondary(document: Document):
+        """Convert a Document to a secondary text for the menu item."""
+        return f"""{document.description}
+
+Relevance Score: {document.relevance_score or 'N/A':0.2f}
+"""
+
+    @param.depends("documents")
+    def _items(self):
+        return [
+            {"label": f"{index+1}. {document.project}: {document.title}", "icon": None, "secondary": self._to_secondary(document)}
+            for index, document in enumerate(self.documents)
+        ]
+
+
+class DocumentView(pn.viewable.Viewer):
+    """
+    A Panel Material UI view for displaying a single Document.
+
+    This view renders the content of a Document in a tabbed interface.
+    """
+
+    document = param.ClassSelector(class_=Document, doc="Document to display", allow_refs=True)
+
+    def __panel__(self):
+        """Create the Panel layout."""
+        return pmui.Tabs(
+            ("Human Readable View", pn.pane.HTML(self._url_view, sizing_mode="stretch_both", stylesheets=[URL_CSS])),
+            # Hack Column Scroll
+            (
+                "Markdown View",
+                pn.Column(pn.pane.Markdown(self._source_view, sizing_mode="stretch_width", stylesheets=[URL_CSS]), sizing_mode="stretch_both", scroll=True),
+            ),
+            ("Raw Response", pn.Column(pn.pane.JSON(self._json_view, sizing_mode="stretch_both"), scroll=True)),
+            dynamic=True,
+        )
+
+    @param.depends("document")
+    def _js_copy_url_to_clipboard(self):
+        return f"navigator.clipboard.writeText('{self._url()}');"
+
+    @param.depends("document")
+    def _url(self):
+        """Get the URL of the document."""
+        if not self.document:
+            return ""
+        url = self.document.url
+        return f"[{url}]({url})"
+
+    @param.depends("document")
+    def _source_url(self):
+        """Get the source URL of the document."""
+        if not self.document:
+            return ""
+        return f"[{self.document.source_url}]({self.document.source_url})"
+
+    @param.depends("document")
+    def _json_view(self):
+        """Create a JSON view for the document."""
+        if not self.document:
+            return None
+        return self.document.model_dump_json()
+
+    @param.depends("document")
+    def _source_view(self):
+        """Create a source view for the document."""
+        if not self.document:
+            return "No document selected."
+        if not self.document.content:
+            return "No content available for this document."
+        if self.document.source_path.endswith(".rst"):
+            language = "restructuredtext"
+        else:
+            language = "markdown"
+
+        return f"""
+<a class="url" href="{self.document.source_url}" target="_blank">{self.document.source_url}</a>
+
+`````{language}
+{self.document.content}
+`````
+"""
+
+    @param.depends("document")
+    def _url_view(self):
+        """Create a URL view for the document."""
+        if not self.document:
+            return "No document selected."
+        if not self.document.url:
+            return "No URL available for this document."
+
+        return f"""\
+    <a id="url" href="{self.document.url}" target="_blank">{self.document.url}</a>
+    <iframe id="iframe" src="{self.document.url}"></iframe>
+    """
+
+
+class SearchApp(pn.viewable.Viewer):
+    """
+    A Panel Material UI app for searching HoloViz MCP documentation.
+
+    Features:
+        - Parameter-driven reactivity
+        - Modern, responsive UI using Panel Material UI
+        - Integration with HoloViz MCP holoviz_search tool
+    """
+
+    title = param.String(default="HoloViz MCP - holoviz_search Tool Demo", doc="Title of the search app")
+    config = param.ClassSelector(class_=SearchConfiguration, doc="Configuration for the search app")
+
+    def __init__(self, **params):
+        """Initialize the SearchApp with default configuration."""
+        params["config"] = params.get("config", SearchConfiguration())
+        super().__init__(**params)
+
+    async def _config(self):
+        await _update_projects(self)
+
+        with pn.config.set(sizing_mode="stretch_width"):
+            return pn.Param(
+                self.config,
+                name="Search",
+                widgets={
+                    "query": {"type": pmui.TextAreaInput, "rows": 3, "placeholder": "Enter search query ..."},
+                    "search": {"type": pmui.Button, "label": "Search", "button_type": "primary"},
+                },
+            )
+
+    def __panel__(self):
+        """Create the Panel layout for the search app."""
+        with pn.config.set(sizing_mode="stretch_width"):
+            menu = DocumentsMenuList(documents=self.config.param.results)
+
+            about_button = pmui.IconButton(
+                label="About", icon="info", description="Click to learn about the Search Tool.", sizing_mode="fixed", color="light", margin=(10, 0)
+            )
+            about = pmui.Dialog(ABOUT, close_on_click=True, width=0)
+            about_button.js_on_click(args={"about": about}, code="about.data.open = true")
+
+            github_button = pmui.IconButton(
+                label="Github",
+                icon="star",
+                description="Give HoloViz-MCP a star on GitHub",
+                sizing_mode="fixed",
+                color="light",
+                margin=(10, 0),
+                href="https://github.com/MarcSkovMadsen/holoviz-mcp",
+                target="_blank",
+            )
+
+            return pmui.Page(
+                title=self.title,
+                site_url="./",
+                sidebar=[self._config, menu],
+                sidebar_width=400,
+                header=[pn.Row(pn.Spacer(), about_button, github_button, align="end")],
+                main=[pmui.Container(about, DocumentView(document=menu.param.value), width_option="xl", sizing_mode="stretch_both")],
+            )
+
+
+if pn.state.served:
+    pn.extension("codeeditor")
+    SearchApp().servable()