holoviz-mcp 0.0.1a0__py3-none-any.whl → 0.0.1a2__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/search.py

@@ -0,0 +1,314 @@
+"""A search application for exploring the HoloViz MCP docs_search tool."""
+
+import panel as pn
+import panel_material_ui as pmui
+import param
+
+from holoviz_mcp.docs_mcp.data import DocumentationIndexer
+from holoviz_mcp.docs_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://github.com/MarcSkovMadsen/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(
+            ("URL", pn.pane.HTML(self._url_view, sizing_mode="stretch_both", stylesheets=[URL_CSS])),
+            # Hack Column Scroll
+            ("CONTENT", pn.Column(pn.pane.Markdown(self._source_view, sizing_mode="stretch_width", stylesheets=[URL_CSS]), sizing_mode="stretch_both", scroll=True)),
+            ("DOCUMENT", 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 docs_search tool
+    """
+
+    title = param.String(default="HoloViz MCP Search Tool", 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"
+            js_code_to_open_holoviz_mcp = f"window.open('{href}', '_blank')"
+            github_button.js_on_click(code=js_code_to_open_holoviz_mcp)
+
+            return pmui.Page(
+                title=self.title,
+                site_url="./",
+                sidebar=[self._config, menu],
+                sidebar_width=400,
+                header=[pn.Row(about, about_button, github_button, align="end")],
+                main=[pmui.Container(DocumentView(document=menu.param.value), width_option="xl", sizing_mode="stretch_both")],
+                # logo="https://holoviz.org/_static/holoviz-logo-unstacked.svg",
+                # stylesheets=[".logo {background: white;border-radius: 5px;margin: 15px 15px 5px 10px;padding:7px}"],
+            )
+
+
+if pn.state.served:
+    pn.extension("codeeditor")
+    SearchApp().servable()

holoviz_mcp/config/__init__.py

@@ -0,0 +1,31 @@
+"""Configuration package for HoloViz MCP server."""
+
+from .loader import ConfigLoader
+from .loader import ConfigurationError
+from .loader import get_config
+from .loader import get_config_loader
+from .loader import reload_config
+from .models import DocsConfig
+from .models import GitRepository
+from .models import HoloVizMCPConfig
+from .models import PromptConfig
+from .models import ResourceConfig
+from .models import SecurityConfig
+from .models import ServerConfig
+
+__all__ = [
+    # Loader
+    "ConfigLoader",
+    "ConfigurationError",
+    "get_config",
+    "get_config_loader",
+    "reload_config",
+    # Models
+    "DocsConfig",
+    "GitRepository",
+    "HoloVizMCPConfig",
+    "PromptConfig",
+    "ResourceConfig",
+    "SecurityConfig",
+    "ServerConfig",
+]

holoviz_mcp/config/config.yaml

@@ -0,0 +1,167 @@
+# Default configuration for HoloViz MCP server
+# This file provides the default settings that are used when no user configuration is provided.
+
+server:
+  name: holoviz-mcp
+  version: "1.0.0"
+  description: "Model Context Protocol server for HoloViz ecosystem"
+  log_level: INFO
+  transport: stdio
+  anonymized_telemetry: false
+  jupyter_server_proxy_url: ""
+  security:
+    allow_code_execution: True
+
+docs:
+  repositories:
+    panel:
+      url: https://github.com/holoviz/panel.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+        examples/reference:
+          url_path: "/reference"
+      base_url: https://panel.holoviz.org
+      reference_patterns:
+        - "examples/reference/**/*.md"
+        - "examples/reference/**/*.ipynb"
+        - "examples/reference/**/*.rst"
+    panel-material-ui:
+      url: https://github.com/panel-extensions/panel-material-ui.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+        examples/reference:
+          url_path: "/reference"
+      base_url: https://panel-material-ui.holoviz.org/
+      reference_patterns:
+        - "examples/reference/**/*.md"
+        - "examples/reference/**/*.ipynb"
+        - "examples/reference/**/*.rst"
+    hvplot:
+      url: https://github.com/holoviz/hvplot.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+      base_url: https://hvplot.holoviz.org
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+    param:
+      url: https://github.com/holoviz/param.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+      base_url: https://param.holoviz.org
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+    holoviews:
+      url: https://github.com/holoviz/holoviews.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+        examples:
+          url_path: ""
+      base_url: https://holoviews.org
+      reference_patterns:
+        - "examples/reference/**/*.md"
+        - "examples/reference/**/*.ipynb"
+        - "examples/reference/**/*.rst"
+    holoviz:
+      url: https://github.com/holoviz/holoviz.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+        examples/tutorial:
+          url_path: "/tutorial"
+      base_url: https://holoviz.org
+      url_transform: "datashader"
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+    datashader:
+      url: https://github.com/holoviz/datashader.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+        examples:
+          url_path: ""
+      base_url: https://datashader.org
+      url_transform: "datashader"
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+    geoviews:
+      url: https://github.com/holoviz/geoviews.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+        examples:
+          url_path: "/"
+      base_url: https://geoviews.org
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+    colorcet:
+      url: https://github.com/holoviz/colorcet.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+      base_url: https://colorcet.holoviz.org
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+    lumen:
+      url: https://github.com/holoviz/lumen.git
+      branch: main
+      folders:
+        doc:
+          url_path: ""
+      base_url: https://lumen.holoviz.org
+      reference_patterns:
+        - "doc/reference/**/*.md"
+        - "doc/reference/**/*.ipynb"
+        - "doc/reference/**/*.rst"
+
+  index_patterns:
+    - "**/*.md"
+    - "**/*.ipynb"
+    - "**/*.rst"
+
+  exclude_patterns:
+    - "**/node_modules/**"
+    - "**/.git/**"
+    - "**/build/**"
+    - "**/__pycache__/**"
+    - "**/.pytest_cache/**"
+
+  max_file_size: 1048576  # 1MB
+  update_interval: 86400  # 24 hours
+
+resources:
+  search_paths: []  # Additional search paths for user resources
+  # Default search paths are automatically included:
+  # - Package default resources (src/holoviz_mcp/config/resources/)
+  # - User config resources (~/.holoviz_mcp/config/resources/)
+
+prompts:
+  search_paths: []  # Additional search paths for user prompts
+  # Default search paths are automatically included:
+  # - Package default prompts (src/holoviz_mcp/config/prompts/)
+  # - User config prompts (~/.holoviz_mcp/config/prompts/)