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

holoviz_mcp/config/loader.py

@@ -0,0 +1,308 @@
+"""Configuration loader for HoloViz MCP server."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+from typing import Optional
+
+import yaml
+from pydantic import ValidationError
+
+from .models import HoloVizMCPConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigurationError(Exception):
+    """Raised when configuration cannot be loaded or is invalid."""
+
+
+class ConfigLoader:
+    """Loads and manages HoloViz MCP configuration."""
+
+    def __init__(self, config: Optional[HoloVizMCPConfig] = None):
+        """Initialize configuration loader.
+
+        Args:
+            config: Pre-configured HoloVizMCPConfig with environment paths.
+                   If None, loads paths from environment. Configuration will
+                   still be loaded from files even if this is provided.
+        """
+        self._env_config = config
+        self._loaded_config: Optional[HoloVizMCPConfig] = None
+
+    def load_config(self) -> HoloVizMCPConfig:
+        """Load configuration from files and environment.
+
+        Returns
+        -------
+            Loaded configuration.
+
+        Raises
+        ------
+            ConfigurationError: If configuration cannot be loaded or is invalid.
+        """
+        if self._loaded_config is not None:
+            return self._loaded_config
+
+        # Get environment config (from parameter or environment)
+        if self._env_config is not None:
+            env_config = self._env_config
+        else:
+            env_config = HoloVizMCPConfig()
+
+        # Start with default configuration dict
+        config_dict = self._get_default_config()
+
+        # Load from default config file if it exists
+        default_config_file = env_config.default_dir / "config.yaml"
+        if default_config_file.exists():
+            try:
+                default_config = self._load_yaml_file(default_config_file)
+                config_dict = self._merge_configs(config_dict, default_config)
+                logger.info(f"Loaded default configuration from {default_config_file}")
+            except Exception as e:
+                logger.warning(f"Failed to load default config from {default_config_file}: {e}")
+
+        # Load from user config file if it exists
+        user_config_file = env_config.config_file_path()
+        if user_config_file.exists():
+            user_config = self._load_yaml_file(user_config_file)
+            # Filter out any unknown fields to prevent validation errors
+            user_config = self._filter_known_fields(user_config)
+            config_dict = self._merge_configs(config_dict, user_config)
+            logger.info(f"Loaded user configuration from {user_config_file}")
+
+        # Apply environment variable overrides
+        config_dict = self._apply_env_overrides(config_dict)
+
+        # Add the environment paths to the config dict
+        config_dict.update(
+            {
+                "user_dir": env_config.user_dir,
+                "default_dir": env_config.default_dir,
+                "repos_dir": env_config.repos_dir,
+            }
+        )
+
+        # Create the final configuration
+        try:
+            self._loaded_config = HoloVizMCPConfig(**config_dict)
+        except ValidationError as e:
+            raise ConfigurationError(f"Invalid configuration: {e}") from e
+
+        return self._loaded_config
+
+    def _filter_known_fields(self, config_dict: dict[str, Any]) -> dict[str, Any]:
+        """Filter out unknown fields that aren't part of the HoloVizMCPConfig schema.
+
+        This prevents validation errors when loading user config files that might
+        contain extra fields.
+        """
+        known_fields = {"server", "docs", "resources", "prompts", "user_dir", "default_dir", "repos_dir"}
+        return {k: v for k, v in config_dict.items() if k in known_fields}
+
+    def _get_default_config(self) -> dict[str, Any]:
+        """Get default configuration dictionary."""
+        return {
+            "server": {
+                "name": "holoviz-mcp",
+                "version": "1.0.0",
+                "description": "Model Context Protocol server for HoloViz ecosystem",
+                "log_level": "INFO",
+                "security": {"allow_code_execution": True},
+            },
+            "docs": {
+                "repositories": {},  # No more Python-side defaults!
+                "index_patterns": ["**/*.md", "**/*.rst", "**/*.txt"],
+                "exclude_patterns": ["**/node_modules/**", "**/.git/**", "**/build/**"],
+                "max_file_size": 1024 * 1024,  # 1MB
+                "update_interval": 86400,  # 24 hours
+            },
+            "resources": {"search_paths": []},
+            "prompts": {"search_paths": []},
+        }
+
+    def _load_yaml_file(self, file_path: Path) -> dict[str, Any]:
+        """Load YAML file safely.
+
+        Args:
+            file_path: Path to YAML file.
+
+        Returns
+        -------
+            Parsed YAML content.
+
+        Raises
+        ------
+            ConfigurationError: If file cannot be loaded or parsed.
+        """
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = yaml.safe_load(f)
+                if content is None:
+                    return {}
+                if not isinstance(content, dict):
+                    raise ConfigurationError(f"Configuration file must contain a YAML dictionary: {file_path}")
+                return content
+        except yaml.YAMLError as e:
+            raise ConfigurationError(f"Invalid YAML in {file_path}: {e}") from e
+        except Exception as e:
+            raise ConfigurationError(f"Failed to load {file_path}: {e}") from e
+
+    def _merge_configs(self, base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+        """Merge two configuration dictionaries recursively.
+
+        Args:
+            base: Base configuration.
+            override: Override configuration.
+
+        Returns
+        -------
+            Merged configuration.
+        """
+        result = base.copy()
+
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._merge_configs(result[key], value)
+            else:
+                result[key] = value
+
+        return result
+
+    def _apply_env_overrides(self, config: dict[str, Any]) -> dict[str, Any]:
+        """Apply environment variable overrides to configuration.
+
+        Args:
+            config: Configuration dictionary.
+
+        Returns
+        -------
+            Configuration with environment overrides applied.
+        """
+        # Log level override
+        if "HOLOVIZ_MCP_LOG_LEVEL" in os.environ:
+            config.setdefault("server", {})["log_level"] = os.environ["HOLOVIZ_MCP_LOG_LEVEL"]
+
+        # Server name override
+        if "HOLOVIZ_MCP_SERVER_NAME" in os.environ:
+            config.setdefault("server", {})["name"] = os.environ["HOLOVIZ_MCP_SERVER_NAME"]
+
+        # Transport override
+        if "HOLOVIZ_MCP_TRANSPORT" in os.environ:
+            config.setdefault("server", {})["transport"] = os.environ["HOLOVIZ_MCP_TRANSPORT"]
+
+        # Telemetry override
+        if "ANONYMIZED_TELEMETRY" in os.environ:
+            config.setdefault("server", {})["anonymized_telemetry"] = os.environ["ANONYMIZED_TELEMETRY"].lower() in ("true", "1", "yes", "on")
+
+        # Jupyter proxy URL override
+        if "JUPYTER_SERVER_PROXY_URL" in os.environ:
+            config.setdefault("server", {})["jupyter_server_proxy_url"] = os.environ["JUPYTER_SERVER_PROXY_URL"]
+
+        # Security configuration override
+        if "HOLOVIZ_MCP_ALLOW_CODE_EXECUTION" in os.environ:
+            config.setdefault("server", {}).setdefault("security", {})["allow_code_execution"] = os.environ["HOLOVIZ_MCP_ALLOW_CODE_EXECUTION"].lower() in (
+                "true",
+                "1",
+                "yes",
+                "on",
+            )
+
+        return config
+
+    def get_repos_dir(self) -> Path:
+        """Get the repository download directory."""
+        config = self.load_config()
+        return config.repos_dir
+
+    def get_resources_dir(self) -> Path:
+        """Get the resources directory."""
+        config = self.load_config()
+        return config.resources_dir()
+
+    def get_prompts_dir(self) -> Path:
+        """Get the prompts directory."""
+        config = self.load_config()
+        return config.prompts_dir()
+
+    def get_best_practices_dir(self) -> Path:
+        """Get the best practices directory."""
+        config = self.load_config()
+        return config.best_practices_dir()
+
+    def create_default_user_config(self) -> None:
+        """Create a default user configuration file."""
+        config = self.load_config()
+        config_file = config.config_file_path()
+
+        # Create directories if they don't exist
+        config_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Don't overwrite existing config
+        if config_file.exists():
+            logger.info(f"Configuration file already exists: {config_file}")
+            return
+
+        # Create default configuration
+        template = {
+            "server": {"name": "holoviz-mcp", "log_level": "INFO", "security": {"allow_code_execution": True}},
+            "docs": {
+                "repositories": {
+                    "example-repo": {
+                        "url": "https://github.com/example/repo.git",
+                        "branch": "main",
+                        "folders": {"doc": {"url_path": ""}},
+                        "base_url": "https://example.readthedocs.io",
+                        "reference_patterns": ["doc/reference/**/*.md", "examples/reference/**/*.ipynb"],
+                    }
+                }
+            },
+            "resources": {"search_paths": []},
+            "prompts": {"search_paths": []},
+        }
+
+        with open(config_file, "w", encoding="utf-8") as f:
+            yaml.dump(template, f, default_flow_style=False, sort_keys=False)
+
+        logger.info(f"Created default user configuration file: {config_file}")
+
+    def reload_config(self) -> HoloVizMCPConfig:
+        """Reload configuration from files.
+
+        Returns
+        -------
+            Reloaded configuration.
+        """
+        self._loaded_config = None
+        return self.load_config()
+
+    def clear_cache(self) -> None:
+        """Clear the cached configuration to force reload on next access."""
+        self._loaded_config = None
+
+
+# Global configuration loader instance
+_config_loader: Optional[ConfigLoader] = None
+
+
+def get_config_loader() -> ConfigLoader:
+    """Get the global configuration loader instance."""
+    global _config_loader
+    if _config_loader is None:
+        _config_loader = ConfigLoader()
+    return _config_loader
+
+
+def get_config() -> HoloVizMCPConfig:
+    """Get the current configuration."""
+    return get_config_loader().load_config()
+
+
+def reload_config() -> HoloVizMCPConfig:
+    """Reload configuration from files."""
+    return get_config_loader().reload_config()

holoviz_mcp/config/models.py

@@ -0,0 +1,216 @@
+"""Configuration models for HoloViz MCP server."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+from typing import Optional
+from typing import Union
+
+from pydantic import AnyHttpUrl
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import PositiveInt
+from pydantic import field_validator
+
+
+def _holoviz_mcp_user_dir() -> Path:
+    """Get the default user directory for HoloViz MCP."""
+    return Path(os.environ.get("HOLOVIZ_MCP_USER_DIR", Path.home() / ".holoviz-mcp"))
+
+
+def _holoviz_mcp_default_dir() -> Path:
+    """Get the default configuration directory for HoloViz MCP."""
+    return Path(os.environ.get("HOLOVIZ_MCP_DEFAULT_DIR", Path(__file__).parent.parent / "config"))
+
+
+class FolderConfig(BaseModel):
+    """Configuration for a folder within a repository."""
+
+    url_path: str = Field(default="", description="URL path mapping for this folder (e.g., '' for root, '/reference' for reference docs)")
+
+
+class GitRepository(BaseModel):
+    """Configuration for a Git repository."""
+
+    url: AnyHttpUrl = Field(..., description="Git repository URL")
+    branch: Optional[str] = Field(default=None, description="Git branch to use")
+    tag: Optional[str] = Field(default=None, description="Git tag to use (e.g., '1.7.2')")
+    commit: Optional[str] = Field(default=None, description="Git commit hash to use")
+    folders: Union[list[str], dict[str, FolderConfig]] = Field(
+        default_factory=lambda: {"doc": FolderConfig()},
+        description="Folders to index within the repository. Can be a list of folder names or a dict mapping folder names to FolderConfig objects",
+    )
+    base_url: AnyHttpUrl = Field(..., description="Base URL for documentation links")
+    url_transform: Literal["holoviz", "plotly", "datashader"] = Field(
+        default="holoviz",
+        description="""How to transform file path into URL:
+
+        - holoViz transform suffix to .html: filename.md -> filename.html
+        - plotly transform suffix to /: filename.md -> filename/
+        - datashader removes leading index and transform suffix to .html: 01_filename.md -> filename.html
+        """,
+    )
+    reference_patterns: list[str] = Field(
+        default_factory=lambda: ["examples/reference/**/*.md", "examples/reference/**/*.ipynb"], description="Glob patterns for reference documentation files"
+    )
+
+    @field_validator("tag")
+    @classmethod
+    def validate_tag(cls, v):
+        """Validate git tag format, allowing both 'v1.2.3' and '1.2.3' formats."""
+        if v is not None and v.startswith("v"):
+            # Allow tags like 'v1.7.2' but also suggest plain version numbers
+            pass
+        return v
+
+    @field_validator("folders")
+    @classmethod
+    def validate_folders(cls, v):
+        """Validate and normalize folders configuration."""
+        if isinstance(v, list):
+            # Convert list to dict format for backward compatibility
+            return {folder: FolderConfig() for folder in v}
+        elif isinstance(v, dict):
+            # Ensure all values are FolderConfig objects
+            result = {}
+            for folder, config in v.items():
+                if isinstance(config, dict):
+                    result[folder] = FolderConfig(**config)
+                elif isinstance(config, FolderConfig):
+                    result[folder] = config
+                else:
+                    raise ValueError(f"Invalid folder config for '{folder}': must be dict or FolderConfig")
+            return result
+        else:
+            raise ValueError("folders must be a list or dict")
+
+    def get_folder_names(self) -> list[str]:
+        """Get list of folder names for backward compatibility."""
+        if isinstance(self.folders, dict):
+            return list(self.folders.keys())
+        return self.folders
+
+    def get_folder_url_path(self, folder_name: str) -> str:
+        """Get URL path for a specific folder."""
+        if isinstance(self.folders, dict):
+            folder_config = self.folders.get(folder_name)
+            if folder_config:
+                return folder_config.url_path
+        return ""
+
+
+class DocsConfig(BaseModel):
+    """Configuration for documentation repositories."""
+
+    repositories: dict[str, GitRepository] = Field(default_factory=dict, description="Dictionary mapping package names to repository configurations")
+    index_patterns: list[str] = Field(
+        default_factory=lambda: ["**/*.md", "**/*.rst", "**/*.txt"], description="File patterns to include when indexing documentation"
+    )
+    exclude_patterns: list[str] = Field(
+        default_factory=lambda: ["**/node_modules/**", "**/.git/**", "**/build/**"], description="File patterns to exclude when indexing documentation"
+    )
+    max_file_size: PositiveInt = Field(
+        default=1024 * 1024,  # 1MB
+        description="Maximum file size in bytes to index",
+    )
+    update_interval: PositiveInt = Field(
+        default=86400,  # 24 hours
+        description="How often to check for updates in seconds",
+    )
+
+
+class ResourceConfig(BaseModel):
+    """Configuration for resources (best practices, etc.)."""
+
+    search_paths: list[Path] = Field(default_factory=list, description="Additional paths to search for resources")
+
+
+class PromptConfig(BaseModel):
+    """Configuration for prompts."""
+
+    search_paths: list[Path] = Field(default_factory=list, description="Additional paths to search for prompts")
+
+
+class SecurityConfig(BaseModel):
+    """Security configuration for code execution."""
+
+    allow_code_execution: bool = Field(
+        default=True,
+        description="Allow LLM to execute arbitrary code. " "This can be dangerous and should only be enabled in trusted environments.",
+    )
+
+
+class ServerConfig(BaseModel):
+    """Configuration for the MCP server."""
+
+    name: str = Field(default="holoviz-mcp", description="Server name")
+    version: str = Field(default="1.0.0", description="Server version")
+    description: str = Field(default="Model Context Protocol server for HoloViz ecosystem", description="Server description")
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(default="INFO", description="Logging level")
+    transport: Literal["stdio", "http"] = Field(default="stdio", description="Transport protocol for MCP communication")
+    anonymized_telemetry: bool = Field(default=False, description="Enable anonymized telemetry")
+    jupyter_server_proxy_url: str = Field(default="", description="Jupyter server proxy URL for Panel app integration")
+    security: SecurityConfig = Field(default_factory=SecurityConfig, description="Security configuration")
+    vector_db_path: Path = Field(
+        default_factory=lambda: (_holoviz_mcp_user_dir() / "vector_db" / "chroma").expanduser(), description="Path to the Chroma vector database."
+    )
+
+
+class HoloVizMCPConfig(BaseModel):
+    """Main configuration for HoloViz MCP server."""
+
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    docs: DocsConfig = Field(default_factory=DocsConfig)
+    resources: ResourceConfig = Field(default_factory=ResourceConfig)
+    prompts: PromptConfig = Field(default_factory=PromptConfig)
+
+    # Environment paths - merged from EnvironmentConfig with defaults
+    user_dir: Path = Field(default_factory=_holoviz_mcp_user_dir, description="User configuration directory")
+    default_dir: Path = Field(default_factory=_holoviz_mcp_default_dir, description="Default configuration directory")
+    repos_dir: Path = Field(default_factory=lambda: _holoviz_mcp_user_dir() / "repos", description="Repository download directory")
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    def config_file_path(self, location: Literal["user", "default"] = "user") -> Path:
+        """Get the path to the configuration file.
+
+        Args:
+            location: Whether to get user or default config file path
+        """
+        if location == "user":
+            return self.user_dir / "config.yaml"
+        else:
+            return self.default_dir / "config.yaml"
+
+    def resources_dir(self, location: Literal["user", "default"] = "user") -> Path:
+        """Get the path to the resources directory.
+
+        Args:
+            location: Whether to get user or default resources directory
+        """
+        if location == "user":
+            return self.user_dir / "config" / "resources"
+        else:
+            return self.default_dir / "resources"
+
+    def prompts_dir(self, location: Literal["user", "default"] = "user") -> Path:
+        """Get the path to the prompts directory.
+
+        Args:
+            location: Whether to get user or default prompts directory
+        """
+        if location == "user":
+            return self.user_dir / "config" / "prompts"
+        else:
+            return self.default_dir / "prompts"
+
+    def best_practices_dir(self, location: Literal["user", "default"] = "user") -> Path:
+        """Get the path to the best practices directory.
+
+        Args:
+            location: Whether to get user or default best practices directory
+        """
+        return self.resources_dir(location) / "best-practices"

holoviz_mcp/config/resources/best-practices/hvplot.md

@@ -0,0 +1,62 @@
+# hvPlot
+
+## General Guidelines
+
+- Always import hvplot for your data backend:
+
+```python
+import hvplot.pandas # will add .hvplot namespace to Pandas dataframes
+import hvplot.polars # will add .hvplot namespace to Polars dataframes
+...
+```
+
+- Prefer Bokeh > Plotly > Matplotlib plotting backend for interactivity
+- DO use bar charts over pie Charts. Pie charts are not supported.
+- DO use NumeralTickFormatter and 'a' formatter for axis formatting:
+
+| Input | Format String | Output |
+| - |  - | - |
+| 1230974 | '0.0a' | 1.2m |
+| 1460 | '0 a' | 1 k |
+| -104000 | '0a' | -104k |
+
+## Developing
+
+When developing a hvplot please serve it for development using Panel:
+
+```python
+import pandas as pd
+import hvplot.pandas  # noqa
+import panel as pn
+
+import numpy as np
+
+np.random.seed(42)
+dates = pd.date_range("2022-08-01", periods=30, freq="B")
+open_prices = np.cumsum(np.random.normal(100, 2, size=len(dates)))
+high_prices = open_prices + np.random.uniform(1, 5, size=len(dates))
+low_prices = open_prices - np.random.uniform(1, 5, size=len(dates))
+close_prices = open_prices + np.random.uniform(-3, 3, size=len(dates))
+
+data = pd.DataFrame({
+    "open": open_prices.round(2),
+    "high": high_prices.round(2),
+    "low": low_prices.round(2),
+    "close": close_prices.round(2),
+}, index=dates)
+
+
+# Create a scatter plot of date vs close price
+scatter_plot = data.hvplot.scatter(x="index", y="close", grid=True, title="Close Price Scatter Plot", xlabel="Date", ylabel="Close Price")
+
+
+# Create a Panel app
+app = pn.Column("# Close Price Scatter Plot", scatter_plot)
+
+if pn.state.served:
+    app.servable()
+```
+
+```bash
+panel serve plot.py --dev
+```