add user configuration

Author: MarcSkovMadsen

README.md

@@ -354,6 +354,48 @@ Install additional packages and restart the server to include them.
 
 </details>
 
+## ⚙️ User Configuration
+
+HoloViz MCP supports user configuration via a YAML file, allowing you to customize server behavior and documentation sources to fit your workflow.
+
+### Custom Configuration File
+
+You can provide a custom configuration file to override or extend the default settings. By default, configuration is loaded from `~/.holoviz-mcp/config.yaml`, but you can specify a different location using the `HOLOVIZ_MCP_USER_DIR` environment variable:
+
+```bash
+export HOLOVIZ_MCP_USER_DIR=/path/to/your/config_dir
+```
+
+### Adding Custom Documentation Repositories
+
+To add documentation from other libraries or your own projects, edit your configuration YAML and add entries under `docs.repositories`.
+
+#### Example: Adding Plotly and Altair Documentation
+
+```yaml
+docs:
+  repositories:
+    plotly:
+      url: "https://github.com/plotly/plotly.py.git"
+      branch: "main"
+      folders:
+        docs: {}
+      base_url: "https://plotly.com/python"
+    altair:
+      url: "https://github.com/altair-viz/altair.git"
+      branch: "main"
+      folders:
+        doc: {}
+      base_url: "https://altair-viz.github.io"
+```
+
+After updating your configuration:
+
+- update your index (`holoviz-mcp-update`)
+- restart the MCP server
+
+Your custom documentation repositories will now be available for search and reference within HoloViz MCP.
+
 ## 🔧 Troubleshooting
 
 ### Common Issues

src/holoviz_mcp/config/__init__.py

@@ -6,7 +6,6 @@
 from .loader import get_config_loader
 from .loader import reload_config
 from .models import DocsConfig
-from .models import EnvironmentConfig
 from .models import GitRepository
 from .models import HoloVizMCPConfig
 from .models import PromptConfig
@@ -23,7 +22,6 @@
     "reload_config",
     # Models
     "DocsConfig",
-    "EnvironmentConfig",
     "GitRepository",
     "HoloVizMCPConfig",
     "PromptConfig",

src/holoviz_mcp/config/loader.py

@@ -11,7 +11,6 @@
 import yaml
 from pydantic import ValidationError
 
-from .models import EnvironmentConfig
 from .models import HoloVizMCPConfig
 
 logger = logging.getLogger(__name__)
@@ -24,14 +23,16 @@ class ConfigurationError(Exception):
 class ConfigLoader:
     """Loads and manages HoloViz MCP configuration."""
 
-    def __init__(self, env_config: Optional[EnvironmentConfig] = None):
+    def __init__(self, config: Optional[HoloVizMCPConfig] = None):
         """Initialize configuration loader.
 
         Args:
-            env_config: Environment configuration. If None, loads from environment.
+            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 = env_config or EnvironmentConfig.from_environment()
-        self._config: Optional[HoloVizMCPConfig] = None
+        self._env_config = config
+        self._loaded_config: Optional[HoloVizMCPConfig] = None
 
     def load_config(self) -> HoloVizMCPConfig:
         """Load configuration from files and environment.
@@ -44,14 +45,20 @@ def load_config(self) -> HoloVizMCPConfig:
         ------
             ConfigurationError: If configuration cannot be loaded or is invalid.
         """
-        if self._config is not None:
-            return self._config
+        if self._loaded_config is not None:
+            return self._loaded_config
 
-        # Start with default configuration
+        # Get environment config (from parameter or environment)
+        if self._env_config is not None:
+            env_config = self._env_config
+        else:
+            env_config = HoloVizMCPConfig.from_environment()
+
+        # Start with default configuration dict
         config_dict = self._get_default_config()
 
         # Load from default config file if it exists
-        default_config_file = self.env_config.default_dir / "config.yaml"
+        default_config_file = env_config.default_dir / "config.yaml"
         if default_config_file.exists():
             try:
                 default_config = self._load_yaml_file(default_config_file)
@@ -61,22 +68,42 @@ def load_config(self) -> HoloVizMCPConfig:
                 logger.warning(f"Failed to load default config from {default_config_file}: {e}")
 
         # Load from user config file if it exists
-        user_config_file = self.env_config.config_file_path()
+        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)
 
-        # Validate and create configuration
+        # 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._config = HoloVizMCPConfig(**config_dict)
+            self._loaded_config = HoloVizMCPConfig(**config_dict)
         except ValidationError as e:
             raise ConfigurationError(f"Invalid configuration: {e}") from e
 
-        return self._config
+        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."""
@@ -190,23 +217,28 @@ def _apply_env_overrides(self, config: dict[str, Any]) -> dict[str, Any]:
 
     def get_repos_dir(self) -> Path:
         """Get the repository download directory."""
-        return self.env_config.repos_dir
+        config = self.load_config()
+        return config.repos_dir
 
     def get_resources_dir(self) -> Path:
         """Get the resources directory."""
-        return self.env_config.resources_dir()
+        config = self.load_config()
+        return config.resources_dir()
 
     def get_prompts_dir(self) -> Path:
         """Get the prompts directory."""
-        return self.env_config.prompts_dir()
+        config = self.load_config()
+        return config.prompts_dir()
 
     def get_best_practices_dir(self) -> Path:
         """Get the best practices directory."""
-        return self.env_config.best_practices_dir()
+        config = self.load_config()
+        return config.best_practices_dir()
 
     def create_default_user_config(self) -> None:
         """Create a default user configuration file."""
-        config_file = self.env_config.config_file_path()
+        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)
@@ -246,9 +278,13 @@ def reload_config(self) -> HoloVizMCPConfig:
         -------
             Reloaded configuration.
         """
-        self._config = None
+        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

src/holoviz_mcp/config/models.py

@@ -136,16 +136,21 @@ class ServerConfig(BaseModel):
     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: Optional[Path] = Field(default=None, description="Path to the Chroma vector database. If not set, defaults to <user_dir>/vector_db/chroma.")
+    vector_db_path: Path = Field(default_factory=lambda: Path.home() / ".holoviz-mcp" / "vector_db" / "chroma", description="Path to the Chroma vector database.")
 
-    def get_vector_db_path(self, user_dir: Path) -> Path:
-        """Return the resolved path to the Chroma vector database.
+    def resolve_vector_db_path(self, user_dir: Path) -> Path:
+        """Resolve the path to the Chroma vector database.
 
-        If vector_db_path is set, use it (expanduser). Otherwise, default to <user_dir>/vector_db/chroma.
+        This method ensures the vector_db_path is properly expanded.
+
+        Args:
+            user_dir: User directory (for compatibility, but not used since vector_db_path is now always set)
+
+        Returns
+        -------
+            Resolved path to the vector database
         """
-        if self.vector_db_path:
-            return Path(self.vector_db_path).expanduser()
-        return user_dir / "vector_db" / "chroma"
+        return Path(self.vector_db_path).expanduser()
 
 
 class HoloVizMCPConfig(BaseModel):
@@ -156,26 +161,29 @@ class HoloVizMCPConfig(BaseModel):
     resources: ResourceConfig = Field(default_factory=ResourceConfig)
     prompts: PromptConfig = Field(default_factory=PromptConfig)
 
-    model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
+    # Environment paths - merged from EnvironmentConfig with defaults
+    user_dir: Path = Field(default_factory=lambda: Path.home() / ".holoviz-mcp", description="User configuration directory")
+    default_dir: Path = Field(default_factory=lambda: Path(__file__).parent.parent / "config", description="Default configuration directory")
+    repos_dir: Path = Field(default_factory=lambda: Path.home() / ".holoviz-mcp" / "repos", description="Repository download directory")
 
-class EnvironmentConfig(BaseModel):
-    """Environment-based configuration paths."""
-
-    user_dir: Path = Field(description="User configuration directory")
-    default_dir: Path = Field(description="Default configuration directory")
-    repos_dir: Path = Field(description="Repository download directory")
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
 
     @classmethod
-    def from_environment(cls) -> EnvironmentConfig:
-        """Create configuration from environment variables."""
-        user_dir = Path(os.environ.get("HOLOVIZ_MCP_USER_DIR", Path.home() / ".config" / "holoviz-mcp"))
-
+    def from_environment(cls) -> HoloVizMCPConfig:
+        """Create configuration from environment variables with defaults."""
+        user_dir = Path(os.environ.get("HOLOVIZ_MCP_USER_DIR", Path.home() / ".holoviz-mcp"))
         default_dir = Path(os.environ.get("HOLOVIZ_MCP_DEFAULT_DIR", Path(__file__).parent.parent / "config"))
-
         repos_dir = Path(os.environ.get("HOLOVIZ_MCP_REPOS_DIR", user_dir / "repos"))
 
-        return cls(user_dir=user_dir, default_dir=default_dir, repos_dir=repos_dir)
+        return cls(
+            server=ServerConfig(),
+            docs=DocsConfig(),
+            resources=ResourceConfig(),
+            prompts=PromptConfig(),
+            user_dir=user_dir,
+            default_dir=default_dir,
+            repos_dir=repos_dir,
+        )
 
     def config_file_path(self, location: Literal["user", "default"] = "user") -> Path:
         """Get the path to the configuration file.

src/holoviz_mcp/config/resources/best-practices/panel.md

@@ -262,6 +262,10 @@ filtered = filtered[
 
 - DO arrange vertically when displaying `CheckButtonGroup` in a sidebar `CheckButtonGroup(..., vertical=True)`.
 
+### Tabulator
+
+- DO set `Tabulator.disabled=True` unless you would like the user to be able to edit the table.
+
 ## Plotting
 
 - DO use bar charts over pie Charts.