diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000..dfa370d Binary files /dev/null and b/docs/assets/logo.png differ diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg deleted file mode 100644 index a52f13c..0000000 --- a/docs/assets/logo.svg +++ /dev/null @@ -1,157 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/examples.md b/docs/examples.md deleted file mode 100644 index 755e73e..0000000 --- a/docs/examples.md +++ /dev/null @@ -1,13 +0,0 @@ -# Examples - -```{.python pycafe-embed pycafe-embed-style="border: 1px solid #e6e6e6; border-radius: 8px;" pycafe-embed-width="100%" pycafe-embed-height="400px" pycafe-embed-scale="1.0"} -import panel as pn -pn.extension() - -x_slider = pn.widgets.IntSlider(name='x', start=0, end=100) - -def apply_square(x): - return f'{x} squared is {x**2}' - -pn.Row(x_slider, pn.bind(apply_square, x_slider)) -``` diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index 65b2004..fa40c37 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md @@ -249,4 +249,4 @@ Planned enhancements: - [Available Tools](tools.md): Details on each tool - [Security Considerations](security.md): Security details -- [Configuration](../how-to/configuration.md): Configuration options +- [Configuration](../how-to/configure-settings.md): Configuration options diff --git a/docs/explanation/display-server.md b/docs/explanation/display-system.md similarity index 100% rename from docs/explanation/display-server.md rename to docs/explanation/display-system.md diff --git a/docs/explanation/security.md b/docs/explanation/security.md index 0cbc3e1..cd5e7bd 100644 --- a/docs/explanation/security.md +++ b/docs/explanation/security.md @@ -269,5 +269,5 @@ Planned improvements: ## Related Documentation - [Architecture](architecture.md): System design -- [Configuration](../how-to/configuration.md): Security settings -- [Docker Guide](../how-to/docker.md): Container security +- [Configuration](../how-to/configure-settings.md): Security settings +- [Docker Production Guide](../how-to/docker-production.md): Container security diff --git a/docs/explanation/tools.md b/docs/explanation/tools.md index 1b0ab52..1aa8085 100644 --- a/docs/explanation/tools.md +++ b/docs/explanation/tools.md @@ -316,6 +316,6 @@ Find relevant information: ## Related Documentation - [Architecture](architecture.md): How tools are implemented -- [Configuration](../how-to/configuration.md): Configure tool behavior +- [Configuration](../how-to/configure-settings.md): Configure tool behavior - [Security Considerations](security.md): Security implications - [Serve Apps](../how-to/serve-apps.md): Serve Panel apps locally diff --git a/docs/how-to/add-custom-docs.md b/docs/how-to/add-custom-docs.md new file mode 100644 index 0000000..18dffcc --- /dev/null +++ b/docs/how-to/add-custom-docs.md @@ -0,0 +1,254 @@ +# Add Custom Documentation + +This guide shows you how to add documentation from other libraries or your own projects to HoloViz MCP. + +## Prerequisites + +- HoloViz MCP installed ([Installation guide](install-uv.md)) +- Configuration file location: `~/.holoviz-mcp/config.yaml` + +## Overview + +You can extend HoloViz MCP to index and search documentation from: + +- Other Python visualization libraries (Plotly, Altair, Matplotlib, etc.) +- Your organization's internal libraries +- Project-specific documentation + +The documentation must be: + +- Hosted in a Git repository +- Written in Markdown, ReST or Jupyter notebook format +- Accessible (public or with credentials) + +## Add Documentation Repository + +### Example: Add Plotly Documentation + +Edit `~/.holoviz-mcp/config.yaml`: + +```yaml +docs: + repositories: + plotly: + url: "https://github.com/plotly/plotly.py.git" + base_url: "https://plotly.com/python" + target_suffix: "plotly" +``` + +**Configuration fields:** + +- **url**: Git repository URL containing the documentation +- **base_url**: Base URL for the live documentation site +- **target_suffix**: Identifier used in internal paths (optional) + +### Example: Add Altair Documentation + +```yaml +docs: + repositories: + altair: + url: "https://github.com/altair-viz/altair.git" + base_url: "https://altair-viz.github.io" +``` + +### Example: Add Multiple Libraries + +```yaml +docs: + repositories: + plotly: + url: "https://github.com/plotly/plotly.py.git" + base_url: "https://plotly.com/python" + target_suffix: "plotly" + altair: + url: "https://github.com/altair-viz/altair.git" + base_url: "https://altair-viz.github.io" + matplotlib: + url: "https://github.com/matplotlib/matplotlib.git" + base_url: "https://matplotlib.org" +``` + +### Example: Add Private Repository + +For private repositories, use SSH URLs with proper credentials: + +```yaml +docs: + repositories: + internal-lib: + url: "git@github.com:myorg/internal-docs.git" + base_url: "https://docs.myorg.com" +``` + +Ensure your SSH keys are configured for Git access. + +## Update Documentation Index + +After adding or modifying repositories, update the index: + +```bash +holoviz-mcp update index +``` + +This will: + +1. Clone or pull the repositories +2. Extract Markdown documentation +3. Build the search index +4. Make the documentation available to your AI assistant + +**Note**: The first index update can take several minutes depending on the size of the documentation. + +## Verify Documentation Added + +Test that your AI assistant can access the new documentation: + +1. **List projects**: + + ```text + List available HoloViz documentation projects + ``` + +2. **Search the documentation**: + + ```text + Search for "scatter plot" in Plotly documentation + ``` + +3. **Use in code generation**: + + ```text + Create a Plotly scatter plot with custom colors + ``` + +If successful, the AI assistant will reference the added documentation in responses. + +## Documentation Structure Requirements + +### Required Structure + +For best results, your documentation should follow this structure: + +``` +docs/ +├── index.md +├── getting-started/ +│ └── installation.md +├── reference/ +│ └── api.md +└── tutorials/ + └── basic-usage.md +``` + +### Markdown Requirements + +- Use standard Markdown syntax +- Include clear headings (`#`, `##`, `###`) +- Code blocks with language tags (` ```python `) +- Relative links to other documentation pages + +### Example: Custom Project Documentation + +```yaml +docs: + repositories: + my-project: + url: "https://github.com/myorg/my-project.git" + base_url: "https://myproject.readthedocs.io" +``` + +Your repository should contain a `docs/` directory with Markdown files. + +## Troubleshooting + +### Repository Clone Failed + +**Check the URL** is correct and accessible: + +```bash +git clone +``` + +**For private repositories**, ensure SSH keys are configured: + +```bash +ssh -T git@github.com +``` + +### Index Update Taking Too Long + +**Large repositories** can take time to index. The process is: + +1. Cloning/pulling repositories +2. Parsing Markdown files +3. Building embeddings +4. Creating search index + +**Check progress** by setting debug logging in your IDE configuration: + +```json +{ + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } +} +``` + +Then run: + +```bash +holoviz-mcp update index +``` + +### Documentation Not Appearing in Search + +**Verify the index was updated**: + +```bash +ls ~/.holoviz-mcp +``` + +You should see database files. + +**Check the repository structure** - ensure Markdown files are in a `docs/` directory or root. + +**Restart your IDE/AI assistant** after updating the index. + +### Invalid Configuration + +**Verify YAML syntax**: + +```bash +cat ~/.holoviz-mcp/config.yaml +``` + +Use proper indentation (2 spaces, no tabs). + +**Test configuration**: + +```bash +holoviz-mcp serve +``` + +Check for error messages. + +## Remove Custom Documentation + +To remove a documentation source: + +1. **Edit** `~/.holoviz-mcp/config.yaml` and remove the repository entry + +2. **Update the index**: + + ```bash + holoviz-mcp update index + ``` + +3. **Restart your IDE/AI assistant** + +## Next Steps + +- [Configure Settings](configure-settings.md): Customize other HoloViz MCP behavior +- [Update HoloViz MCP](update-holoviz-mcp.md): Keep the server up to date +- [Troubleshooting](troubleshooting.md): Fix common issues diff --git a/docs/how-to/configuration.md b/docs/how-to/configuration.md deleted file mode 100644 index 41c2987..0000000 --- a/docs/how-to/configuration.md +++ /dev/null @@ -1,251 +0,0 @@ -# Configuration - -This guide explains how to customize HoloViz MCP behavior through configuration files and environment variables. - -## Configuration File - -HoloViz MCP uses a YAML configuration file located at: - -```bash -~/.holoviz-mcp/config.yaml -``` - -### Custom Configuration Directory - -Set a custom configuration directory using an environment variable: - -```bash -export HOLOVIZ_MCP_USER_DIR=/path/to/your/config -``` - -### Configuration Schema - -A JSON schema is provided for validation and editor autocompletion: - -```yaml -# yaml-language-server: $schema=https://raw.githubusercontent.com/MarcSkovMadsen/holoviz-mcp/refs/heads/main/src/holoviz_mcp/config/schema.json - -# Your configuration here -``` - -This enables real-time validation and autocompletion in VS Code with the [vscode-yaml](https://github.com/redhat-developer/vscode-yaml) extension. - -## Environment Variables - -### Server Configuration - -**HOLOVIZ_MCP_TRANSPORT** -Transport mode for the server. -Values: `stdio`, `http` -Default: `stdio` - -```bash -HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp -``` - -**HOLOVIZ_MCP_HOST** -Host address to bind to (HTTP transport only). -Default: `127.0.0.1` - -```bash -HOLOVIZ_MCP_HOST=0.0.0.0 HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp -``` - -**HOLOVIZ_MCP_PORT** -Port to bind to (HTTP transport only). -Default: `8000` - -```bash -HOLOVIZ_MCP_PORT=9000 HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp -``` - -**HOLOVIZ_MCP_LOG_LEVEL** -Server logging level. -Values: `DEBUG`, `INFO`, `WARNING`, `ERROR` -Default: `INFO` - -```bash -HOLOVIZ_MCP_LOG_LEVEL=DEBUG holoviz-mcp -``` - -**HOLOVIZ_MCP_SERVER_NAME** -Override the server name. -Default: `holoviz-mcp` - -### Remote Development - -**JUPYTER_SERVER_PROXY_URL** -URL prefix for Panel apps when running remotely. - -```bash -JUPYTER_SERVER_PROXY_URL=/proxy/5007/ holoviz-mcp -``` - -This is useful when running in JupyterHub or similar environments. - -### Documentation Configuration - -**ANONYMIZED_TELEMETRY** -Enable or disable Chroma telemetry. -Values: `true`, `false` -Default: `false` - -```bash -ANONYMIZED_TELEMETRY=true holoviz-mcp -``` - -### Display Server Configuration - -The Display Server can run in two modes: - -#### Subprocess Mode (Default) - -In subprocess mode, the MCP server automatically manages the Display Server: - -```yaml -display: - enabled: true - mode: subprocess # Default - port: 5005 - host: "127.0.0.1" - max_restarts: 3 -``` - -The Display Server starts automatically when the MCP server starts. No manual setup required. - -#### Remote Mode - -In remote mode, connect to an independently running Display Server: - -```bash -# Start Display Server manually in a separate terminal -display-server - -# Or specify custom port -display-server --port 5004 -``` - -Configure the MCP server to connect to it in `~/.holoviz-mcp/config.yaml`: - -```yaml -display: - enabled: true - mode: remote - server_url: "http://127.0.0.1:5005" # Match your display-server URL -``` - -The Display Server has its own environment variables (see `display-server --help`): - -- `PORT`: Server port (default: 5005) -- `ADDRESS`: Server host (default: 127.0.0.1) -- `DISPLAY_DB_PATH`: Database path - -**Example: Remote Display Server on Another Machine** - -If the Display Server is running on another machine: - -```yaml -display: - enabled: true - mode: remote - server_url: "http://192.168.1.100:5005" -``` - -**Example: Disable Display Tool** - -To disable the display tool entirely: - -```yaml -display: - enabled: false -``` - -## Adding Custom Documentation - -You can add documentation from other libraries or your own projects. - -### Example: Add Plotly Documentation - -Edit `~/.holoviz-mcp/config.yaml`: - -```yaml -docs: - repositories: - plotly: - url: "https://github.com/plotly/plotly.py.git" - base_url: "https://plotly.com/python" - target_suffix: "plotly" -``` - -### Example: Add Altair Documentation - -```yaml -docs: - repositories: - altair: - url: "https://github.com/altair-viz/altair.git" - base_url: "https://altair-viz.github.io" -``` - -### Update Documentation Index - -After adding repositories, update the index: - -```bash -holoviz-mcp update index -``` - -## IDE-Specific Configuration - -### VS Code Configuration - -Set environment variables in `mcp.json`: - -```json -{ - "servers": { - "holoviz": { - "type": "stdio", - "command": "holoviz-mcp", - "env": { - "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" - } - } - } -} -``` - -### Claude Desktop Configuration - -```json -{ - "mcpServers": { - "holoviz": { - "command": "holoviz-mcp", - "env": { - "HOLOVIZ_MCP_LOG_LEVEL": "INFO" - } - } - } -} -``` - -## Docker Configuration - -See the [Docker Guide](docker.md) for Docker-specific configuration options. - -## Configuration Viewer - -HoloViz MCP includes a built-in configuration viewer. Run: - -```bash -holoviz-mcp serve -``` - -Navigate to the Configuration Viewer tool to see your current configuration. - -## Next Steps - -- [Updates & Maintenance](updates.md): Keep HoloViz MCP up to date -- [Security Considerations](../explanation/security.md): Understand security implications -- [Troubleshooting](troubleshooting.md): Fix configuration issues diff --git a/docs/how-to/configure-claude-code.md b/docs/how-to/configure-claude-code.md new file mode 100644 index 0000000..4cdcbf9 --- /dev/null +++ b/docs/how-to/configure-claude-code.md @@ -0,0 +1,164 @@ +# Configure HoloViz MCP for Claude Code + +This guide shows you how to configure HoloViz MCP with Claude Code (the command-line interface). + +## Prerequisites + +- Claude Code CLI installed ([Installation guide](https://claude.ai/download)) +- HoloViz MCP installed ([Installation guide](install-uv.md)) + +## Add the MCP Server + +Configure HoloViz MCP globally for your user: + +```bash +claude mcp add holoviz --transport stdio --scope user -- holoviz-mcp +``` + +This will update your `~/.claude.json` file with the HoloViz MCP server configuration. + +## Verify the Configuration + +Check that the server is configured: + +```bash +claude mcp list +``` + +You should see `holoviz` in the list of configured MCP servers. + +In Claude Code, you can also run the `/mcp` command to verify the status: + +```bash +claude /mcp +``` + +![Claude Code HoloViz MCP](../assets/images/claude-code-holoviz-mcp.png) + +## Test Your Configuration + +Test the configuration by asking Claude about Panel components: + +1. **Simple Query**: + + ```text + List available Panel input components + ``` + +2. **Detailed Query**: + + ```text + What parameters does the Panel TextInput component have? + ``` + +3. **Code Generation**: + + ```text + Create a simple Panel dashboard with a slider and save it to app.py + ``` + +If Claude provides detailed, accurate responses with specific Panel component information, your configuration is working! 🎉 + +## Advanced Configuration + +### Set Log Level + +To enable debug logging, edit your `~/.claude.json` file manually: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +### Custom Configuration Directory + +Use a custom directory for configuration and data: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_USER_DIR": "/path/to/custom/dir" + } + } + } +} +``` + +## Troubleshooting + +### Server Not Found + +**Check that holoviz-mcp is installed**: + +```bash +holoviz-mcp --version +``` + +**Verify the MCP server is configured**: + +```bash +claude mcp list +``` + +### Claude Not Recognizing Components + +1. **Verify documentation index exists**: + + ```bash + ls ~/.holoviz-mcp + ``` + +2. **Recreate the index**: + + ```bash + holoviz-mcp update index + ``` + +3. **Test the server directly**: + + ```bash + holoviz-mcp + ``` + +### Configuration File Issues + +**Check the configuration file**: + +```bash +cat ~/.claude.json +``` + +**Verify JSON syntax** - ensure there are no trailing commas or syntax errors. + +### Permission Errors + +**Linux/macOS**: Ensure the configuration file is readable: + +```bash +chmod 644 ~/.claude.json +``` + +## Remove the Configuration + +To remove the HoloViz MCP server from Claude Code: + +```bash +claude mcp remove holoviz +``` + +## Next Steps + +- **[Getting Started Tutorial](../tutorials/getting-started-claude-code.md)**: Complete walkthrough for Claude Code +- **[Configuration Options](configure-settings.md)**: Customize HoloViz MCP behavior +- **[Troubleshooting Guide](troubleshooting.md)**: Fix common issues diff --git a/docs/how-to/configure-claude-desktop.md b/docs/how-to/configure-claude-desktop.md new file mode 100644 index 0000000..87ac699 --- /dev/null +++ b/docs/how-to/configure-claude-desktop.md @@ -0,0 +1,193 @@ +# Configure HoloViz MCP for Claude Desktop + +This guide shows you how to configure HoloViz MCP with Claude Desktop application. + +## Prerequisites + +- Claude Desktop installed ([Download](https://claude.ai/download)) +- HoloViz MCP installed ([Installation guide](install-uv.md)) + +## Locate Your Configuration File + +Find your Claude Desktop configuration file: + +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **Linux**: `~/.config/Claude/claude_desktop_config.json` + +## Add the MCP Server + +1. Open the configuration file in a text editor +2. Add this configuration: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp" + } + } +} +``` + +3. Save the file +4. Restart Claude Desktop + +!!! tip "Existing Configuration" + If your file already has other MCP servers configured, add `"holoviz"` to the existing `mcpServers` object: + + ```json + { + "mcpServers": { + "existing-server": { + "command": "existing-command" + }, + "holoviz": { + "command": "holoviz-mcp" + } + } + } + ``` + +## Verify the Connection + +After restarting Claude Desktop: + +1. Look for the MCP indicator (🔌) in the interface +2. It should show "holoviz" as a connected server + +If you don't see the indicator, check the troubleshooting section below. + +## Test Your Configuration + +Test the configuration by asking Claude about Panel components: + +1. **Simple Query**: + + ``` + List available Panel input components + ``` + +2. **Detailed Query**: + + ``` + What parameters does the Panel TextInput component have? + ``` + +3. **Code Generation**: + + ``` + Create a simple Panel dashboard with a slider + ``` + +If Claude provides detailed, accurate responses with specific Panel component information, your configuration is working! 🎉 + +## Advanced Configuration + +### Set Log Level + +For debugging, increase the log level: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +### Custom Configuration Directory + +Use a custom directory for configuration and data: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_USER_DIR": "/path/to/custom/dir" + } + } + } +} +``` + +## Troubleshooting + +### MCP Indicator Not Showing + +**Check the configuration file path** - ensure you edited the correct file for your operating system. + +**Verify JSON syntax** - ensure there are no trailing commas, missing quotes, or other syntax errors. + +**Restart Claude Desktop completely** - quit and reopen the application. + +### Server Not Starting + +**Check that holoviz-mcp is installed**: + +```bash +holoviz-mcp --version +``` + +**Test the server directly**: + +```bash +holoviz-mcp +``` + +Press `Ctrl+C` to stop it. + +### Claude Not Recognizing Components + +1. **Verify documentation index exists**: + + ```bash + ls ~/.holoviz-mcp + ``` + +2. **Recreate the index**: + + ```bash + holoviz-mcp update index + ``` + +3. **Restart Claude Desktop** + +### Configuration File Not Found + +**Create the directory** if it doesn't exist: + +```bash +# macOS +mkdir -p ~/Library/Application\ Support/Claude + +# Linux +mkdir -p ~/.config/Claude + +# Windows (PowerShell) +New-Item -Path "$env:APPDATA\Claude" -ItemType Directory -Force +``` + +**Create the file** with the configuration above. + +### Permission Errors + +**Linux/macOS**: Ensure the configuration file is readable: + +```bash +chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json # macOS +chmod 644 ~/.config/Claude/claude_desktop_config.json # Linux +``` + +## Next Steps + +- **[Getting Started Tutorial](../tutorials/getting-started-claude-desktop.md)**: Complete walkthrough for Claude Desktop +- **[Configuration Options](configure-settings.md)**: Customize HoloViz MCP behavior +- **[Troubleshooting Guide](troubleshooting.md)**: Fix common issues diff --git a/docs/how-to/configure-cursor.md b/docs/how-to/configure-cursor.md new file mode 100644 index 0000000..7db2181 --- /dev/null +++ b/docs/how-to/configure-cursor.md @@ -0,0 +1,152 @@ +# Configure HoloViz MCP for Cursor + +This guide shows you how to configure HoloViz MCP with Cursor IDE. + +## Prerequisites + +- Cursor IDE installed ([Download](https://cursor.sh/)) +- HoloViz MCP installed ([Installation guide](install-uv.md)) + +## Quick Install + +Click the button below to open Cursor's MCP settings directly: + +[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square)](cursor://settings/mcp) + +Then follow the Manual Configuration steps below. + +## Manual Configuration + +1. Open Cursor Settings +2. Navigate to `Features` → `Model Context Protocol` +3. Click `Add Server` +4. Enter the configuration: + +```json +{ + "name": "holoviz", + "command": "holoviz-mcp" +} +``` + +5. Save the configuration +6. Restart Cursor + +## Test Your Configuration + +Test the configuration with Cursor's AI: + +1. **Simple Query** - Open Cursor's AI chat and ask: + + ``` + List available Panel input components + ``` + +2. **Detailed Query** - Ask for specific information: + + ``` + What parameters does the Panel TextInput component have? + ``` + +3. **Code Generation** - Ask Cursor AI to generate code: + + ``` + Create a simple Panel dashboard with a slider + ``` + +If Cursor's AI provides detailed, accurate responses with specific Panel component information, your configuration is working! 🎉 + +## Advanced Configuration + +### Set Log Level + +For debugging, increase the log level in your Cursor MCP settings: + +```json +{ + "name": "holoviz", + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } +} +``` + +### Custom Configuration Directory + +Use a custom directory for configuration and data: + +```json +{ + "name": "holoviz", + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_USER_DIR": "/path/to/custom/dir" + } +} +``` + +## Troubleshooting + +### Server Not Showing in Cursor + +**Verify JSON syntax** - ensure there are no trailing commas or syntax errors. + +**Restart Cursor** after adding the configuration. + +**Check MCP settings** - navigate to `Features` → `Model Context Protocol` to verify the server is listed. + +### Server Not Starting + +**Check that holoviz-mcp is installed**: + +```bash +holoviz-mcp --version +``` + +**Test the server directly**: + +```bash +holoviz-mcp +``` + +Press `Ctrl+C` to stop it. + +### Cursor AI Not Recognizing Components + +1. **Verify documentation index exists**: + + ```bash + ls ~/.holoviz-mcp + ``` + +2. **Recreate the index**: + + ```bash + holoviz-mcp update index + ``` + +3. **Restart Cursor** + +### Configuration Not Saving + +**Check Cursor version** - ensure you have the latest version that supports MCP. + +**Manually edit configuration** - if the UI isn't working, you may need to manually edit Cursor's configuration file. + +## Working with Cursor + +Cursor provides several ways to interact with AI: + +- **Cmd/Ctrl + K**: Open inline AI editor to modify code +- **Cmd/Ctrl + L**: Open AI chat panel +- **@-mentions**: Reference files and code in your prompts +- **Tab to accept**: AI suggestions appear inline as you type + +When asking about Panel or HoloViz, Cursor will use the HoloViz MCP server to provide accurate, up-to-date information! + +## Next Steps + +- **[Getting Started Tutorial](../tutorials/getting-started-cursor.md)**: Complete walkthrough for Cursor +- **[Configuration Options](configure-settings.md)**: Customize HoloViz MCP behavior +- **[Troubleshooting Guide](troubleshooting.md)**: Fix common issues diff --git a/docs/how-to/configure-display-server.md b/docs/how-to/configure-display-server.md new file mode 100644 index 0000000..1d2d81b --- /dev/null +++ b/docs/how-to/configure-display-server.md @@ -0,0 +1,221 @@ +# Configure Display Server + +This guide shows you how to configure the Display Server, which enables AI assistants to display Python visualizations in your browser. + +## Prerequisites + +- HoloViz MCP installed ([Installation guide](install-uv.md)) +- Basic understanding of the Display System ([Tutorial](../tutorials/display-system.md)) + +## Display Server Modes + +The Display Server can run in two modes: + +- **Subprocess Mode** (default): MCP server automatically manages the Display Server +- **Remote Mode**: Connect to an independently running Display Server + +## Subprocess Mode (Default) + +In subprocess mode, the Display Server starts automatically when the MCP server starts. This is the easiest option. + +### Configuration + +Edit `~/.holoviz-mcp/config.yaml`: + +```yaml +display: + enabled: true + mode: subprocess # Default + port: 5005 + host: "127.0.0.1" + max_restarts: 3 +``` + +### Configuration Options + +- **enabled**: Enable or disable the display tool (default: `true`) +- **mode**: Server mode - `subprocess` or `remote` (default: `subprocess`) +- **port**: Port number for the Display Server (default: `5005`) +- **host**: Host address to bind to (default: `"127.0.0.1"`) +- **max_restarts**: Maximum automatic restarts on failure (default: `3`) + +No manual setup required - the Display Server starts automatically. + +## Remote Mode + +In remote mode, you run the Display Server independently and configure the MCP server to connect to it. This is useful for: + +- Running the Display Server on a different machine +- Running multiple MCP servers connected to one Display Server +- Custom Display Server configurations + +### Step 1: Start Display Server Manually + +In a separate terminal: + +```bash +# Start Display Server on default port 5005 +display-server + +# Or specify custom port +display-server --port 5004 +``` + +Keep this terminal open. + +### Step 2: Configure MCP Server + +Edit `~/.holoviz-mcp/config.yaml`: + +```yaml +display: + enabled: true + mode: remote + server_url: "http://127.0.0.1:5005" # Match your display-server URL +``` + +### Step 3: Restart Your IDE/AI Assistant + +Restart your IDE or AI assistant to apply the configuration. + +## Display Server Environment Variables + +The Display Server has its own environment variables (see `display-server --help`): + +- **PORT**: Server port (default: `5005`) +- **ADDRESS**: Server host (default: `127.0.0.1`) +- **DISPLAY_DB_PATH**: Database path for storing visualizations + +Example: + +```bash +PORT=5004 ADDRESS=0.0.0.0 display-server +``` + +## Advanced Configurations + +### Remote Display Server on Another Machine + +If the Display Server is running on another machine: + +```yaml +display: + enabled: true + mode: remote + server_url: "http://192.168.1.100:5005" +``` + +Make sure: +- The Display Server is accessible over the network +- Firewall allows connections to the port +- Consider security implications of exposing the Display Server + +### Disable Display Tool + +To disable the display tool entirely: + +```yaml +display: + enabled: false +``` + +The MCP server will not provide the `holoviz_display` tool. + +### Custom Subprocess Configuration + +Run Display Server on a different port in subprocess mode: + +```yaml +display: + enabled: true + mode: subprocess + port: 5010 + host: "127.0.0.1" + max_restarts: 5 +``` + +## Troubleshooting + +### Display Server Not Starting + +**Check the configuration file**: + +```bash +cat ~/.holoviz-mcp/config.yaml +``` + +**Verify YAML syntax** - ensure proper indentation and no syntax errors. + +**Check the logs** - set log level to DEBUG in your IDE configuration: + +```json +{ + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } +} +``` + +### Port Already in Use + +If port 5005 is already in use, either: + +1. **Change the port** in your config: + + ```yaml + display: + enabled: true + port: 5006 + ``` + +2. **Find and stop the process** using port 5005: + + ```bash + # On Linux/macOS + lsof -ti:5005 | xargs kill -9 + + # On Windows + netstat -ano | findstr :5005 + ``` + +### Cannot Connect to Remote Display Server + +**Verify Display Server is running**: + +```bash +curl http://127.0.0.1:5005/health +``` + +Should return `{"status":"ok"}`. + +**Check the server URL** in your config matches the Display Server address. + +**Check firewall settings** if connecting to a remote machine. + +### Visualizations Not Displaying + +**Verify display tool is enabled** - ask your AI assistant: + +``` +List available MCP tools +``` + +You should see `holoviz_display` in the list. + +**Check Display Server health**: + +```bash +curl http://127.0.0.1:5005/health +``` + +**Restart both servers**: + +1. Stop the Display Server (Ctrl+C) +2. Restart your IDE/AI assistant +3. Start Display Server again (if using remote mode) + +## Next Steps + +- [Display System Tutorial](../tutorials/display-system.md): Learn how to use the display tool +- [Display System Concepts](../explanation/display-system.md): Understand the architecture +- [Troubleshooting Guide](troubleshooting.md): Fix common issues diff --git a/docs/how-to/configure-settings.md b/docs/how-to/configure-settings.md new file mode 100644 index 0000000..02779a3 --- /dev/null +++ b/docs/how-to/configure-settings.md @@ -0,0 +1,201 @@ +# Configure Settings + +This guide shows you how to customize HoloViz MCP behavior through the configuration file and environment variables. + +## Prerequisites + +- HoloViz MCP installed ([Installation guide](install-uv.md)) + +## Configuration File Location + +HoloViz MCP uses a YAML configuration file: + +```bash +~/.holoviz-mcp/config.yaml +``` + +### Use Custom Configuration Directory + +Set a custom configuration directory: + +```bash +export HOLOVIZ_MCP_USER_DIR=/path/to/your/config +``` + +Then restart your IDE/AI assistant. + +## Configuration Schema + +Enable validation and autocompletion by adding this line to your config: + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/MarcSkovMadsen/holoviz-mcp/refs/heads/main/src/holoviz_mcp/config/schema.json + +# Your configuration here +``` + +This enables real-time validation in VS Code with the [vscode-yaml](https://github.com/redhat-developer/vscode-yaml) extension. + +## Environment Variables + +### Server Configuration + +**HOLOVIZ_MCP_TRANSPORT** +Transport mode for the server. +Values: `stdio`, `http` +Default: `stdio` + +```bash +HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp +``` + +**HOLOVIZ_MCP_HOST** +Host address to bind to (HTTP transport only). +Default: `127.0.0.1` + +```bash +HOLOVIZ_MCP_HOST=0.0.0.0 HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp +``` + +**HOLOVIZ_MCP_PORT** +Port to bind to (HTTP transport only). +Default: `8000` + +```bash +HOLOVIZ_MCP_PORT=9000 HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp +``` + +**HOLOVIZ_MCP_LOG_LEVEL** +Server logging level. +Values: `DEBUG`, `INFO`, `WARNING`, `ERROR` +Default: `INFO` + +```bash +HOLOVIZ_MCP_LOG_LEVEL=DEBUG holoviz-mcp +``` + +**HOLOVIZ_MCP_SERVER_NAME** +Override the server name. +Default: `holoviz-mcp` + +### Remote Development + +**JUPYTER_SERVER_PROXY_URL** +URL prefix for Panel apps when running remotely. + +```bash +JUPYTER_SERVER_PROXY_URL=/proxy/5007/ holoviz-mcp +``` + +Use this when running in JupyterHub or similar environments. + +### Documentation Configuration + +**ANONYMIZED_TELEMETRY** +Enable or disable Chroma telemetry. +Values: `true`, `false` +Default: `false` + +```bash +ANONYMIZED_TELEMETRY=true holoviz-mcp +``` + +## IDE-Specific Configuration + +### VS Code Configuration + +Set environment variables in `mcp.json`: + +```json +{ + "servers": { + "holoviz": { + "type": "stdio", + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +### Claude Desktop Configuration + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "INFO" + } + } + } +} +``` + +### Claude Code Configuration + +Edit `~/.claude.json`: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG", + "HOLOVIZ_MCP_USER_DIR": "/custom/path" + } + } + } +} +``` + +### Cursor Configuration + +Set environment variables in Cursor's MCP settings: + +```json +{ + "name": "holoviz", + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "INFO" + } +} +``` + +### Windsurf Configuration + +Edit Windsurf's config file: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +## View Current Configuration + +HoloViz MCP includes a built-in configuration viewer: + +```bash +holoviz-mcp serve +``` + +Navigate to the Configuration Viewer tool to see your current configuration. + +## Next Steps + +- [Configure Display Server](configure-display-server.md): Set up the display tool +- [Add Custom Documentation](add-custom-docs.md): Index your own libraries +- [Troubleshooting](troubleshooting.md): Fix configuration issues diff --git a/docs/how-to/configure-vscode.md b/docs/how-to/configure-vscode.md new file mode 100644 index 0000000..aad9642 --- /dev/null +++ b/docs/how-to/configure-vscode.md @@ -0,0 +1,164 @@ +# Configure HoloViz MCP for Copilot + VS Code + +This guide shows you how to configure HoloViz MCP with GitHub Copilot and VS Code. + +## Prerequisites + +- VS Code installed +- GitHub Copilot extension installed +- HoloViz MCP installed ([Installation guide](install-uv.md)) + +## Add the MCP Server + +1. Open VS Code +2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) +3. Type "MCP: Add Server" and press Enter +4. Select "Command (stdio)" +5. Enter the command "holoviz-mcp" +6. Enter *Server ID* "holoviz" +7. Select the "Global" *Configuration Target* + +This will add the following configuration to your user `mcp.json` file: + +```json +{ + "servers": { + "holoviz": { + "type": "stdio", + "command": "holoviz-mcp" + } + }, + "inputs": [] +} +``` + +!!! tip "Remote Development" + For remote development (SSH, Dev Containers, Codespaces), use Workspace or Remote settings to ensure the MCP server runs on the remote machine. + +See the [VS Code | MCP Servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) guide for more details. + +## Start the MCP Server + +1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) +2. Type "MCP: List Servers" +3. Select `holoviz` from the dropdown +4. Select "Start Server" + +![VS Code Start HoloViz MCP](../assets/images/vscode-start-holoviz-mcp.png) + +## Test Your Configuration + +After starting the server, test it with Copilot: + +1. **Simple Query** - Open Copilot Chat and ask: + + ``` + List available Panel input components + ``` + +2. **Detailed Query** - Ask for specific information: + + ``` + What parameters does the Panel TextInput component have? + ``` + +3. **Code Generation** - Ask Copilot to generate code: + + ``` + Create a simple Panel dashboard with a slider + ``` + +If you get detailed, accurate responses with specific Panel component information, your configuration is working! 🎉 + +!!! tip "Force MCP Usage" + In VS Code, you can include `#holoviz` in your prompt to explicitly request that Copilot use the holoviz-mcp server for your query. + +## Advanced Configuration + +### Set Log Level + +For debugging, increase the log level: + +```json +{ + "servers": { + "holoviz": { + "type": "stdio", + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +### Custom Configuration Directory + +Use a custom directory for configuration and data: + +```json +{ + "servers": { + "holoviz": { + "type": "stdio", + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_USER_DIR": "/path/to/custom/dir" + } + } + } +} +``` + +## Troubleshooting + +### Server Not Starting + +**Check the command**: + +```bash +# Test the server directly +holoviz-mcp +``` + +**Verify installation**: + +```bash +uv --version # Check uv is installed +python --version # Should be 3.11 or higher +``` + +### Copilot Not Recognizing Components + +1. **Verify documentation index exists**: + + ```bash + ls ~/.holoviz-mcp + ``` + +2. **Recreate the index**: + + ```bash + holoviz-mcp update index + ``` + +3. **Restart VS Code** + +### Configuration File Not Found + +Use Command Palette → "MCP: Edit Settings" to create or edit the file. + +### Permission Errors + +**Linux/macOS**: Ensure the configuration file is readable: + +```bash +chmod 644 ~/.config/Code/User/globalStorage/github.copilot/mcp.json +``` + +## Next Steps + +- **[Getting Started Tutorial](../tutorials/getting-started-copilot-vscode.md)**: Complete walkthrough for Copilot + VS Code +- **[Configuration Options](configure-settings.md)**: Customize HoloViz MCP behavior +- **[Troubleshooting Guide](troubleshooting.md)**: Fix common issues diff --git a/docs/how-to/configure-windsurf.md b/docs/how-to/configure-windsurf.md new file mode 100644 index 0000000..c1fbc56 --- /dev/null +++ b/docs/how-to/configure-windsurf.md @@ -0,0 +1,175 @@ +# Configure HoloViz MCP for Windsurf + +This guide shows you how to configure HoloViz MCP with Windsurf IDE. + +## Prerequisites + +- Windsurf IDE installed ([Download](https://windsurf.ai/)) +- HoloViz MCP installed ([Installation guide](install-uv.md)) + +## Locate Your Configuration File + +Find your Windsurf MCP configuration file. The location varies by operating system and Windsurf version. Common locations include: + +- **macOS**: `~/Library/Application Support/Windsurf/config.json` or similar +- **Windows**: `%APPDATA%\Windsurf\config.json` or similar +- **Linux**: `~/.config/Windsurf/config.json` or similar + +!!! note + The exact configuration file location may vary. Check Windsurf's documentation for your specific version. + +## Add the MCP Server + +1. Open the Windsurf MCP configuration file in a text editor +2. Add this configuration: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp" + } + } +} +``` + +3. Save the file +4. Restart Windsurf + +!!! tip "Existing Configuration" + If your file already has other MCP servers configured, add `"holoviz"` to the existing `mcpServers` object: + + ```json + { + "mcpServers": { + "existing-server": { + "command": "existing-command" + }, + "holoviz": { + "command": "holoviz-mcp" + } + } + } + ``` + +## Test Your Configuration + +Test the configuration with Windsurf's AI: + +1. **Simple Query** - Open Windsurf's AI assistant and ask: + + ``` + List available Panel input components + ``` + +2. **Detailed Query** - Ask for specific information: + + ``` + What parameters does the Panel TextInput component have? + ``` + +3. **Code Generation** - Ask Windsurf AI to generate code: + + ``` + Create a simple Panel dashboard with a slider + ``` + +If Windsurf's AI provides detailed, accurate responses with specific Panel component information, your configuration is working! 🎉 + +## Advanced Configuration + +### Set Log Level + +For debugging, increase the log level: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" + } + } + } +} +``` + +### Custom Configuration Directory + +Use a custom directory for configuration and data: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp", + "env": { + "HOLOVIZ_MCP_USER_DIR": "/path/to/custom/dir" + } + } + } +} +``` + +## Troubleshooting + +### Configuration File Not Found + +**Check Windsurf's documentation** for the correct configuration file location for your version. + +**Create the file** if it doesn't exist, using the configuration above. + +### Server Not Starting + +**Check that holoviz-mcp is installed**: + +```bash +holoviz-mcp --version +``` + +**Test the server directly**: + +```bash +holoviz-mcp +``` + +Press `Ctrl+C` to stop it. + +### Windsurf AI Not Recognizing Components + +1. **Verify documentation index exists**: + + ```bash + ls ~/.holoviz-mcp + ``` + +2. **Recreate the index**: + + ```bash + holoviz-mcp update index + ``` + +3. **Restart Windsurf** + +### Configuration Not Loading + +**Verify JSON syntax** - ensure there are no trailing commas, missing quotes, or other syntax errors. + +**Restart Windsurf completely** - quit and reopen the application. + +**Check logs** - look for error messages in Windsurf's output or logs. + +### Permission Errors + +**Linux/macOS**: Ensure the configuration file is readable: + +```bash +chmod 644 ~/.config/Windsurf/config.json # Adjust path as needed +``` + +## Next Steps + +- **[Getting Started Tutorial](../tutorials/getting-started-windsurf.md)**: Complete walkthrough for Windsurf +- **[Configuration Options](configure-settings.md)**: Customize HoloViz MCP behavior +- **[Troubleshooting Guide](troubleshooting.md)**: Fix common issues diff --git a/docs/how-to/docker.md b/docs/how-to/docker-development.md similarity index 68% rename from docs/how-to/docker.md rename to docs/how-to/docker-development.md index 40e51bd..cc0c474 100644 --- a/docs/how-to/docker.md +++ b/docs/how-to/docker-development.md @@ -1,18 +1,17 @@ -# Docker Guide +# Docker for Development -This guide provides comprehensive information about running HoloViz MCP Server using Docker. +This guide shows you how to use Docker for local development with HoloViz MCP. -## Overview +## Prerequisites -Docker provides a very easy way to run HoloViz MCP Server with all dependencies pre-installed and properly configured. The Docker image is automatically built and published to GitHub Container Registry for both AMD64 and ARM64 architectures (Apple Silicon, Raspberry Pi, etc.). +- Docker installed ([Installation guide](install-docker.md)) -### Benefits of Using Docker +## Benefits of Using Docker - **Zero Setup**: No need to install Python, UV, Pixi, or manage dependencies - **Consistent Environment**: Same configuration across all platforms - **Isolated**: Runs in a container without affecting your system - **Multi-Architecture**: Supports both x86_64 and ARM64 (Apple Silicon) -- **Production Ready**: Optimized for both development and deployment ## Quick Start @@ -46,7 +45,7 @@ The server will be accessible at `http://localhost:8000/mcp/`. ## Available Image Tags -The Docker image is published with multiple tags for different use cases: +The Docker image is published with multiple tags: | Tag | Description | Use Case | |-----|-------------|----------| @@ -159,7 +158,7 @@ docker run -it --rm \ ## Integration with MCP Clients -### VS Code + GitHub Copilot (HTTP) +### Copilot + VS Code (HTTP) 1. Start the Docker container with HTTP transport: @@ -196,7 +195,7 @@ While Docker primarily supports HTTP transport for MCP, you can use it with Clau ## Docker Compose -For production deployments or easier management, use Docker Compose. +For easier management during development, use Docker Compose. ### Basic Setup @@ -222,79 +221,6 @@ Start the service: docker-compose up -d ``` -### Production Setup - -For production use with logging and resource limits: - -```yaml -services: - holoviz-mcp: - image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 - container_name: holoviz-mcp - ports: - - "8000:8000" - environment: - - HOLOVIZ_MCP_TRANSPORT=http - - HOLOVIZ_MCP_LOG_LEVEL=WARNING - - HOLOVIZ_MCP_HOST=0.0.0.0 - - HOLOVIZ_MCP_PORT=8000 - volumes: - - holoviz-data:/root/.holoviz-mcp - restart: unless-stopped - deploy: - resources: - limits: - cpus: '2.0' - memory: 2G - reservations: - cpus: '0.5' - memory: 512M - logging: - driver: "json-file" - options: - max-size: "10m" - max-file: "3" - -volumes: - holoviz-data: - driver: local -``` - -## Building Locally - -### Build the Image - -To build the Docker image locally: - -```bash -docker build -t holoviz-mcp:local . -``` - -### Build with Specific Platform - -Build for a specific architecture: - -```bash -# For AMD64 (Intel/AMD) -docker build --platform linux/amd64 -t holoviz-mcp:local-amd64 . - -# For ARM64 (Apple Silicon, Raspberry Pi) -docker build --platform linux/arm64 -t holoviz-mcp:local-arm64 . -``` - -### Multi-Platform Build - -Build for both architectures using buildx: - -```bash -docker buildx create --use -docker buildx build \ - --platform linux/amd64,linux/arm64 \ - -t holoviz-mcp:local \ - --load \ - . -``` - ## Advanced Usage ### Running in Detached Mode @@ -454,84 +380,8 @@ curl http://localhost:8000/mcp/ docker run --memory=2g --memory-swap=2g ... ``` -## Security Considerations - -### Network Exposure - -When running with HTTP transport: - -- **Development**: Use `127.0.0.1` to restrict to localhost -- **Production**: Use `0.0.0.0` with proper firewall rules - -```bash -# Development (localhost only) --e HOLOVIZ_MCP_HOST=127.0.0.1 - -# Production (all interfaces) --e HOLOVIZ_MCP_HOST=0.0.0.0 -``` - -### Updates - -Regularly update to the latest image for security patches: - -```bash -# Pull latest updates -docker pull ghcr.io/marcskovmadsen/holoviz-mcp:latest - -# Restart container -docker-compose down && docker-compose up -d -``` - -## Performance Optimization - -### Resource Limits - -Set appropriate resource limits for your use case: - -```bash -docker run \ - --cpus=2 \ - --memory=2g \ - --memory-swap=2g \ - ... -``` - -### Volume Performance - -For better I/O performance on macOS: - -```yaml -volumes: - - ~/.holoviz-mcp:/root/.holoviz-mcp:cached -``` - -### Cleanup - -Remove unused images and containers: - -```bash -# Remove old images -docker image prune -a - -# Remove unused volumes -docker volume prune - -# Remove all unused resources -docker system prune -a --volumes -``` - ## Next Steps -- **Configure MCP Client**: Set up your preferred AI assistant to use the Docker container -- **Customize Configuration**: Create a `config.yaml` in your mounted volume -- **Explore Features**: Try asking your AI assistant about Panel components -- **Production Deployment**: Use Docker Compose for production setups - -## Additional Resources - -- [Main Documentation](../index.md) -- [Examples](../examples.md) -- [GitHub Repository](https://github.com/MarcSkovMadsen/holoviz-mcp) -- [Docker Hub](https://github.com/MarcSkovMadsen/holoviz-mcp/pkgs/container/holoviz-mcp) -- [HoloViz Community](https://discourse.holoviz.org/) +- [Docker Production Guide](docker-production.md): Deploy to production +- [Configure Settings](configure-settings.md): Customize behavior +- [Troubleshooting](troubleshooting.md): Fix common issues diff --git a/docs/how-to/docker-production.md b/docs/how-to/docker-production.md new file mode 100644 index 0000000..fa30094 --- /dev/null +++ b/docs/how-to/docker-production.md @@ -0,0 +1,529 @@ +# Docker for Production + +This guide shows you how to deploy HoloViz MCP with Docker in production environments. + +## Prerequisites + +- Docker installed ([Installation guide](install-docker.md)) +- Understanding of Docker development setup ([Development guide](docker-development.md)) + +## Production Docker Compose + +For production deployments, use Docker Compose with proper configuration for logging, resource limits, and restarts. + +### Production Setup + +Create a `docker-compose.yml` file with production settings: + +```yaml +services: + holoviz-mcp: + image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + container_name: holoviz-mcp + ports: + - "8000:8000" + environment: + - HOLOVIZ_MCP_TRANSPORT=http + - HOLOVIZ_MCP_LOG_LEVEL=WARNING + - HOLOVIZ_MCP_HOST=0.0.0.0 + - HOLOVIZ_MCP_PORT=8000 + volumes: + - holoviz-data:/root/.holoviz-mcp + restart: unless-stopped + deploy: + resources: + limits: + cpus: '2.0' + memory: 2G + reservations: + cpus: '0.5' + memory: 512M + logging: + driver: "json-file" + options: + max-size: "10m" + max-file: "3" + +volumes: + holoviz-data: + driver: local +``` + +### Configuration Details + +**Image Versioning** +- Use specific version tags (e.g., `v1.0.0`) not `latest` +- This ensures reproducible deployments + +**Resource Limits** +- `limits`: Maximum resources the container can use +- `reservations`: Minimum resources guaranteed to the container + +**Logging** +- `json-file` driver with rotation to prevent disk space issues +- `max-size`: Maximum size of a single log file +- `max-file`: Maximum number of log files to retain + +**Restart Policy** +- `unless-stopped`: Automatically restart container on failure +- Container won't restart if manually stopped + +### Start Production Service + +```bash +docker-compose up -d +``` + +### Monitor Production Service + +```bash +# Check status +docker-compose ps + +# View logs +docker-compose logs -f + +# Restart service +docker-compose restart + +# Stop service +docker-compose down +``` + +## Building Custom Images + +### Build Locally + +To build the Docker image locally with customizations: + +```bash +docker build -t holoviz-mcp:local . +``` + +### Build for Specific Platform + +Build for a specific architecture: + +```bash +# For AMD64 (Intel/AMD) +docker build --platform linux/amd64 -t holoviz-mcp:local-amd64 . + +# For ARM64 (Apple Silicon, Raspberry Pi) +docker build --platform linux/arm64 -t holoviz-mcp:local-arm64 . +``` + +### Multi-Platform Build + +Build for both architectures using buildx: + +```bash +docker buildx create --use +docker buildx build \ + --platform linux/amd64,linux/arm64 \ + -t holoviz-mcp:local \ + --load \ + . +``` + +### Custom Dockerfile + +Create a custom Dockerfile based on the HoloViz MCP image: + +```dockerfile +FROM ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + +# Add custom documentation +COPY docs/ /custom-docs/ + +# Install additional dependencies +RUN pip install plotly altair + +# Set custom configuration +COPY config.yaml /root/.holoviz-mcp/config.yaml + +# Update documentation index +RUN holoviz-mcp update index +``` + +Build the custom image: + +```bash +docker build -t holoviz-mcp:custom . +``` + +## Security Considerations + +### Network Exposure + +Configure network binding based on your deployment: + +**Development (localhost only)** + +```bash +-e HOLOVIZ_MCP_HOST=127.0.0.1 +``` + +This restricts access to the local machine only. + +**Production (all interfaces)** + +```bash +-e HOLOVIZ_MCP_HOST=0.0.0.0 +``` + +Allows access from any network interface. Use with proper firewall rules. + +### Firewall Configuration + +When exposing the container to the network: + +1. **Use a reverse proxy** (Nginx, Traefik) for SSL/TLS termination +2. **Configure firewall rules** to restrict access +3. **Use authentication** if exposing to the internet + +Example with Nginx: + +```nginx +server { + listen 443 ssl; + server_name mcp.example.com; + + ssl_certificate /etc/ssl/certs/example.com.crt; + ssl_certificate_key /etc/ssl/private/example.com.key; + + location /mcp/ { + proxy_pass http://localhost:8000/mcp/; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } +} +``` + +### Updates + +Regularly update to the latest image for security patches: + +```bash +# Pull latest updates +docker pull ghcr.io/marcskovmadsen/holoviz-mcp:latest + +# Update Docker Compose service +docker-compose pull +docker-compose down +docker-compose up -d +``` + +### User Permissions + +Run the container with a non-root user: + +```yaml +services: + holoviz-mcp: + image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + user: "1000:1000" # Use your user ID + volumes: + - ./data:/root/.holoviz-mcp +``` + +Or at runtime: + +```bash +docker run --user $(id -u):$(id -g) ... +``` + +### Environment Variable Security + +Store sensitive environment variables securely: + +**Using Docker secrets**: + +```yaml +services: + holoviz-mcp: + image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + secrets: + - holoviz_config + environment: + - HOLOVIZ_MCP_CONFIG_FILE=/run/secrets/holoviz_config + +secrets: + holoviz_config: + file: ./secrets/config.yaml +``` + +**Using .env file**: + +Create a `.env` file: + +```bash +HOLOVIZ_MCP_LOG_LEVEL=WARNING +HOLOVIZ_MCP_TRANSPORT=http +``` + +Reference it in `docker-compose.yml`: + +```yaml +services: + holoviz-mcp: + env_file: .env +``` + +## Performance Optimization + +### Resource Limits + +Set appropriate resource limits based on your workload: + +```bash +docker run \ + --cpus=2 \ + --memory=2g \ + --memory-swap=2g \ + ... +``` + +In Docker Compose: + +```yaml +deploy: + resources: + limits: + cpus: '2.0' + memory: 2G + reservations: + cpus: '0.5' + memory: 512M +``` + +### Volume Performance + +For better I/O performance on macOS: + +```yaml +volumes: + - ~/.holoviz-mcp:/root/.holoviz-mcp:cached +``` + +For Linux production, use named volumes: + +```yaml +volumes: + holoviz-data: + driver: local + driver_opts: + type: none + o: bind + device: /var/lib/holoviz-mcp +``` + +### Network Performance + +Use host networking for better performance (Linux only): + +```bash +docker run --network host \ + -e HOLOVIZ_MCP_TRANSPORT=http \ + ... +``` + +**Note**: This removes network isolation. Use with caution. + +### Cleanup + +Remove unused images and containers periodically: + +```bash +# Remove old images +docker image prune -a + +# Remove unused volumes +docker volume prune + +# Remove all unused resources +docker system prune -a --volumes +``` + +Schedule automatic cleanup: + +```bash +# Add to crontab (daily at 2 AM) +0 2 * * * docker system prune -f +``` + +## Monitoring and Logging + +### Health Checks + +Add health checks to your Docker Compose configuration: + +```yaml +services: + holoviz-mcp: + image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8000/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s +``` + +### Log Management + +**View logs**: + +```bash +# All logs +docker-compose logs + +# Follow logs +docker-compose logs -f + +# Last 100 lines +docker-compose logs --tail=100 + +# Specific service +docker-compose logs holoviz-mcp +``` + +**External log management**: + +Configure Docker to send logs to external systems: + +```yaml +logging: + driver: "syslog" + options: + syslog-address: "tcp://192.168.0.42:123" +``` + +Or use log aggregation tools like ELK Stack, Splunk, or Datadog. + +### Metrics + +Monitor container metrics: + +```bash +# Container stats +docker stats holoviz-mcp + +# Detailed stats +docker stats --no-stream --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" +``` + +## High Availability + +### Multiple Instances + +Run multiple instances behind a load balancer: + +```yaml +services: + holoviz-mcp-1: + image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + ports: + - "8001:8000" + + holoviz-mcp-2: + image: ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + ports: + - "8002:8000" + + nginx: + image: nginx:latest + ports: + - "80:80" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf +``` + +### Orchestration + +For production orchestration, consider: + +- **Docker Swarm**: Built-in Docker orchestration +- **Kubernetes**: Enterprise-grade container orchestration +- **AWS ECS/Fargate**: Managed container services +- **Azure Container Instances**: Serverless containers + +## Backup and Recovery + +### Backup Data + +Backup the persistent volume: + +```bash +# Create backup +docker run --rm \ + -v holoviz-data:/data \ + -v $(pwd):/backup \ + alpine tar czf /backup/holoviz-backup-$(date +%Y%m%d).tar.gz /data +``` + +### Restore Data + +Restore from backup: + +```bash +# Restore backup +docker run --rm \ + -v holoviz-data:/data \ + -v $(pwd):/backup \ + alpine tar xzf /backup/holoviz-backup-20250115.tar.gz -C / +``` + +### Automated Backups + +Add to crontab for daily backups: + +```bash +0 3 * * * docker run --rm -v holoviz-data:/data -v /backups:/backup alpine tar czf /backup/holoviz-$(date +\%Y\%m\%d).tar.gz /data +``` + +## Troubleshooting + +### Container Performance Issues + +**Check resource usage**: + +```bash +docker stats holoviz-mcp +``` + +**Increase limits** if needed in `docker-compose.yml`. + +### Network Issues + +**Test connectivity**: + +```bash +curl http://localhost:8000/mcp/ +``` + +**Check firewall rules**: + +```bash +sudo ufw status +``` + +### Data Persistence Issues + +**Verify volume**: + +```bash +docker volume inspect holoviz-data +``` + +**Check volume contents**: + +```bash +docker run --rm -v holoviz-data:/data alpine ls -la /data +``` + +## Next Steps + +- [Security Considerations](../explanation/security.md): Understand security model +- [Docker Development](docker-development.md): Local development setup +- [Configure Settings](configure-settings.md): Customize behavior +- [Troubleshooting](troubleshooting.md): Fix common issues diff --git a/docs/how-to/ide-configuration.md b/docs/how-to/ide-configuration.md deleted file mode 100644 index 801bd95..0000000 --- a/docs/how-to/ide-configuration.md +++ /dev/null @@ -1,249 +0,0 @@ -# IDE Configuration - -This guide covers configuring HoloViz MCP with different IDEs and AI assistants. - -## VS Code + GitHub Copilot - -1. Open VS Code -2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) -3. Type "MCP: Add Server" and press Enter -4. Select "Command (stdio)" -5. Enter the command "holoviz-mcp" -6. Enter *Server ID* "holoviz" -7. Select the "Global" *Configuration Target* - -This will add the below configuration to user mcp.json file. - - ```json - { - "servers": { - "holoviz": { - "type": "stdio", - "command": "holoviz-mcp" - } - }, - "inputs": [] - } - ``` - -**Tip**: For remote development (SSH, Dev Containers, Codespaces), use Workspace or Remote settings to ensure the MCP server runs on the remote machine. - -Please refer to the [VS Code | MCP Servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) guide for more details. - -### Start the MCP Server - -1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) -2. Type "MCP: List Servers" -3. Select `holoviz` from the dropdown -4. Select "Start Server" - -![VS Code Start HoloViz MCP](../assets/images/vscode-start-holoviz-mcp.png) - -## Claude Code - -To configure globally for your user: - -```bash -claude mcp add holoviz --transport stdio --scope user -- holoviz-mcp -``` - -This will update your `~/.claude.json` file. - -In Claude Code, run the `/mcp` command to verify the status of the HoloViz MCP server. - -![Claude Code HoloViz MCP](../assets/images/claude-code-holoviz-mcp.png) - -## Claude Desktop - -### Manual Configuration - -1. Locate your Claude Desktop configuration file: - - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - - **Linux**: `~/.config/Claude/claude_desktop_config.json` - -2. Add this configuration: - -```json -{ - "mcpServers": { - "holoviz": { - "command": "holoviz-mcp" - } - } -} -``` - -3. Save the file and restart Claude Desktop - -### Verify Connection - -After restarting Claude Desktop, look for the MCP indicator (🔌) in the interface. It should show "holoviz" as a connected server. - -## Cursor - -### Quick Install - -[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square)](cursor://settings/mcp) - -### Manual Configuration - -1. Open Cursor Settings -2. Navigate to `Features` → `Model Context Protocol` -3. Click `Add Server` -4. Enter the configuration: - -```json -{ - "name": "holoviz", - "command": "holoviz-mcp" -} -``` - -5. Save and restart Cursor - -## Windsurf - -Add to your Windsurf MCP configuration: - -```json -{ - "mcpServers": { - "holoviz": { - "command": "holoviz-mcp" - } - } -} -``` - -## Other MCP Clients - -For other MCP-compatible clients, use the standard configuration: - -```json -{ - "name": "holoviz", - "command": "holoviz-mcp" -} -``` - -## Environment Variables - -You can customize server behavior using environment variables: - -### Set Log Level - -```json -{ - "servers": { - "holoviz": { - "type": "stdio", - "command": "holoviz-mcp", - "env": { - "HOLOVIZ_MCP_LOG_LEVEL": "DEBUG" - } - } - } -} -``` - -### Custom Configuration Directory - -Use a custom directory for configuration and data: - -```json -{ - "servers": { - "holoviz": { - "type": "stdio", - "command": "holoviz-mcp", - "env": { - "HOLOVIZ_MCP_USER_DIR": "/path/to/custom/dir" - } - } - } -} -``` - -## Testing Your Configuration - -After configuration, test with your AI assistant: - -1. **Simple Query**: - - ``` - List available Panel input components - ``` - -2. **Detailed Query**: - - ``` - What parameters does the Panel TextInput component have? - ``` - -3. **Code Generation**: - - ``` - Create a simple Panel dashboard with a slider - ``` - -If you get detailed, accurate responses, your configuration is working! 🎉 - -## Troubleshooting - -### Server Not Starting - -**Check the command**: - -```bash -# Test the server directly -holoviz-mcp -``` - -**Verify uv installation**: - -```bash -uv --version -``` - -**Check Python version**: - -```bash -python --version # Should be 3.11 or higher -``` - -### AI Assistant Not Recognizing Components - -1. **Verify documentation index exists**: - - ```bash - ls ~/.holoviz-mcp - ``` - -2. **Recreate the index**: - - ```bash - holoviz-mcp update index - ``` - -3. **Restart your IDE** - -### Configuration File Not Found - -**VS Code**: Use Command Palette → "MCP: Edit Settings" to create the file - -**Claude Desktop**: Create the file manually at the correct location - -### Permission Errors - -**Linux/macOS**: Ensure the configuration file is readable: - -```bash -chmod 644 ~/.config/Code/User/globalStorage/github.copilot/mcp.json -``` - -## Next Steps - -- [Configuration Guide](configuration.md): Customize HoloViz MCP behavior -- [Docker Guide](docker.md): Run in a container -- [Troubleshooting](troubleshooting.md): Fix common issues diff --git a/docs/how-to/install-conda.md b/docs/how-to/install-conda.md new file mode 100644 index 0000000..c7f3686 --- /dev/null +++ b/docs/how-to/install-conda.md @@ -0,0 +1,124 @@ +# Install HoloViz MCP with conda/mamba + +This guide shows you how to install HoloViz MCP using conda or mamba package managers. + +!!! note "Alternative: uv installation" + For faster installation, consider using [uv](install-uv.md) instead. + +## Prerequisites + +You need either conda or mamba installed. If you don't have either: + +- **Conda**: Install [Anaconda](https://www.anaconda.com/download) or [Miniconda](https://docs.conda.io/en/latest/miniconda.html) +- **Mamba**: Install [Miniforge](https://github.com/conda-forge/miniforge) (includes mamba) + +## Install HoloViz MCP + +### Using conda + +Install HoloViz MCP from conda-forge: + +```bash +conda install -c conda-forge holoviz-mcp +``` + +### Using mamba + +Mamba is faster than conda: + +```bash +mamba install -c conda-forge holoviz-mcp +``` + +!!! tip "Create a dedicated environment" + It's recommended to create a dedicated environment: + + ```bash + # With conda + conda create -n holoviz-mcp -c conda-forge holoviz-mcp + conda activate holoviz-mcp + + # With mamba + mamba create -n holoviz-mcp -c conda-forge holoviz-mcp + mamba activate holoviz-mcp + ``` + +## Install Chromium + +HoloViz MCP uses Chromium for taking screenshots. Install it: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Create Documentation Index + +Create the documentation index so HoloViz MCP can provide intelligent answers: + +```bash +holoviz-mcp update index +``` + +**⏱️ This takes 5-10 minutes** on first run as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Verify Installation + +Test that the server starts correctly: + +```bash +holoviz-mcp +``` + +You should see output indicating the server is running. Press `Ctrl+C` to stop it. + +## Update HoloViz MCP + +To update to the latest version: + +```bash +# With conda +conda update -c conda-forge holoviz-mcp + +# With mamba +mamba update -c conda-forge holoviz-mcp +``` + +After updating, refresh the documentation index: + +```bash +holoviz-mcp update index +``` + +## Uninstall + +To remove HoloViz MCP: + +```bash +# With conda +conda remove holoviz-mcp + +# With mamba +mamba remove holoviz-mcp +``` + +To also remove the documentation index and configuration: + +```bash +rm -rf ~/.holoviz-mcp +``` + +## Next Steps + +After installation, configure your IDE or AI assistant: + +- **[Copilot + VS Code](configure-vscode.md)**: Configure for VS Code +- **[Claude Desktop](configure-claude-desktop.md)**: Configure for Claude Desktop +- **[Claude Code](configure-claude-code.md)**: Configure for Claude Code +- **[Cursor](configure-cursor.md)**: Configure for Cursor +- **[Windsurf](configure-windsurf.md)**: Configure for Windsurf + +Or start with a complete tutorial: + +- **[Getting Started Tutorials](../tutorials/getting-started-copilot-vscode.md)**: Choose your tool diff --git a/docs/how-to/install-docker.md b/docs/how-to/install-docker.md new file mode 100644 index 0000000..88e5269 --- /dev/null +++ b/docs/how-to/install-docker.md @@ -0,0 +1,140 @@ +# Install HoloViz MCP with Docker + +This guide shows you how to install and run HoloViz MCP using Docker. This is ideal for containerized deployments and when you want all dependencies pre-installed. + +## Why Use Docker? + +- **Zero Setup**: No need to install Python or manage dependencies +- **Consistent Environment**: Same configuration across all platforms +- **Isolated**: Runs in a container without affecting your system +- **Multi-Architecture**: Supports both x86_64 and ARM64 (Apple Silicon) + +## Prerequisites + +You need Docker installed on your system. If you don't have it: + +- **macOS**: Install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/) +- **Windows**: Install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) +- **Linux**: Install [Docker Engine](https://docs.docker.com/engine/install/) + +Verify Docker is installed: + +```bash +docker --version +``` + +## Pull the Docker Image + +Pull the latest HoloViz MCP image from GitHub Container Registry: + +```bash +docker pull ghcr.io/marcskovmadsen/holoviz-mcp:latest +``` + +## Run HoloViz MCP + +### Basic Run (STDIO mode) + +For local development with AI assistants: + +```bash +docker run -it --rm \ + -v ~/.holoviz-mcp:/root/.holoviz-mcp \ + ghcr.io/marcskovmadsen/holoviz-mcp:latest +``` + +This: +- Runs interactively (`-it`) +- Removes the container when stopped (`--rm`) +- Mounts your local config directory (`-v`) + +### Run with HTTP Transport + +For remote development or HTTP access: + +```bash +docker run -it --rm \ + -p 8000:8000 \ + -e HOLOVIZ_MCP_TRANSPORT=http \ + -v ~/.holoviz-mcp:/root/.holoviz-mcp \ + ghcr.io/marcskovmadsen/holoviz-mcp:latest +``` + +The server will be accessible at `http://localhost:8000/mcp/`. + +## Available Image Tags + +Choose the right tag for your use case: + +| Tag | Description | Use Case | +|-----|-------------|----------| +| `latest` | Latest build from main branch | Development, testing | +| `vX.Y.Z` | Semantic version (e.g., `v1.0.0`) | Production, stable releases | +| `YYYY.MM.DD` | Date-based tags (e.g., `2025.01.15`) | Reproducible builds | + +### Pull Specific Versions + +```bash +# Latest stable release +docker pull ghcr.io/marcskovmadsen/holoviz-mcp:latest + +# Specific version +docker pull ghcr.io/marcskovmadsen/holoviz-mcp:v1.0.0 + +# Date-based version for reproducibility +docker pull ghcr.io/marcskovmadsen/holoviz-mcp:2025.01.15 +``` + +## Verify Installation + +After starting the container, verify it's running: + +```bash +docker ps +``` + +You should see the holoviz-mcp container in the list. + +## Update HoloViz MCP + +To update to the latest version: + +```bash +# Pull the latest image +docker pull ghcr.io/marcskovmadsen/holoviz-mcp:latest + +# Restart your container with the new image +docker stop # If running in background +# Then start a new container as shown above +``` + +## Remove Docker Image + +To remove the image and free up space: + +```bash +# Remove the image +docker rmi ghcr.io/marcskovmadsen/holoviz-mcp:latest + +# Remove unused images +docker image prune +``` + +## Next Steps + +After installation, you have several options: + +### For Development + +- **[Docker Development Guide](docker-development.md)**: Local development with Docker +- **[Configure your IDE](configure-vscode.md)**: Connect your IDE to the Docker container + +### For Production + +- **[Docker Production Guide](docker-production.md)**: Production deployment patterns +- **[Configuration Options](configure-settings.md)**: Environment variables and settings + +### Get Started + +- **[Getting Started Tutorials](../tutorials/getting-started-copilot-vscode.md)**: Choose your tool +- **[Display System](../tutorials/display-system.md)**: Learn about visualizations diff --git a/docs/how-to/install-pip.md b/docs/how-to/install-pip.md new file mode 100644 index 0000000..9a004d6 --- /dev/null +++ b/docs/how-to/install-pip.md @@ -0,0 +1,103 @@ +# Install HoloViz MCP with pip + +This guide shows you how to install HoloViz MCP using pip, the standard Python package installer. + +!!! note "Alternative: uv installation" + For faster installation and better dependency management, consider using [uv](install-uv.md) instead. + +## Prerequisites + +You need Python 3.11 or newer installed. Check your version: + +```bash +python --version +``` + +## Install HoloViz MCP + +Install HoloViz MCP using pip: + +```bash +pip install holoviz-mcp +``` + +!!! tip "Virtual environments" + It's recommended to install in a virtual environment: + + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + pip install holoviz-mcp + ``` + +## Install Chromium + +HoloViz MCP uses Chromium for taking screenshots. Install it: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Create Documentation Index + +Create the documentation index so HoloViz MCP can provide intelligent answers: + +```bash +holoviz-mcp update index +``` + +**⏱️ This takes 5-10 minutes** on first run as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Verify Installation + +Test that the server starts correctly: + +```bash +holoviz-mcp +``` + +You should see output indicating the server is running. Press `Ctrl+C` to stop it. + +## Update HoloViz MCP + +To update to the latest version: + +```bash +pip install --upgrade holoviz-mcp +``` + +After updating, refresh the documentation index: + +```bash +holoviz-mcp update index +``` + +## Uninstall + +To remove HoloViz MCP: + +```bash +pip uninstall holoviz-mcp +``` + +To also remove the documentation index and configuration: + +```bash +rm -rf ~/.holoviz-mcp +``` + +## Next Steps + +After installation, configure your IDE or AI assistant: + +- **[Copilot + VS Code](configure-vscode.md)**: Configure for VS Code +- **[Claude Desktop](configure-claude-desktop.md)**: Configure for Claude Desktop +- **[Claude Code](configure-claude-code.md)**: Configure for Claude Code +- **[Cursor](configure-cursor.md)**: Configure for Cursor +- **[Windsurf](configure-windsurf.md)**: Configure for Windsurf + +Or start with a complete tutorial: + +- **[Getting Started Tutorials](../tutorials/getting-started-copilot-vscode.md)**: Choose your tool diff --git a/docs/how-to/install-uv.md b/docs/how-to/install-uv.md new file mode 100644 index 0000000..c786323 --- /dev/null +++ b/docs/how-to/install-uv.md @@ -0,0 +1,109 @@ +# Install HoloViz MCP with uv + +This guide shows you how to install HoloViz MCP using [uv](https://docs.astral.sh/uv/), a fast Python package installer. This is the **recommended** installation method. + +## Prerequisites + +You need uv installed on your system. If you don't have it: + +```bash +# macOS and Linux +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Windows +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +For other installation methods, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/). + +## Install HoloViz MCP + +Install HoloViz MCP as a uv tool: + +```bash +# Basic installation +uv tool install holoviz-mcp + +# Or with PyData packages (recommended for data science) +uv tool install holoviz-mcp[pydata] + +# Or with specific extra packages +uv tool install holoviz-mcp --with altair --with polars +``` + +!!! tip "Which option should I use?" + - **Basic**: Minimal installation, you add packages as needed + - **PyData**: Includes pandas, numpy, matplotlib, and other common data science packages + - **With extras**: Add specific packages you know you'll need + +## Install Chromium + +HoloViz MCP uses Chromium for taking screenshots. Install it: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Create Documentation Index + +Create the documentation index so HoloViz MCP can provide intelligent answers: + +```bash +holoviz-mcp update index +``` + +**⏱️ This takes 5-10 minutes** on first run as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Verify Installation + +Test that the server starts correctly: + +```bash +holoviz-mcp +``` + +You should see output indicating the server is running. Press `Ctrl+C` to stop it. + +## Update HoloViz MCP + +To update to the latest version: + +```bash +uv tool upgrade holoviz-mcp +``` + +After updating, refresh the documentation index: + +```bash +holoviz-mcp update index +``` + +## Uninstall + +To remove HoloViz MCP: + +```bash +uv tool uninstall holoviz-mcp +``` + +To also remove the documentation index and configuration: + +```bash +rm -rf ~/.holoviz-mcp +``` + +## Next Steps + +After installation, configure your IDE or AI assistant: + +- **[Copilot + VS Code](configure-vscode.md)**: Configure for VS Code +- **[Claude Desktop](configure-claude-desktop.md)**: Configure for Claude Desktop +- **[Claude Code](configure-claude-code.md)**: Configure for Claude Code +- **[Cursor](configure-cursor.md)**: Configure for Cursor +- **[Windsurf](configure-windsurf.md)**: Configure for Windsurf + +Or start with a complete tutorial: + +- **[Getting Started Tutorials](../tutorials/getting-started-copilot-vscode.md)**: Choose your tool diff --git a/docs/how-to/installation.md b/docs/how-to/installation.md deleted file mode 100644 index 375ceb1..0000000 --- a/docs/how-to/installation.md +++ /dev/null @@ -1,143 +0,0 @@ -# Installation - -This guide covers different ways to install HoloViz MCP. - -## Install with uv (Recommended) - -The recommended installation method uses [uv](https://docs.astral.sh/uv/), a fast Python package installer. - -### Prerequisites - -First, install uv if you haven't already: - -```bash -# macOS and Linux -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Windows -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -For other installation methods, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/). - -### Install as a Tool - -Install HoloViz MCP as a uv tool: - -```bash -# Basic installation -uv tool install holoviz-mcp - -# Alternative installation with a broad range of PyData packages -uv tool install holoviz-mcp[pydata] - -# Alternative installation with extra packages -uv tool install holoviz-mcp --with altair --with polars -``` - -### Install Chromium - -```bash -holoviz-mcp install chromium -``` - -### Create Documentation Index - -After installation, create the documentation index: - -```bash -holoviz-mcp update index -``` - -**Note**: This process takes 5-10 minutes on first run. - -### Verify Installation - -Test that the server starts correctly: - -```bash -holoviz-mcp -``` - -Press `Ctrl+C` to stop the server. - -## Install with pip - -You can also install HoloViz MCP using pip: - -```bash -pip install holoviz-mcp -``` - -Then install Chromium and create the index as previously described. - -## Install with conda/mamba - -HoloViz MCP is available on conda-forge: - -```bash -conda install -c conda-forge holoviz-mcp -``` - -Or with mamba: - -```bash -mamba install -c conda-forge holoviz-mcp -``` - -Then install Chhromium and create the index as previously described. - -## Docker Installation - -For containerized deployment, see the [Docker Guide](docker.md). - -## Updating - -### Update with uv - -```bash -uv tool update holoviz-mcp -``` - -### Update Documentation Index - -After updating the package, refresh the documentation: - -```bash -holoviz-mcp update index -``` - -## Uninstalling - -### With uv - -```bash -uv tool uninstall holoviz-mcp -``` - -### With pip - -```bash -pip uninstall holoviz-mcp -``` - -### With conda/mamba - -```bash -conda remove holoviz-mcp -``` - -### Clean Up Data - -Remove the documentation index and configuration: - -```bash -rm -rf ~/.holoviz-mcp -``` - -## Next Steps - -After installation, configure your IDE: - -- [IDE Configuration](ide-configuration.md) -- [Getting Started Tutorial](../tutorials/getting-started.md) diff --git a/docs/how-to/serve-apps.md b/docs/how-to/serve-apps.md index ba08fb9..1ea3537 100644 --- a/docs/how-to/serve-apps.md +++ b/docs/how-to/serve-apps.md @@ -4,7 +4,7 @@ ### Prerequisites -- Install the project following the [Installation Guide](../how-to/installation.md). +- Install the project following the [Installation Guide](install-uv.md). ### Steps diff --git a/docs/how-to/troubleshooting.md b/docs/how-to/troubleshooting.md index c250c63..582c5a6 100644 --- a/docs/how-to/troubleshooting.md +++ b/docs/how-to/troubleshooting.md @@ -378,6 +378,6 @@ If you can't resolve the issue: ## Next Steps -- [Configuration](configuration.md): Adjust settings -- [Updates](updates.md): Keep software current +- [Configuration](configure-settings.md): Adjust settings +- [Updates](update-holoviz-mcp.md): Keep software current - [Security](../explanation/security.md): Understand security considerations diff --git a/docs/how-to/updates.md b/docs/how-to/update-holoviz-mcp.md similarity index 97% rename from docs/how-to/updates.md rename to docs/how-to/update-holoviz-mcp.md index 2e338c1..2cb5be4 100644 --- a/docs/how-to/updates.md +++ b/docs/how-to/update-holoviz-mcp.md @@ -178,4 +178,4 @@ holoviz-mcp ## Next Steps - [Troubleshooting](troubleshooting.md): Fix update issues -- [Configuration](configuration.md): Customize after updates +- [Configuration](configure-settings.md): Customize after updates diff --git a/docs/index.md b/docs/index.md index 8fcf5d5..a919b15 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,16 @@ Welcome to the HoloViz MCP documentation! +## Choose Your Tool + +Get started with HoloViz MCP for your preferred AI assistant: + +- **[Claude Code](tutorials/getting-started-claude-code.md)** - Command-line Claude interface +- **[Claude Desktop](tutorials/getting-started-claude-desktop.md)** - Standalone Claude application +- **[GitHub Copilot + VS Code](tutorials/getting-started-copilot-vscode.md)** - Full-featured IDE with Copilot agents +- **[Cursor](tutorials/getting-started-cursor.md)** - AI-first code editor +- **[Windsurf](tutorials/getting-started-windsurf.md)** - Modern development environment + ## What is HoloViz MCP? HoloViz MCP is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) server that provides intelligent access to the [HoloViz](https://holoviz.org/) ecosystem. It enables AI assistants to help you build data visualizations, data tools, dashboards and data apps with [Panel](https://panel.holoviz.org/), [hvPlot](https://hvplot.holoviz.org), [Lumen](https://lumen.holoviz.org/), [Datashader](https://datashader.org/), the rest of the [HoloViz](https://holoviz.org/) ecosystem and your favorite Python libraries. @@ -22,41 +32,16 @@ HoloViz MCP is a [Model Context Protocol](https://modelcontextprotocol.io/introd ## Getting Started -New to HoloViz MCP? Start with our tutorial: - -**[Getting Started Tutorial →](tutorials/getting-started.md)** +New to HoloViz MCP? Choose your tool above to get started with a step-by-step tutorial tailored to your environment. ## Documentation Structure This documentation follows the [Diataxis](https://diataxis.fr/) framework: -### 📖 [Tutorials](tutorials/getting-started.md) -Learning-oriented guides that take you through a series of steps to complete a project. Perfect for beginners! - -- [Getting Started](tutorials/getting-started.md) - -### 🔧 [How-To Guides](how-to/installation.md) -Problem-oriented guides that show you how to solve specific problems and accomplish common tasks. - -- [Installation](how-to/installation.md) -- [IDE Configuration](how-to/ide-configuration.md) -- [Docker Setup](how-to/docker.md) -- [Configuration](how-to/configuration.md) -- [Serve Apps](how-to/serve-apps.md) -- [Updates & Maintenance](how-to/updates.md) -- [Troubleshooting](how-to/troubleshooting.md) - -### 💡 [Explanation](explanation/architecture.md) -Understanding-oriented articles that clarify and illuminate topics, providing background and context. - -- [Architecture](explanation/architecture.md) -- [Available Tools](explanation/tools.md) -- [Security Considerations](explanation/security.md) - -### 📚 [Reference](reference/holoviz_mcp.md) -Information-oriented technical descriptions of the API and implementation details. - -- [API Documentation](reference/holoviz_mcp.md) +- **Tutorials**: Learning-oriented guides that take you through a series of steps to complete a project. Perfect for beginners! +- **How-to**: Problem-oriented guides that show you how to solve specific problems and accomplish common tasks. +- **Explanation**: Understanding-oriented articles that clarify and illuminate topics, providing background and context. +- **Reference**: Information-oriented technical descriptions of the API and implementation details. ## Quick Links diff --git a/docs/tutorials/copilot.md b/docs/tutorials/copilot.md deleted file mode 100644 index e14b1af..0000000 --- a/docs/tutorials/copilot.md +++ /dev/null @@ -1,134 +0,0 @@ - -# Using HoloViz MCP with Github Copilot - -In this tutorial, you'll learn how to use the HoloViz MCP server with GitHub Copilot in VS Code. - -!!! tip "What you'll learn" - - - How to use HoloViz MCP resources to enhance Copilot's responses - - How to add custom Copilot agents optimized for HoloViz MCP - - How to create a plot using Copilot + HoloViz MCP - - How to build a dashboard using Copilot + HoloViz MCP - -!!! note "Prerequisites" - - - VS Code installed - - GitHub Copilot subscription and extension installed - - HoloViz MCP server installed and configured ([Installation guide](../how-to/installation.md)) - ---- - -## Starting the MCP Server - -Start the Holoviz MCP Server: - -- In VS Code, open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) -- Type "MCP: List Servers" and press Enter -- Choose the "holoviz" server -- Select "Start Server" - -Repeat 1.+2. and verify that the `holoviz` mcp server is now running. - -![HoloViz MCP Running](../assets/images/holoviz-mcp-vscode-running.png) - -## Using HoloViz Agents - -### Installing the Agents - -[Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents) enable you to configure the AI to adopt different personas tailored to specific development roles and tasks. To install the `holoviz-mcp` agents: - -- Open a terminal in VS Code (`` Ctrl+` `` or `Terminal > New Terminal`). -- Run the following command: - - ```bash - holoviz-mcp install copilot - ``` - -- Wait for the command to complete successfully. - -You should see output confirming that agents were installed to `.github/agents/`. - -!!! note "What's happening" - This command installs custom Copilot agents specifically designed for HoloViz development. These agents understand the `holoviz-mcp` server and can use it to understand the architecture patterns and best practices for Panel, hvPlot, and other HoloViz libraries. - -!!! tip - Run `holoviz-mcp install copilot --skills` to populate the `.github/skills` folder too. See [Use Agent Skills in VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills) for more info. - ---- - -### Creating a Plan with the HoloViz App Planner Agent - -Instead of diving straight into code, let's use the specialized agent to plan our application architecture. - -- In the Copilot Chat interface, click the **Set Agent** dropdown. -- Select **`HoloViz App Planner`** from the list. - -![HoloViz App Planner](../assets/images/copilot-holoviz-app-planner.png) - -- Type the following prompt: - - ```text - Create a plan for a stock dashboard that displays historical prices and trading volume - ``` - -- Press Enter and wait for the agent to respond. - -![Copilot Dashboard Plan](../assets/images/copilot-dashboard-plan.png) - -!!! note "What's happening" - The HoloViz App Planner agent analyzes your requirements and creates an architecture plan following HoloViz best practices. This ensures your application is well-structured before you write any code. - ---- - -### Implementing the Dashboard - -Now that you have a plan, let's ask Copilot to help implement it. - -- In the Copilot Chat, respond to the plan with: - - ```text - Implement the plan outlined above. - ``` - -- Copilot will generate the code for your dashboard and test it. - -To learn more check out the [Weather Dashboard Tutorial](weather-dashboard.md)! - ---- - -## Using HoloViz Resources - -MCP resources contain curated knowledge that enhances Copilot's understanding of specific frameworks. Let's load the hvPlot best practice skills and use them to create a basic data visualization. - -- In the Copilot Chat Interface, click "Add Context" (`CTRL + '`) -- Select "MCP Resources". -- You'll see a list of available resources. Select **`holoviz_hvplot`**. - -![HoloViz MCP Resources](../assets/images/holoviz-mcp-resources.png) - -- Notice in the chat interface that the resource is now added to the context. - -![HvPlot Resource Added](../assets/images/holoviz-mcp-vscode-resource-added.png) - -- Ask the agent: - - ```bash - Please create a basic hvplot visualization in a script.py file. - ``` - -![HvPlot Plot](../assets/images/holoviz-mcp-vscode-resource-plot.png) - -!!! tip - You can add multiple resources to the context. Try browsing and adding `holoviz_panel` as well to get Panel-specific guidance. - ---- - -## What You've Learned - -In this tutorial, you've learned how to: - -✅ **Use specialized agents** – You used the HoloViz App Planner agent to design your application architecture. - -✅ **Use specialized resources** – You loaded HoloViz best practice skills into Copilot's context using MCP resources. - ---- diff --git a/docs/tutorials/display-server.md b/docs/tutorials/display-server.md deleted file mode 100644 index dca42c4..0000000 --- a/docs/tutorials/display-server.md +++ /dev/null @@ -1,283 +0,0 @@ -# Tutorial: Building Your First Visualizations with the Display Server - -In this tutorial, you'll learn how to use the HoloViz Display Server to create, view, and share interactive visualizations. By the end, you'll have created multiple visualizations, learned how to manage them, and understand how to interact with the server programmatically. - -This foundation will enable you to effectively use the [`holoviz_display`](display-tool.md) MCP tool and integrate visualization capabilities into your AI-assisted workflows. - -!!! warning - The Display Server is currently in alpha. Changes between versions may make existing snippets inaccessible. Use for exploration and testing only - **do not rely on the Display Server for persistent storage of important work!** - - - -## What You'll Learn - -By following this tutorial, you will: - -- Install and start the Display Server -- Create your first interactive visualization using the web interface -- View and browse your visualizations -- Learn about different execution methods -- Create visualizations programmatically using the REST API -- Manage and organize your visualization collection - -## What You'll Need - -- Python 3.11 or later installed on your system -- Basic familiarity with Python and data visualization -- A web browser - -## Step 1: Install the Display Server - -The Display Server is included with the `holoviz-mcp` package. Please [make sure its installed](getting-started.md/#step-1-install-holoviz-mcp). - -## Step 2: Start the Server - -Now that you have the server installed, let's start it: - -```bash -display-server -``` - -You should see output like this: - -```bash -Starting Display Server... -Display Server running at: - - - Add: http://localhost:5005/add - - Feed: http://localhost:5005/feed - - Admin: http://localhost:5005/admin - - API: http://localhost:5005/api -``` - -Great! Your server is now running. Keep this terminal window open while you work through the tutorial. - -!!! info "Server Configuration" - For this tutorial, we're using the default settings. You can customize the server with different ports and address: - - ```bash - # Custom port - display-server --port 5004 - - # Custom address and port - display-server --address 0.0.0.0 --port 8080 - ``` - -## Step 3: Create Your First Visualization - -Let's create your first interactive visualization using the web interface. - -Open your web browser and navigate to [`http://localhost:5005/add`](http://localhost:5005/add). You'll see a form for creating visualizations. - -Now, let's create a simple bar chart. In the code editor, enter the following Python code: - -```python -import pandas as pd -import hvplot.pandas - -df = pd.DataFrame({ - 'Product': ['A', 'B', 'C', 'D'], - 'Sales': [120, 95, 180, 150] -}) - -df.hvplot.bar(x='Product', y='Sales', title='Sales by Product') -``` - -This code creates a simple dataset with product sales and generates an interactive bar chart. - -Next, fill in the form fields: - -- **Name**: Enter "Product Sales Chart" -- **Description**: Enter "An interactive bar chart showing sales by product" -- **Execution Method**: Make sure `jupyter` is selected (this should be the default) - -Click the **Submit** button. You should see a success message with a link to view your visualization. - -![Add Page](../assets/images/display-server-add.png) - -!!! tip "About Available Packages" - The Display Server can use any packages installed in your Python environment. To use additional visualization libraries or data processing tools, install them in the same environment where you're running the server. - -## Step 4: View Your Visualization - -After submitting your code, click the link provided on the Add page. This will take you to a unique URL like `http://localhost:5005/view?id=abc123` where your visualization is displayed. - -![View Page](../assets/images/display-manager-view.png) - -You should now see your interactive bar chart! Try hovering over the bars - you'll notice they're interactive, showing additional information as you interact with them. - -!!! success "Congratulations!" - You've just created your first interactive visualization with the Display Server. Each visualization gets its own unique URL that you can bookmark or share. - -## Step 5: Browse Your Visualizations - -As you create more visualizations, you'll want an easy way to browse them. Let's check out the Feed page. - -Navigate to [`http://localhost:5005/feed`](http://localhost:5005/feed). Here you'll see a list view of your recent visualizations, including: - -- The visualization name and description -- When it was created -- A direct link to view it - -The Feed page automatically updates to show your most recent work. - -![Feed Page](../assets/images/display-server-feed.png) - -## Step 6: Manage Your Collection - -Now let's explore the Admin page where you can manage all your visualizations. - -Visit [`http://localhost:5005/admin`](http://localhost:5005/admin). This page provides a table view of all your snippets where you can: - -- See detailed information about each snippet -- Delete visualizations you no longer need -- Search and filter through your collection - -![Admin Page](../assets/images/display-server-manage.png) - -Feel free to create a few more visualizations to see how the Feed and Admin pages help you organize your work. - -## Understanding Execution Methods - -Before we move on to programmatic creation, let's understand the two ways the Display Server can execute your code. - -### Jupyter Method (Default) - -This method executes code like you would in a Jupyter notebook - the last expression is automatically displayed: - -```python -import pandas as pd -df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]}) -df # This is displayed -``` - -### Panel Method - -This method is for creating more complex Panel applications with multiple components. You'll need to use `.servable()` to mark which components should be displayed: - -```python -import panel as pn - -pn.extension() - -# Create components -pn.Column( - pn.pane.Markdown("# My Dashboard"), - pn.widgets.Button(name="Click me") -).servable() -``` - -## Step 7: Create Visualizations Programmatically - -Now that you're comfortable with the web interface, let's learn how to create visualizations programmatically using the REST API. This is useful for automation and integration with other tools. - -Create a new file called `script.py` in your working directory: - -```python -import requests - -# Create a visualization -response = requests.post( - "http://localhost:5005/api/snippet", - headers={"Content-Type": "application/json"}, - json={ - "code": "a='Hello, HoloViz MCP!'\na", - "name": "Hello World", - "method": "jupyter" - } -) - -print(f"Status Code: {response.status_code}") -print(f"Response: {response.json()}") -``` - -Save the file and run it: - -```bash -python script.py -``` - -You should see output showing the status code (200 for success) and the response containing the URL of your new visualization. Visit that URL to see your programmatically-created visualization! - -```bash -Status Code: 200 -Response: {'id': '6541b6b3-2b16-4ef5-ac4f-c8fe6d59ff1c', 'created_at': '2026-01-10T10:23:55.270232+00:00', 'url': 'http://localhost:5005/view?id=6541b6b3-2b16-4ef5-ac4f-c8fe6d59ff1c'} -``` - -!!! success "Well Done!" - You can now create visualizations both interactively through the web interface and programmatically through the REST API. - -## Understanding Storage - -All your visualizations are stored in a local SQLite database. By default, this is located at: - -``` -~/.holoviz-mcp/snippets/snippets.db -``` - -The database stores: - -- Your Python code and execution results -- Metadata like names, descriptions, and timestamps -- Detected packages and extensions - -!!! tip "Custom Database Location" - You can specify a custom database location by setting the `DISPLAY_DB_PATH` environment variable before starting the server. - -!!! warning "Database Compatibility After Updates" - If you update `holoviz-mcp`, your existing database may become incompatible due to schema changes. If you encounter errors after updating, delete the database file at `~/.holoviz-mcp/snippets/snippets.db` (or your custom location). **Note:** This will remove all saved visualizations! - -## Step 8: Stop the Display Server - -When you're done with the tutorial, press `CTRL+C` in the terminal to stop the server. - -## Troubleshooting Common Issues - -As you work with the Display Server, you might encounter some common issues. Let's learn how to resolve them. - -### ModuleNotFoundError - -**What's happening?** When you create a visualization that uses a package not installed in your environment, you'll see a `ModuleNotFoundError`. - -![Module Not Found](../assets/images/display-server-module-not-found.png) - -**Why does this happen?** The Display Server runs in a specific Python environment and can only access packages installed in that environment. When your visualization code imports a package like `scikit-learn` or `plotly`, Python looks for it in the active environment. - -**How to fix it:** - -1. Identify the missing package from the error message (e.g., "No module named 'sklearn'") -2. Install it in the same environment where the Display Server is running: - -```bash -pip install scikit-learn -``` - -3. **Important**: You don't need to restart the Display Server - just try creating your visualization again! - -!!! tip "Pro Tip" - To avoid this issue, install commonly used data science packages upfront: - - ```bash - pip install scikit-learn pandas numpy matplotlib seaborn plotly altair - ``` - -## What You've Learned - -Congratulations! You've completed the Display Server tutorial. You now know how to: - -- ✓ Install and start the Display Server -- ✓ Create interactive visualizations using the web interface -- ✓ View and browse your visualizations -- ✓ Manage your visualization collection -- ✓ Understand the different execution methods -- ✓ Create visualizations programmatically using the REST API - -## Next Steps - -Now that you understand the basics, you can explore more advanced topics: - -- **[Use the Display Server with the MCP tool](./display-tool.md)** - Integrate the Display Server with AI assistants -- **[Learn about the Display System architecture](../explanation/display-server.md)** - Understand how the Display Server works under the hood -- **[Configure for production deployments](../how-to/serve-apps.md)** - Set up the server for team use or production environments - -Happy visualizing! diff --git a/docs/tutorials/display-system.md b/docs/tutorials/display-system.md new file mode 100644 index 0000000..35434ed --- /dev/null +++ b/docs/tutorials/display-system.md @@ -0,0 +1,392 @@ +# Tutorial: Building Visualizations with the Display System + +In this tutorial, you'll learn how to use the HoloViz Display System to create, view, and share interactive visualizations. You'll explore both standalone usage and AI-assisted workflows. By the end, you'll have created multiple visualizations and understand how to integrate visualization capabilities into your development workflow. + +!!! warning "Alpha Software" + The Display System is currently in alpha. Changes between versions may make existing snippets inaccessible. Use for exploration and testing only - **do not rely on the Display System for persistent storage of important work!** + + + +## What You'll Learn + +By following this tutorial, you will: + +- Understand what the Display System is and its two modes of operation +- Install and start the Display Server +- Create visualizations using the web interface (standalone mode) +- Create visualizations using AI assistants (MCP tool mode) +- View, browse, and manage your visualizations +- Understand execution methods (Jupyter vs Panel) +- Create visualizations programmatically using the REST API + +## What You'll Need + +- Python 3.11 or later installed on your system +- HoloViz MCP installed (`uv tool install holoviz-mcp[pydata]`) +- Basic familiarity with Python and data visualization +- A web browser +- (Optional) An AI assistant configured with HoloViz MCP for Part 2 + +## Understanding the Display System + +The Display System consists of two components: + +1. **Display Server**: A local web server that runs visualizations and provides a browser interface +2. **holoviz_display tool**: An MCP tool that lets AI assistants create visualizations + +You can use the Display System in two ways: + +- **Standalone**: Start the server manually and create visualizations via the web interface or REST API +- **With AI**: The MCP server automatically starts the Display Server, and AI assistants use it via the `holoviz_display` tool + +## Part 1: Using the Display Server Standalone + +### Step 1: Install the Display Server + +The Display Server is included with the `holoviz-mcp` package. If you haven't installed it yet, see one of the [getting started guides](getting-started-copilot-vscode.md). + +### Step 2: Start the Server + +Open your terminal and start the Display Server: + +```bash +display-server +``` + +You should see output like this: + +```bash +Starting Display Server... +Display Server running at: + + - Add: http://localhost:5005/add + - Feed: http://localhost:5005/feed + - Admin: http://localhost:5005/admin + - API: http://localhost:5005/api +``` + +Great! Your server is now running. Keep this terminal window open while you work through the tutorial. + +!!! info "Server Configuration" + You can customize the server with different ports and addresses: + + ```bash + # Custom port + display-server --port 5004 + + # Custom address and port + display-server --address 0.0.0.0 --port 8080 + ``` + +### Step 3: Create Your First Visualization + +Let's create your first interactive visualization using the web interface. + +Open your web browser and navigate to [http://localhost:5005/add](http://localhost:5005/add). You'll see a form for creating visualizations. + +Now, let's create a simple bar chart. In the code editor, enter the following Python code: + +```python +import pandas as pd +import hvplot.pandas + +df = pd.DataFrame({ + 'Product': ['A', 'B', 'C', 'D'], + 'Sales': [120, 95, 180, 150] +}) + +df.hvplot.bar(x='Product', y='Sales', title='Sales by Product') +``` + +This code creates a simple dataset with product sales and generates an interactive bar chart. + +Next, fill in the form fields: + +- **Name**: Enter "Product Sales Chart" +- **Description**: Enter "An interactive bar chart showing sales by product" +- **Execution Method**: Make sure `jupyter` is selected (this should be the default) + +Click the **Submit** button. You should see a success message with a link to view your visualization. + +![Add Page](../assets/images/display-server-add.png) + +!!! tip "About Available Packages" + The Display Server can use any packages installed in your Python environment. To use additional visualization libraries or data processing tools, install them in the same environment where you're running the server. + +### Step 4: View Your Visualization + +After submitting your code, click the link provided. This will take you to a unique URL like `http://localhost:5005/view?id=abc123` where your visualization is displayed. + +![View Page](../assets/images/display-manager-view.png) + +You should now see your interactive bar chart! Try hovering over the bars - you'll notice they're interactive, showing additional information as you interact with them. + +!!! success "Congratulations!" + You've just created your first interactive visualization with the Display Server. Each visualization gets its own unique URL that you can bookmark or share. + +### Step 5: Browse Your Visualizations + +As you create more visualizations, you'll want an easy way to browse them. Let's check out the Feed page. + +Navigate to [http://localhost:5005/feed](http://localhost:5005/feed). Here you'll see a list view of your recent visualizations, including: + +- The visualization name and description +- When it was created +- A direct link to view it + +The Feed page automatically updates to show your most recent work. + +![Feed Page](../assets/images/display-server-feed.png) + +### Step 6: Manage Your Collection + +Now let's explore the Admin page where you can manage all your visualizations. + +Visit [http://localhost:5005/admin](http://localhost:5005/admin). This page provides a table view of all your snippets where you can: + +- See detailed information about each snippet +- Delete visualizations you no longer need +- Search and filter through your collection + +![Admin Page](../assets/images/display-server-manage.png) + +### Step 7: Create Visualizations Programmatically + +Now that you're comfortable with the web interface, let's learn how to create visualizations programmatically using the REST API. This is useful for automation and integration with other tools. + +Create a new file called `script.py`: + +```python +import requests + +# Create a visualization +response = requests.post( + "http://localhost:5005/api/snippet", + headers={"Content-Type": "application/json"}, + json={ + "code": "a='Hello, HoloViz MCP!'\na", + "name": "Hello World", + "method": "jupyter" + } +) + +print(f"Status Code: {response.status_code}") +print(f"Response: {response.json()}") +``` + +Run it: + +```bash +python script.py +``` + +You should see output showing the status code (200 for success) and the response containing the URL of your new visualization! + +!!! success "Well Done!" + You can now create visualizations both interactively through the web interface and programmatically through the REST API. + +## Part 2: Using the Display System with AI Assistants + + + +Now let's explore using the Display System through AI assistants. This enables you to create visualizations using natural language! + +### Prerequisites + +- An AI assistant configured to use HoloViz MCP (see [getting started guides](getting-started-copilot-vscode.md)) +- The Palmer Penguins dataset: [Download penguins.csv](../assets/data/penguins.csv) + +### Step 1: Start the MCP Server + +In your IDE, start the HoloViz MCP server. The Display Server will start automatically. + +!!! note + If you're still running the standalone Display Server from Part 1, stop it with `CTRL+C` before starting the MCP server. + +### Step 2: Create Your First AI-Assisted Visualization + +Open your AI assistant and ask: + +> My dataset is penguins.csv. What is the distribution of the 'species' column? Use the #holoviz_display tool + +Your AI assistant will use the `holoviz_display` tool and respond with: + +```bash +✓ Visualization created successfully! +View at: http://localhost:5005/view?id={snippet_id} +``` + +Click the URL. You should see an interactive bar chart showing the count of each penguin species! + +![Interactive Bar Chart](../assets/images/display-tool-view.png) + +!!! success "Checkpoint" + If you see the species distribution in your browser, you've successfully created your first AI-assisted visualization! The chart should be interactive - try hovering over the bars. + +!!! tip "VS Code Users" + If the AI doesn't use the `holoviz_display` tool automatically, include `#holoviz_display` in your prompt as shown above. + +### Step 3: Explore Relationships with Scatter Plots + +Let's explore the relationship between penguin measurements. Ask your AI: + +> Show me a scatter plot of 'flipper_length_mm' vs 'body_mass_g' + +The AI will create a new visualization with: + +- A scatter plot showing the relationship between flipper length and body mass +- Interactive tooltips when hovering over points +- The ability to zoom and pan through the data + +![Interactive Scatter Plot](../assets/images/display-tool-view2.png) + +!!! tip "What you're learning" + Each visualization gets its own unique URL. The `holoviz_display` tool handles different chart types automatically based on your natural language request. + +### Step 4: Combine Multiple Analysis Steps + +You can ask the AI to perform several steps in one message: + +> Filter the dataset for species 'Chinstrap' and calculate the median 'body_mass_g'. Then display and discuss the result. + +The AI will: + +1. Filter the data for Chinstrap penguins +2. Calculate the median body mass +3. Create a visualization showing the result with comparisons +4. Provide analysis and discussion of the findings + +### Step 5: Create Multi-Plot Layouts + +Create visualizations that combine multiple plots: + +> Create a histogram of 'bill_length_mm' and a box plot of 'flipper_length_mm' side by side. + +The AI will create a layout with both plots displayed together! + +### Step 6: Build Interactive Dashboards + +For advanced use cases, create interactive dashboards with widgets: + +> Create an interactive dashboard for the penguins dataset with dropdown filters for species and island. + +The visualization will include: + +- Interactive widgets (dropdowns, sliders, etc.) +- Plots that update automatically when you change widget values +- A complete dashboard layout + +![Penguins Dashboard](../assets/images/display-tool-feed-dashboard.png) + +!!! success "Achievement unlocked" + You've created an interactive dashboard using natural language! The tool uses Panel's execution methods to enable full applications with reactive components. + +### Step 7: Refine Your Visualizations + +If results aren't what you expected, continue the conversation: + +- **Adjust the visualization**: "Can you color the points by species?" or "Add a trend line to the scatter plot." +- **Modify the data**: "Show only penguins with body mass greater than 4000g." +- **Change the layout**: "Make the chart wider" or "Display these charts side by side." + +The AI will iterate on your existing work, creating new visualizations that build on previous ones. + +## Understanding Execution Methods + +The Display System supports two execution methods: + +### Jupyter Method (Default) + +Executes code like a Jupyter notebook - the last expression is automatically displayed: + +```python +import pandas as pd +df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]}) +df # This is displayed +``` + +### Panel Method + +For creating complex Panel applications with multiple components. Use `.servable()` to mark components: + +```python +import panel as pn + +pn.extension() + +pn.Column( + pn.pane.Markdown("# My Dashboard"), + pn.widgets.Button(name="Click me") +).servable() +``` + +## Understanding Storage + +All visualizations are stored in a local SQLite database at: + +``` +~/.holoviz-mcp/snippets/snippets.db +``` + +The database stores: + +- Your Python code and execution results +- Metadata (names, descriptions, timestamps) +- Detected packages and extensions + +!!! tip "Custom Database Location" + Set the `DISPLAY_DB_PATH` environment variable before starting the server to use a custom location. + +!!! warning "Database Compatibility" + After updating `holoviz-mcp`, your database may become incompatible. If you encounter errors, delete the database file (this will remove all saved visualizations). + +## Troubleshooting + +### ModuleNotFoundError + +**Problem**: Your visualization code imports a package not installed in your environment. + +**Solution**: Install the missing package: + +```bash +pip install package-name +``` + +You don't need to restart the server - just try creating your visualization again! + +### Display Server Not Available (MCP mode) + +**Problem**: AI says the display server isn't available. + +**Solution**: Verify the MCP server is running and check startup logs for "Panel server started successfully". + +### Visualization Errors + +**Problem**: A visualization shows an error. + +**Solution**: Ask your AI to fix it based on the error message, or start with a simpler visualization to verify the system is working. + +For comprehensive help, see the [Troubleshooting Guide](../how-to/troubleshooting.md). + +## What You've Learned + +Congratulations! You've completed the Display System tutorial. You now know how to: + +✅ Start the Display Server standalone or via MCP +✅ Create visualizations using the web interface +✅ Create visualizations via REST API +✅ Create visualizations using AI assistants and natural language +✅ View, browse, and manage your visualizations +✅ Understand execution methods +✅ Build interactive dashboards +✅ Troubleshoot common issues + +## Next Steps + +Now that you understand the Display System, you can: + +- **[Learn about the Display System architecture](../explanation/display-system.md)** - Understand how it works under the hood +- **[Configure for production](../how-to/configure-display-server.md)** - Set up for team use or production +- **[Build advanced projects](stock-analysis-copilot-vscode.md)** - Apply your skills to real-world projects + +Happy visualizing! 🚀 diff --git a/docs/tutorials/display-tool.md b/docs/tutorials/display-tool.md deleted file mode 100644 index 3d559da..0000000 --- a/docs/tutorials/display-tool.md +++ /dev/null @@ -1,179 +0,0 @@ -# Tutorial: Creating your first Visualization with the holoviz_display tool - -In this tutorial, we will create visualizations using the `holoviz_display` tool through an AI assistant. By the end, you will have created several interactive visualizations and learned how to view them. - -!!! info "What you'll accomplish" - - Use the `holoviz_display` tool - - Create and display a bar chart through your AI assistant - - Build and display an interactive scatter plot - - Learn to troubleshoot common issues - -!!! warning - The `holoviz_display` tool is currently in alpha. Changes between versions may make existing snippets inaccessible. Use for exploration and testing only - **do not rely on the `holoviz_display` tool for persistent storage of important work!** - - - -## Prerequisites - -Before starting, ensure you have: - -- HoloViz MCP installed (`pip install holoviz-mcp`) -- An AI assistant configured to use HoloViz MCP (Claude Desktop, VS Code with Copilot, etc.) -- Python 3.11 or later - -## Step 0: Start the MCP Server - -In your IDE or development environment make sure to [start the HoloViz MCP server](getting-started.md/#start-the-server). - -!!! note - If the [Display Server](display-server.md) is already running separately, please stop it using CTRL+C. The MCP server will automatically start the Display Server. - -## Step 1: Load the Penguins Dataset - -For this tutorial, we'll use the Palmer Penguins dataset, which contains measurements of penguin species from Antarctica. Download the dataset: - -Right-click [penguins.csv](../assets/data/penguins.csv) and save it to your working directory. - -## Step 2: Create Your First Visualization - -Now let's explore the penguins dataset. Open your AI assistant and ask: - -> My dataset is penguins.csv. What is the distribution of the 'species' column? Use the #holoviz_display tool - -Your AI assistant will use the `holoviz_display` tool and respond with something like: - -```bash -✓ Visualization created successfully! -View at: http://localhost:5005/view?id={snippet_id} -``` - -Click the URL. You should see: - -- An interactive bar chart showing the count of each penguin species - -![Interactive Bar Chart](../assets/images/display-tool-view.png) - -!!! success "Checkpoint" - If you see the species distribution in your browser, you've successfully created your first visualization! The chart should be interactive - try hovering over the bars. - -!!! tip "VS Code" - If the LLM does not use the `holoviz_display` tool, you can make it more clear by including `#holoviz_display` in the chat as we did above. - -## Step 3: Explore Relationships with Scatter Plots - -Let's explore the relationship between penguin measurements. Ask your AI assistant: - -> Show me a scatter plot of 'flipper_length_mm' vs 'body_mass_g' - -The AI will create a new visualization. Click the new URL to see: - -- A scatter plot showing the relationship between flipper length and body mass -- Interactive tooltips when hovering over points -- The ability to zoom and pan through the data - -![Interactive Scatter Plot](../assets/images/display-tool-view2.png) - -!!! tip "What you're learning" - Each visualization gets its own unique URL that you can bookmark or share. The `holoviz_display` tool handles different chart types automatically based on your natural language request. - -## Step 3a: Combine Multiple Requests - -You can ask the AI to perform several steps in one message. This helps you build complex analyses without multiple back-and-forths. Try: - -> Filter the dataset for species 'Chinstrap' and calculate the median 'body_mass_g'. Then display and discuss the result. - -The AI will: - -1. Filter the data for Chinstrap penguins -2. Calculate the median body mass -3. Create a visualization showing the result with comparisons to other species -4. Provide analysis and discussion of the findings - -This demonstrates how `holoviz_display` can handle multi-step analytical workflows in a single request. - -## Step 4: Browse and Refine Your Visualizations - -### Browse Your Work - -Now let's see all your visualizations together. In your browser, navigate to: - -```bash -http://localhost:5005/feed -``` - -You should see: - -- All your visualizations with names and descriptions -- Creation timestamps -- "Full Screen" and "Copy Code" buttons for each - -![Feed](../assets/images/display-tool-feed.png) - -The Feed page automatically updates when new visualizations are created! - -### Refine Results - -If results aren't what you expected, you can refine them by continuing the conversation: - -- **Adjust the visualization**: "Can you color the points by species?" or "Add a trend line to the scatter plot." -- **Modify the data**: "Show only penguins with body mass greater than 4000g." -- **Change the layout**: "Make the chart wider" or "Display these charts side by side." - -The AI will iterate on your existing work based on your feedback, creating new visualizations that build on previous ones. - -## Step 5: Create Multi-Plot Layouts - -You can create visualizations that combine multiple plots for comprehensive analysis. Ask your AI: - -> Create a histogram of 'bill_length_mm' and a box plot of 'flipper_length_mm' side by side. - -The AI will create a layout with both plots displayed together, making it easy to compare different aspects of the data at a glance. When you view it in the Feed page, you'll see a descriptive title and the combined visualization. - -## Step 6: Build Interactive Dashboards - -For more advanced use cases, you can create interactive dashboards with widgets. Ask your AI: - -> Create an interactive dashboard for the penguins dataset with dropdown filters for species and island. - -The visualization will include: - -- Interactive widgets (dropdowns, sliders, etc.) -- Plots that update automatically when you change widget values -- A complete dashboard layout - -![Penguins Dashboard](../assets/images/display-tool-feed-dashboard.png) - -!!! success "Achievement unlocked" - You've created an interactive dashboard! Behind the scenes, the tool uses Panel's execution methods to enable full applications with reactive components. - -## What You've Learned - -Through this tutorial, you have: - -- ✅ Created data visualizations using natural language queries -- ✅ Explored the Palmer Penguins dataset with various chart types -- ✅ Combined multiple analysis steps in single requests -- ✅ Refined and iterated on visualizations through conversation -- ✅ Built interactive dashboards with widgets and layouts - -## Next Steps - -Now that you've mastered the basics, you can: - -- **Learn about the Display Server**: Read the [Display Server tutorial](./display-server.md) to understand the architecture - -## Troubleshooting - -### Tool not available - -If your AI says the `holoviz_display` tool isn't available, ensure the MCP server is running and your AI assistant is configured to use HoloViz MCP. - -### Display server not available - -If you see this error, verify the MCP server is running and look for "Panel server started successfully" in the startup logs. - -### Visualization errors - -If a visualization shows an error, try asking your AI to fix it based on the error message, or start with a simpler visualization to verify the system is working. - -**For comprehensive help**, see the [troubleshooting guide](../how-to/troubleshooting.md) or review the [Display System architecture](../explanation/display-server.md). diff --git a/docs/tutorials/getting-started-claude-code.md b/docs/tutorials/getting-started-claude-code.md new file mode 100644 index 0000000..14369d5 --- /dev/null +++ b/docs/tutorials/getting-started-claude-code.md @@ -0,0 +1,198 @@ +# Getting Started with HoloViz MCP for Claude Code + +This tutorial will guide you through installing and using HoloViz MCP with Claude Code (the command-line interface). By the end, you'll have HoloViz MCP running and be able to ask Claude questions about Panel components directly from your terminal! + +!!! tip "What you'll learn" + - How to install HoloViz MCP + - How to configure it with Claude Code + - How to use it to get help building Panel applications + - How to verify everything is working correctly + - How to build your first Panel dashboard + +!!! note "Prerequisites" + Before you begin, ensure you have: + + - **Python 3.11 or newer** installed on your system + - **[uv](https://docs.astral.sh/uv/)** package installer + - **Claude Code CLI** installed ([Installation guide](https://claude.ai/download)) + +## Step 1: Install HoloViz MCP + +Open your terminal and install HoloViz MCP as a uv tool: + +```bash +uv tool install holoviz-mcp[pydata] +``` + +This command installs HoloViz MCP globally, making it available for Claude Code to reference. + +!!! tip "What's happening?" + The uv tool manager creates an isolated environment for HoloViz MCP and installs all necessary dependencies. + + The extra `pydata` dependencies are added to install a wide range of python data related packages. We will assume these are installed throughout this guide. You can replace them with your favorite dependencies for your own work. + +## Step 2: Install Chromium + +Install [Chromium](https://playwright.dev/docs/browsers) to enable the holoviz-mcp server to take screenshots: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Step 3: Create the Documentation Index + +HoloViz MCP needs to index the HoloViz documentation to provide intelligent answers. Run: + +```bash +holoviz-mcp update index +``` + +**⏱️ This will take 5-10 minutes** as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Step 4: Configure Claude Code + +Now let's configure Claude Code to use the HoloViz MCP server: + +```bash +claude mcp add holoviz --transport stdio --scope user -- holoviz-mcp +``` + +This will update your `~/.claude.json` file with the HoloViz MCP server configuration. + +## Step 5: Verify Installation + +Let's verify that HoloViz MCP is working correctly! + +### Check Server Status + +In Claude Code, run the `/mcp` command to verify the status of the HoloViz MCP server: + +```bash +claude /mcp +``` + +You should see `holoviz` listed as an available MCP server. + +![Claude Code HoloViz MCP](../assets/images/claude-code-holoviz-mcp.png) + +### Test with Claude + +Open a chat with Claude Code and try these questions: + +**Component Discovery**: + +```text +What Panel components are available for user input? +``` + +**Component Details**: + +```text +What parameters does the Panel Button component accept? +``` + +If Claude provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 + +## Step 6: Build Your First Dashboard + +Now that everything is set up, let's build a simple dashboard. + +**Ask Claude:** + +```text +Create a Panel dashboard that displays a slider and shows the square of the slider's value. Save it to app.py +``` + +Claude will provide code using HoloViz MCP's knowledge of Panel components! + +Save the code to `app.py` and run it: + +```bash +panel serve app.py --show +``` + +Your dashboard will open in your default web browser! + +## Step 7: Using the Display Tool + +HoloViz MCP includes a powerful display tool that can render visualizations directly. Ask Claude: + +```bash +Use the holoviz_display tool to show me a simple hvplot visualization of random data. +``` + +Claude will use the display tool to generate and display the visualization. See the [Display System tutorial](display-system.md) for more details. + +## What's Next? + +Now that you have HoloViz MCP running with Claude Code, explore more: + +- **[Display System](display-system.md)**: Learn about the display server for visualizations +- **[Stock Analysis](stock-analysis-claude-code.md)**: Create a real-world stock analysis report +- **[Weather Dashboard](weather-dashboard-claude-code.md)**: Create an interactive weather visualization + +## Troubleshooting + +### Installation Issues + +**Problem**: `uv: command not found` + +**Solution**: Install uv by following the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) + +**Problem**: `claude: command not found` + +**Solution**: Install Claude Code by following the [installation guide](https://claude.ai/download) + +**Problem**: Installation takes too long + +**Solution**: This is normal! The first installation downloads many dependencies. Subsequent updates are much faster. + +### Configuration Issues + +**Problem**: `/mcp` command doesn't show holoviz server + +**Solution**: + +1. Check that the configuration command completed successfully +2. Verify `~/.claude.json` contains the holoviz server configuration +3. Try running the server directly: `holoviz-mcp` +4. Run `claude mcp list` to see configured servers + +**Problem**: Claude doesn't recognize Panel components + +**Solution**: + +1. Check that the documentation index completed (Step 3) +2. Verify your configuration is correct: `claude mcp list` +3. Try running the server directly in terminal: `holoviz-mcp` +4. Check Claude Code logs for errors + +### Server Issues + +**Problem**: MCP server won't connect + +**Solution**: + +1. Verify Python 3.11+ is installed: `python --version` +2. Check uv installation: `uv --version` +3. Try running the server directly: `holoviz-mcp` +4. Check the Claude Code logs for errors + +For more help, see the [Troubleshooting Guide](../how-to/troubleshooting.md) or join the [HoloViz Discord](https://discord.gg/AXRHnJU6sP). + +## Summary + +In this tutorial, you: + +✅ Installed HoloViz MCP using uv +✅ Created the documentation index +✅ Installed Chromium +✅ Configured Claude Code +✅ Verified the installation +✅ Built your first Panel dashboard +✅ Learned about the display tool +✅ Learned how to work on projects with Claude Code + +You're now ready to use HoloViz MCP with Claude Code to accelerate your Panel development from the command line! Happy coding! 🚀 diff --git a/docs/tutorials/getting-started-claude-desktop.md b/docs/tutorials/getting-started-claude-desktop.md new file mode 100644 index 0000000..72417a9 --- /dev/null +++ b/docs/tutorials/getting-started-claude-desktop.md @@ -0,0 +1,190 @@ +# Getting Started with HoloViz MCP for Claude Desktop + +This tutorial will guide you through installing and using HoloViz MCP with Claude Desktop. By the end, you'll have HoloViz MCP running and be able to ask Claude questions about Panel components! + +!!! tip "What you'll learn" + - How to install HoloViz MCP + - How to configure it with Claude Desktop + - How to use it to get help building Panel applications + - How to verify everything is working correctly + - How to build your first Panel dashboard + +!!! note "Prerequisites" + Before you begin, ensure you have: + + - **Python 3.11 or newer** installed on your system + - **[uv](https://docs.astral.sh/uv/)** package installer + - **Claude Desktop application** installed ([Download](https://claude.ai/download)) + +## Step 1: Install HoloViz MCP + +Open your terminal and install HoloViz MCP as a uv tool: + +```bash +uv tool install holoviz-mcp[pydata] +``` + +This command installs HoloViz MCP globally, making it available for Claude Desktop to reference. + +!!! tip "What's happening?" + The uv tool manager creates an isolated environment for HoloViz MCP and installs all necessary dependencies. + + The extra `pydata` dependencies are added to install a wide range of python data related packages. We will assume these are installed throughout this guide. You can replace them with your favorite dependencies for your own work. + +## Step 2: Install Chromium + +Install [Chromium](https://playwright.dev/docs/browsers) to enable the holoviz-mcp server to take screenshots: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Step 3: Create the Documentation Index + +HoloViz MCP needs to index the HoloViz documentation to provide intelligent answers. Run: + +```bash +holoviz-mcp update index +``` + +**⏱️ This will take 5-10 minutes** as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Step 4: Configure Claude Desktop + +Now let's configure Claude Desktop to use the HoloViz MCP server: + +1. Locate your Claude Desktop configuration file: + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + - **Linux**: `~/.config/Claude/claude_desktop_config.json` + +2. Add this configuration: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp" + } + } +} +``` + +3. Save the file and restart Claude Desktop + +## Step 5: Verify Installation + +Let's verify that HoloViz MCP is working correctly! + +### Check Server Connection + +After restarting Claude Desktop, look for the MCP indicator (🔌) in the interface. It should show "holoviz" as a connected server. + +### Test with Claude + +Open a chat with Claude and try these questions: + +**Component Discovery**: + + What Panel components are available for user input? + +**Component Details**: + + What parameters does the Panel Button component accept? + +If Claude provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 + +## Step 6: Build Your First Dashboard + +Now that everything is set up, let's build a simple dashboard. + +**Ask Claude:** + + Create a Panel dashboard that displays a slider and shows the square of the slider's value. Save it to app.py + +Claude will provide code using HoloViz MCP's knowledge of Panel components! + +Save the code to `app.py` and run it: + +```bash +panel serve app.py --show +``` + +Your dashboard will open in your default web browser! + +## Step 7: Using the Display Tool + +HoloViz MCP includes a powerful display tool that can render visualizations directly. Ask Claude: + + Use the holoviz_display tool to show me a simple hvplot visualization of random data. + +Claude will use the display tool to generate and display the visualization. See the [Display System tutorial](display-system.md) for more details. + +## What's Next? + +Now that you have HoloViz MCP running with Claude Desktop, explore more: + +- **[Display System](display-system.md)**: Learn about the display server for visualizations +- **[Stock Analysis](stock-analysis-claude-code.md)**: Create a real-world stock analysis report +- **[Weather Dashboard](weather-dashboard-claude-code.md)**: Create an interactive weather visualization + +## Troubleshooting + +### Installation Issues + +**Problem**: `uv: command not found` + +**Solution**: Install uv by following the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) + +**Problem**: Installation takes too long + +**Solution**: This is normal! The first installation downloads many dependencies. Subsequent updates are much faster. + +### Configuration Issues + +**Problem**: Claude Desktop doesn't show the MCP indicator + +**Solution**: + +1. Check that the configuration file path is correct for your operating system +2. Verify the JSON syntax is correct (no trailing commas, proper quotes) +3. Restart Claude Desktop completely (quit and reopen) +4. Check that holoviz-mcp is installed: `holoviz-mcp --version` + +**Problem**: Claude doesn't recognize Panel components + +**Solution**: + +1. Check that the documentation index completed (Step 3) +2. Verify your configuration file is correct +3. Restart Claude Desktop +4. Try running the server directly in terminal: `holoviz-mcp` + +### Server Issues + +**Problem**: MCP server won't connect + +**Solution**: + +1. Verify Python 3.11+ is installed: `python --version` +2. Check uv installation: `uv --version` +3. Try running the server directly: `holoviz-mcp` +4. Check the Claude Desktop logs for errors + +For more help, see the [Troubleshooting Guide](../how-to/troubleshooting.md) or join the [HoloViz Discord](https://discord.gg/AXRHnJU6sP). + +## Summary + +In this tutorial, you: + +✅ Installed HoloViz MCP using uv +✅ Created the documentation index +✅ Installed Chromium +✅ Configured Claude Desktop +✅ Verified the installation +✅ Built your first Panel dashboard +✅ Learned about the display tool + +You're now ready to use HoloViz MCP with Claude Desktop to accelerate your Panel development! Happy coding! 🚀 diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started-copilot-vscode.md similarity index 50% rename from docs/tutorials/getting-started.md rename to docs/tutorials/getting-started-copilot-vscode.md index 62573da..522c460 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started-copilot-vscode.md @@ -1,25 +1,24 @@ -# Getting Started with HoloViz MCP +# Getting Started with HoloViz MCP for Copilot + VS Code -This tutorial will guide you through installing and using HoloViz MCP for the first time. By the end, you'll have HoloViz MCP running and be able to ask your AI assistant questions about Panel components! +This tutorial will guide you through installing and using HoloViz MCP with GitHub Copilot and VS Code. By the end, you'll have HoloViz MCP running with specialized Copilot agents and be able to build advanced Panel dashboards! !!! tip "What you'll learn" - How to install HoloViz MCP - - How to configure it with your AI assistant (VS Code, Claude Desktop, or Cursor) - - How to use it to get help building Panel applications + - How to configure it with Github Copilot and VS Code + - How to install and use HoloViz Copilot agents + - How to use HoloViz MCP resources in Copilot - How to verify everything is working correctly + - How to build your first Panel dashboard -!!! Prerequisites +!!! note "Prerequisites" Before you begin, ensure you have: - **Python 3.11 or newer** installed on your system - **[uv](https://docs.astral.sh/uv/)** package installer - - An **MCP-compatible AI assistant**: - - VS Code with GitHub Copilot extension - - Claude Desktop application - - Cursor IDE - - Or any other MCP-compatible client + - **VS Code** with GitHub Copilot extension + - **GitHub Copilot subscription** (required for agents and resources) ## Step 1: Install HoloViz MCP @@ -56,19 +55,25 @@ holoviz-mcp update index **⏱️ This will take 5-10 minutes** as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. -## Step 4: Install the agents +## Step 4: Install HoloViz Copilot Agents -If using copilot install the *agents*: +[Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents) enable you to configure the AI to adopt different personas tailored to specific development roles and tasks. Install the HoloViz MCP agents: ```bash holoviz-mcp install copilot ``` -## Step 5: Configure Your AI Assistant +You should see output confirming that agents were installed to `.github/agents/`. -Choose your AI assistant and follow the appropriate configuration: +!!! note "What's happening" + This command installs custom Copilot agents specifically designed for HoloViz development. These agents understand the `holoviz-mcp` server and can use it to understand the architecture patterns and best practices for Panel, hvPlot, and other HoloViz libraries. -### VS Code + GitHub Copilot +!!! tip + Run `holoviz-mcp install copilot --skills` to populate the `.github/skills` folder too. See [Use Agent Skills in VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills) for more info. + +## Step 5: Configure VS Code + +Now let's configure VS Code to use the HoloViz MCP server: 1. In VS Code, open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) 2. Type "MCP: Add Server..." and press Enter @@ -93,42 +98,6 @@ This will add the below configuration to your *user* `mcp.json` file. Please refer to the [VS Code | MCP Servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) guide for more details. -### Claude Desktop - -1. Locate your Claude Desktop configuration file: - - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - - **Linux**: `~/.config/Claude/claude_desktop_config.json` - -2. Add this configuration: - -```json -{ - "mcpServers": { - "holoviz": { - "command": "holoviz-mcp" - } - } -} -``` - -3. Save the file and restart Claude Desktop - -### Cursor - -1. Open Cursor Settings -2. Navigate to `Features` → `Model Context Protocol` -3. Click `Add Server` and enter: - -```json -{ - "name": "holoviz", - "command": "holoviz-mcp" -} -``` - -4. Save and restart Cursor - ## Step 6: Verify Installation Let's verify that HoloViz MCP is working correctly! @@ -140,6 +109,10 @@ Let's verify that HoloViz MCP is working correctly! 3. Choose the "holoviz" server 4. Select "Start Server" +Repeat steps 1-2 and verify that the `holoviz` MCP server is now running. + +![HoloViz MCP Running](../assets/images/holoviz-mcp-vscode-running.png) + ### Check Server Status In VS Code, you can monitor the MCP server: @@ -150,9 +123,9 @@ In VS Code, you can monitor the MCP server: 4. Select "Show Output" 5. You should see log messages indicating the server is running -### Test with Your AI Assistant +### Test with Copilot -Open a chat with your AI assistant and try these questions: +Open Copilot Chat and try these questions: **Component Discovery**: @@ -166,30 +139,84 @@ Open a chat with your AI assistant and try these questions: What parameters does the Panel Button component accept? -If your AI assistant provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 +If Copilot provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 ## Step 7: Build Your First Dashboard Now that everything is set up, let's build a simple dashboard. -**Ask your AI "Agent":** +**Ask Copilot:** - Create a Panel dashboard in the file app.py that displays a slider and shows the square of the slider's value. Use panel skills. + Create a Panel dashboard in the file app.py that displays a slider and shows the square of the slider's value. Use panel skills. -Your AI "Agent" will provide code using HoloViz MCP's knowledge of Panel components! +Copilot will provide code using HoloViz MCP's knowledge of Panel components! ![Copilot Chat](../assets/images/getting-started-build-dashboard-copilot-chat.png) ![Dashboard](../assets/images/getting-started-build-dashboard.png) +## Step 8: Using HoloViz Resources + +MCP resources contain curated knowledge that enhances Copilot's understanding of specific frameworks. Let's load the hvPlot best practice skills and use them to create a basic data visualization. + +1. In the Copilot Chat Interface, click "Add Context" (`CTRL + '`) +2. Select "MCP Resources" +3. You'll see a list of available resources. Select **`holoviz_hvplot`** + +![HoloViz MCP Resources](../assets/images/holoviz-mcp-resources.png) + +Notice in the chat interface that the resource is now added to the context. + +![HvPlot Resource Added](../assets/images/holoviz-mcp-vscode-resource-added.png) + +Ask Copilot: + + Please create a basic hvplot visualization in a script.py file. + +![HvPlot Plot](../assets/images/holoviz-mcp-vscode-resource-plot.png) + +!!! tip + You can add multiple resources to the context. Try browsing and adding `holoviz_panel` as well to get Panel-specific guidance. + +## Step 9: Using HoloViz Agents + +### Creating a Plan with the HoloViz App Planner Agent + +Instead of diving straight into code, let's use the specialized agent to plan an application architecture. + +1. In the Copilot Chat interface, click the **Set Agent** dropdown +2. Select **`HoloViz App Planner`** from the list + +![HoloViz App Planner](../assets/images/copilot-holoviz-app-planner.png) + +Type the following prompt: + + Create a plan for a stock dashboard that displays historical prices and trading volume + +Press Enter and wait for the agent to respond. + +![Copilot Dashboard Plan](../assets/images/copilot-dashboard-plan.png) + +!!! note "What's happening" + The HoloViz App Planner agent analyzes your requirements and creates an architecture plan following HoloViz best practices. This ensures your application is well-structured before you write any code. + +### Implementing the Dashboard + +Now that you have a plan, let's ask Copilot to help implement it. + +In the Copilot Chat, respond to the plan with: + + Implement the plan outlined above. + +Copilot will generate the code for your dashboard and test it. + ## What's Next? -Now that you have HoloViz MCP running, explore more: +Now that you have HoloViz MCP running with Copilot + VS Code, explore more: -- **[IDE Configuration Guide](../how-to/ide-configuration.md)**: Advanced IDE setup options -- **[Configuration Guide](../how-to/configuration.md)**: Customize HoloViz MCP behavior -- **[Available Tools](../explanation/tools.md)**: Learn about all the tools HoloViz MCP provides -- **[Docker Setup](../how-to/docker.md)**: Run HoloViz MCP in a container +- **[Display System](display-system.md)**: Learn about the display server for visualizations +- **[Stock Analysis](stock-analysis-copilot-vscode.md)**: Create a real-world stock analysis report +- **[Weather Dashboard](weather-dashboard-copilot-vscode.md)**: Create an interactive weather visualization ## Troubleshooting @@ -205,14 +232,15 @@ Now that you have HoloViz MCP running, explore more: ### Configuration Issues -**Problem**: AI assistant doesn't recognize Panel components +**Problem**: Copilot doesn't recognize Panel components **Solution**: -1. Check that the documentation index completed (Step 2) +1. Check that the documentation index completed (Step 3) 2. Verify your configuration file is correct -3. Restart your IDE +3. Restart VS Code 4. Check the MCP server logs for errors +5. Include `#holoviz` in your prompt to explicitly use HoloViz MCP ### Server Issues @@ -234,8 +262,11 @@ In this tutorial, you: ✅ Installed HoloViz MCP using uv ✅ Created the documentation index ✅ Installed Chromium -✅ Configured your AI assistant +✅ Installed HoloViz Copilot agents +✅ Configured Github Copilot and VS Code ✅ Verified the installation ✅ Built your first Panel dashboard +✅ Used HoloViz MCP resources +✅ Used specialized HoloViz agents -You're now ready to use HoloViz MCP to accelerate your Panel development! Happy coding! 🚀 +You're now ready to use HoloViz MCP with Copilot + VS Code to accelerate your Panel development! Happy coding! 🚀 diff --git a/docs/tutorials/getting-started-cursor.md b/docs/tutorials/getting-started-cursor.md new file mode 100644 index 0000000..475a081 --- /dev/null +++ b/docs/tutorials/getting-started-cursor.md @@ -0,0 +1,199 @@ +# Getting Started with HoloViz MCP for Cursor + +This tutorial will guide you through installing and using HoloViz MCP with Cursor. By the end, you'll have HoloViz MCP running and be able to ask Cursor's AI questions about Panel components! + +!!! tip "What you'll learn" + - How to install HoloViz MCP + - How to configure it with Cursor + - How to use it to get help building Panel applications + - How to verify everything is working correctly + - How to build your first Panel dashboard + +!!! note "Prerequisites" + Before you begin, ensure you have: + + - **Python 3.11 or newer** installed on your system + - **[uv](https://docs.astral.sh/uv/)** package installer + - **Cursor IDE** installed ([Download](https://cursor.sh/)) + +## Step 1: Install HoloViz MCP + +Open your terminal and install HoloViz MCP as a uv tool: + +```bash +uv tool install holoviz-mcp[pydata] +``` + +This command installs HoloViz MCP globally, making it available for Cursor to reference. + +!!! tip "What's happening?" + The uv tool manager creates an isolated environment for HoloViz MCP and installs all necessary dependencies. + + The extra `pydata` dependencies are added to install a wide range of python data related packages. We will assume these are installed throughout this guide. You can replace them with your favorite dependencies for your own work. + +## Step 2: Install Chromium + +Install [Chromium](https://playwright.dev/docs/browsers) to enable the holoviz-mcp server to take screenshots: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Step 3: Create the Documentation Index + +HoloViz MCP needs to index the HoloViz documentation to provide intelligent answers. Run: + +```bash +holoviz-mcp update index +``` + +**⏱️ This will take 5-10 minutes** as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Step 4: Configure Cursor + +Now let's configure Cursor to use the HoloViz MCP server: + +### Quick Install + +Click the button below to open Cursor's MCP settings: + +[![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square)](cursor://settings/mcp) + +### Manual Configuration + +1. Open Cursor Settings +2. Navigate to `Features` → `Model Context Protocol` +3. Click `Add Server` +4. Enter the configuration: + +```json +{ + "name": "holoviz", + "command": "holoviz-mcp" +} +``` + +5. Save and restart Cursor + +## Step 5: Verify Installation + +Let's verify that HoloViz MCP is working correctly! + +### Test with Cursor AI + +Open Cursor's AI chat and try these questions: + +**Component Discovery**: + + What Panel components are available for user input? + +**Component Details**: + + What parameters does the Panel Button component accept? + +If Cursor's AI provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 + +## Step 6: Build Your First Dashboard + +Now that everything is set up, let's build a simple dashboard. + +**Ask Cursor:** + + Create a Panel dashboard that displays a slider and shows the square of the slider's value. Save it to app.py + +Cursor will provide code using HoloViz MCP's knowledge of Panel components! + +Save the code to `app.py` and run it: + +```bash +panel serve app.py --show +``` + +Your dashboard will open in your default web browser! + +## Step 7: Using the Display Tool + +HoloViz MCP includes a powerful display tool that can render visualizations directly. Ask Cursor: + + Use the holoviz_display tool to show me a simple hvplot visualization of random data. + +Cursor will use the display tool to generate and display the visualization. See the [Display System tutorial](display-system.md) for more details. + +## Working with Cursor + +Cursor is designed for AI-first development. Here are some tips: + +- **Cmd/Ctrl + K**: Open inline AI editor to modify code +- **Cmd/Ctrl + L**: Open AI chat panel +- **@-mentions**: Reference files and code in your prompts +- **Tab to accept**: AI suggestions appear inline as you type + +Ask Cursor to help you with Panel-specific tasks, and it will use HoloViz MCP to provide accurate, up-to-date information! + +## What's Next? + +Now that you have HoloViz MCP running with Cursor, explore more: + +- **[Display System](display-system.md)**: Learn about displaying visualizations + +## Troubleshooting + +### Installation Issues + +**Problem**: `uv: command not found` + +**Solution**: Install uv by following the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) + +**Problem**: Installation takes too long + +**Solution**: This is normal! The first installation downloads many dependencies. Subsequent updates are much faster. + +### Configuration Issues + +**Problem**: Cursor doesn't recognize Panel components + +**Solution**: + +1. Check that the documentation index completed (Step 3) +2. Verify your MCP configuration is correct in Cursor Settings +3. Restart Cursor completely +4. Try running the server directly: `holoviz-mcp` +5. Check that holoviz-mcp is installed: `holoviz-mcp --version` + +**Problem**: MCP server not showing in Cursor + +**Solution**: + +1. Verify the JSON configuration is correct (no trailing commas) +2. Restart Cursor after adding the configuration +3. Check Cursor's MCP settings to ensure the server is listed + +### Server Issues + +**Problem**: MCP server won't connect + +**Solution**: + +1. Verify Python 3.11+ is installed: `python --version` +2. Check uv installation: `uv --version` +3. Try running the server directly: `holoviz-mcp` +4. Check Cursor's output/console for error messages + +For more help, see the [Troubleshooting Guide](../how-to/troubleshooting.md) or join the [HoloViz Discord](https://discord.gg/AXRHnJU6sP). + +## Summary + +In this tutorial, you: + +✅ Installed HoloViz MCP using uv +✅ Created the documentation index +✅ Installed Chromium +✅ Configured Cursor +✅ Verified the installation +✅ Built your first Panel dashboard +✅ Learned about the display tool +✅ Learned Cursor-specific tips + +You're now ready to use HoloViz MCP with Cursor to accelerate your Panel development! Happy coding! 🚀 diff --git a/docs/tutorials/getting-started-windsurf.md b/docs/tutorials/getting-started-windsurf.md new file mode 100644 index 0000000..ecba89b --- /dev/null +++ b/docs/tutorials/getting-started-windsurf.md @@ -0,0 +1,191 @@ +# Getting Started with HoloViz MCP for Windsurf + +This tutorial will guide you through installing and using HoloViz MCP with Windsurf. By the end, you'll have HoloViz MCP running and be able to ask Windsurf's AI questions about Panel components! + +!!! tip "What you'll learn" + - How to install HoloViz MCP + - How to configure it with Windsurf + - How to use it to get help building Panel applications + - How to verify everything is working correctly + - How to build your first Panel dashboard + +!!! note "Prerequisites" + Before you begin, ensure you have: + + - **Python 3.11 or newer** installed on your system + - **[uv](https://docs.astral.sh/uv/)** package installer + - **Windsurf IDE** installed ([Download](https://windsurf.ai/)) + +## Step 1: Install HoloViz MCP + +Open your terminal and install HoloViz MCP as a uv tool: + +```bash +uv tool install holoviz-mcp[pydata] +``` + +This command installs HoloViz MCP globally, making it available for Windsurf to reference. + +!!! tip "What's happening?" + The uv tool manager creates an isolated environment for HoloViz MCP and installs all necessary dependencies. + + The extra `pydata` dependencies are added to install a wide range of python data related packages. We will assume these are installed throughout this guide. You can replace them with your favorite dependencies for your own work. + +## Step 2: Install Chromium + +Install [Chromium](https://playwright.dev/docs/browsers) to enable the holoviz-mcp server to take screenshots: + +```bash +holoviz-mcp install chromium +``` + +**📦 This downloads 300MB** as it downloads the Chromium and FFMPEG engines. + +## Step 3: Create the Documentation Index + +HoloViz MCP needs to index the HoloViz documentation to provide intelligent answers. Run: + +```bash +holoviz-mcp update index +``` + +**⏱️ This will take 5-10 minutes** as it downloads and indexes documentation from Panel, hvPlot, and other HoloViz libraries. + +## Step 4: Configure Windsurf + +Now let's configure Windsurf to use the HoloViz MCP server: + +1. Locate your Windsurf MCP configuration file +2. Add the following configuration: + +```json +{ + "mcpServers": { + "holoviz": { + "command": "holoviz-mcp" + } + } +} +``` + +3. Save the file and restart Windsurf + +## Step 5: Verify Installation + +Let's verify that HoloViz MCP is working correctly! + +### Test with Windsurf AI + +Open Windsurf's AI assistant and try these questions: + +**Component Discovery**: + + What Panel components are available for user input? + +**Component Details**: + + What parameters does the Panel Button component accept? + +If Windsurf's AI provides detailed, accurate answers with specific Panel component information, congratulations! HoloViz MCP is working correctly! 🎉 + +## Step 6: Build Your First Dashboard + +Now that everything is set up, let's build a simple dashboard. + +**Ask Windsurf:** + + Create a Panel dashboard that displays a slider and shows the square of the slider's value. Save it to app.py + +Windsurf will provide code using HoloViz MCP's knowledge of Panel components! + +Save the code to `app.py` and run it: + +```bash +panel serve app.py --show +``` + +Your dashboard will open in your default web browser! + +## Step 7: Using the Display Tool + +HoloViz MCP includes a powerful display tool that can render visualizations directly. Ask Windsurf: + + Use the holoviz_display tool to show me a simple hvplot visualization of random data. + +Windsurf will use the display tool to generate and display the visualization. See the [Display System tutorial](display-system.md) for more details. + +## Working with Windsurf + +Windsurf provides an AI-enhanced development experience. Here are some tips for working with HoloViz MCP: + +- Ask specific questions about Panel components and parameters +- Request code examples for building dashboards +- Get help with hvPlot visualizations and customization +- Use the display tool to see visualizations without leaving your IDE + +The AI will leverage HoloViz MCP to provide accurate, contextual assistance! + +## What's Next? + +Now that you have HoloViz MCP running with Windsurf, explore more: + +- **[Display System](display-system.md)**: Learn about displaying visualizations + +## Troubleshooting + +### Installation Issues + +**Problem**: `uv: command not found` + +**Solution**: Install uv by following the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) + +**Problem**: Installation takes too long + +**Solution**: This is normal! The first installation downloads many dependencies. Subsequent updates are much faster. + +### Configuration Issues + +**Problem**: Windsurf doesn't recognize Panel components + +**Solution**: + +1. Check that the documentation index completed (Step 3) +2. Verify your MCP configuration file is correct +3. Restart Windsurf completely +4. Try running the server directly: `holoviz-mcp` +5. Check that holoviz-mcp is installed: `holoviz-mcp --version` + +**Problem**: MCP server not connecting + +**Solution**: + +1. Verify the JSON configuration is correct (no trailing commas, proper quotes) +2. Restart Windsurf after adding the configuration +3. Check the configuration file path is correct for your system + +### Server Issues + +**Problem**: MCP server won't start + +**Solution**: + +1. Verify Python 3.11+ is installed: `python --version` +2. Check uv installation: `uv --version` +3. Try running the server directly: `holoviz-mcp` +4. Check Windsurf's logs for error messages + +For more help, see the [Troubleshooting Guide](../how-to/troubleshooting.md) or join the [HoloViz Discord](https://discord.gg/AXRHnJU6sP). + +## Summary + +In this tutorial, you: + +✅ Installed HoloViz MCP using uv +✅ Created the documentation index +✅ Installed Chromium +✅ Configured Windsurf +✅ Verified the installation +✅ Built your first Panel dashboard +✅ Learned about the display tool + +You're now ready to use HoloViz MCP with Windsurf to accelerate your Panel development! Happy coding! 🚀 diff --git a/docs/tutorials/stock-analysis-claude-code.md b/docs/tutorials/stock-analysis-claude-code.md new file mode 100644 index 0000000..14b5630 --- /dev/null +++ b/docs/tutorials/stock-analysis-claude-code.md @@ -0,0 +1,210 @@ +# Tutorial: Building an Interactive Stock Analysis Report with Claude Code + +In this tutorial, you will create a complete stock analysis report that visualizes price movements and trading patterns for multiple stocks using Claude Code from the command line. + +By the end, you'll have built an interactive report that displays financial data with professional charts and statistics. + +!!! tip "What you'll learn" + - How to use Claude Code to plan and build data applications + - How to use the `holoviz_display` tool to quickly visualize and persist your work + - How to work with stock data using yfinance + - How to iterate on visualizations using natural language + +!!! note "Prerequisites" + Before starting, ensure you have: + + - Claude Code CLI installed and configured ([Getting Started Guide](getting-started-claude-code.md)) + - HoloViz MCP server configured with Claude Code + - `yfinance` installed: `pip install yfinance` + +## Step 1: Plan Your Report + +First, let's ask Claude to help us plan our stock analysis report. Open your terminal and run: + +```bash +claude "I want to create a stock analysis report showing AAPL and META's hourly data for the last 5 days. The report should include: + +- Individual price charts for each stock +- Summary statistics table +- Normalized comparison overlay +- Trading volume visualization +- Professional styling + +Please plan the architecture for this report. What components should I use from Panel and hvPlot?" +``` + +Claude will provide a detailed architecture plan including: + +- Data sources and how to fetch stock data with yfinance +- Chart types to use for price and volume visualization +- Panel components for layout and statistics +- Best practices for organizing the report + +!!! success "What you'll see" + Claude will outline a clear plan for building your report, including the key libraries and components needed. + +## Step 2: Implement the Report + +Now let's ask Claude to implement the report and use the display tool to show it: + +```bash +claude "Based on the plan above, please implement the stock analysis report for AAPL and META. Use the holoviz_display tool to create and show the report. Keep it clean and simple." +``` + +Claude will: + +1. Generate the complete Python code +2. Use the `holoviz_display` tool to execute it +3. Provide a URL where you can view the results + +You should see output like: + +``` +✓ Visualization created successfully! +View at: http://localhost:5005/view?id={snippet_id} +``` + +## Step 3: View Your Report + +Open the URL in your browser. You should see your stock analysis report with: + +- **Individual price charts** showing AAPL and META stock movements +- **Summary statistics table** with key metrics (open, high, low, close, volume) +- **Normalized comparison** overlaying both stocks to compare relative performance +- **Volume visualization** showing trading activity + +![Stock Analysis Report](../assets/images/stock-analysis-report.png) + +!!! success "Checkpoint" + If you see interactive charts like the above, congratulations! You've successfully created a stock analysis report. Try hovering over the charts - they're interactive! + +## Step 4: Experiment with Different Stocks + +Now that you understand how the report works, let's modify it to analyze different stocks: + +```bash +claude "Modify the report to show GOOGL and MSFT instead of AAPL and META" +``` + +Claude will generate updated code with the new stocks and provide a new URL to view the modified report. + +![Google and Microsoft](../assets/images/stock-analysis-googl-msft.png) + +## Step 5: Add More Features + +Let's enhance the report by adding a moving average to the price charts: + +```bash +claude "Add a 20-period moving average line to each stock's price chart" +``` + +Claude will update the code to include moving average trend lines and provide a new URL to view the enhanced report. + +![Moving Average](../assets/images/stock-analysis-moving-average.png) + +!!! success "What you've learned" + You can iterate on your report by asking for modifications in natural language. Claude understands the existing code structure and makes appropriate changes. + +## Step 6: Save Your Work + +The reports you created are stored by the Display Server. To save one as a permanent file: + +1. Navigate to the Display Server feed at `http://localhost:5005/feed` +2. Find your stock analysis report +3. Click the **Copy Code** button + +![Copy Code Button](../assets/images/stock-analysis-copy-code.png) + +4. Create a new file called `stock_report.py` in your project +5. Paste the code and save + +Now you have a standalone Python file! You can run it anytime: + +```bash +panel serve stock_report.py --show +``` + +## Step 7: Create a Project-Based Report + +For a more structured workflow, you can create the report as a project file: + +```bash +# Navigate to your project directory +cd my-stock-project + +# Ask Claude to create the report file +claude "Create a stock_analysis.py file that analyzes AAPL and META with the visualizations we discussed. Include proper imports, error handling, and documentation." +``` + +Claude will create the file in your project. You can then review it: + +```bash +cat stock_analysis.py +``` + +And run it: + +```bash +panel serve stock_analysis.py --show +``` + +## Common Issues and Solutions + +### Module Not Found Error + +**What you see**: `ModuleNotFoundError: No module named 'yfinance'` + +**Why it happens**: The required package isn't installed in your Python environment + +**Solution**: Install the missing package: +```bash +pip install yfinance +``` + +### Charts Not Displaying + +**What you see**: Empty page or error when clicking the view URL + +**Why it happens**: The Display Server might not be running or there's a code error + +**Solution**: + +1. Check that Claude Code MCP server is configured: `claude mcp list` +2. Look at the error message in the report for specific issues +3. Ask Claude to fix any code errors: + ```bash + claude "The report shows an error: [paste error]. Please fix this." + ``` + +### Connection Refused Error + +**What you see**: `Connection refused` when accessing the display URL + +**Why it happens**: The Display Server isn't running + +**Solution**: The Display Server should start automatically with the MCP server. Check Claude Code's output for startup messages. + +## What You've Accomplished + +Congratulations! In this tutorial, you have: + +- ✅ Planned and built a data analysis application with Claude Code +- ✅ Implemented a complete stock analysis report +- ✅ Created interactive charts with hvPlot +- ✅ Built a multi-component report with Panel +- ✅ Explored interactive visualization features +- ✅ Modified the report to analyze different stocks +- ✅ Added new features through natural language requests +- ✅ Saved your work as a standalone Python application + +## Next Steps + +Now that you've mastered stock analysis with Claude Code, try: + +- **[Weather Dashboard Tutorial](weather-dashboard-claude-code.md)**: Build another interactive dashboard +- **[Display System Guide](display-system.md)**: Learn more about the display capabilities +- **Expand your report**: Add technical indicators (RSI, MACD, Bollinger Bands) +- **Real-time updates**: Make the report refresh with live data +- **Portfolio analysis**: Compare multiple stocks with portfolio weights + +Happy analyzing! 📈 diff --git a/docs/tutorials/stock-analysis.md b/docs/tutorials/stock-analysis-copilot-vscode.md similarity index 97% rename from docs/tutorials/stock-analysis.md rename to docs/tutorials/stock-analysis-copilot-vscode.md index 4cf6963..5eeb6eb 100644 --- a/docs/tutorials/stock-analysis.md +++ b/docs/tutorials/stock-analysis-copilot-vscode.md @@ -14,9 +14,9 @@ By the end, you'll have built an interactive report that displays financial data Before starting, ensure you have: - VS Code with GitHub Copilot or another MCP-compatible AI assistant - - HoloViz MCP installed and configured ([Getting Started Guide](getting-started.md)) - - Configured the `HoloViz Analysis Planner` agent. ([HoloViz Agents](copilot.md/#using-holoviz-agents)) - - The HoloViz MCP server running ([How to start the server](getting-started.md/#start-the-server)) + - HoloViz MCP installed and configured ([Getting Started Guide](getting-started-copilot-vscode.md)) + - Configured the `HoloViz Analysis Planner` agent. ([HoloViz Agents](getting-started-copilot-vscode.md#step-9-using-holoviz-agents)) + - The HoloViz MCP server running ([How to start the server](getting-started-copilot-vscode.md#start-the-server)) - `yfinance` installed in the virtual environment where you run `holoviz-mcp`: `pip install yfinance` ## Step 1: Plan Your Report with the HoloViz Analysis Planner diff --git a/docs/tutorials/weather-dashboard-claude-code.md b/docs/tutorials/weather-dashboard-claude-code.md new file mode 100644 index 0000000..278ca86 --- /dev/null +++ b/docs/tutorials/weather-dashboard-claude-code.md @@ -0,0 +1,235 @@ +# Tutorial: Building an Interactive Weather Dashboard with Claude Code + +In this tutorial, you will create a professional weather analysis dashboard that explores Seattle weather patterns from 2012-2015 using Claude Code from the command line. + +By the end, you'll have built a complete interactive application with multi-year filtering, animated charts, and modern styling that works beautifully in both light and dark modes. + + + +!!! note "Prerequisites" + Before starting, ensure you have: + + - An understanding of Python, [Panel](https://panel.holoviz.org/index.html), and data visualization concepts + - HoloViz MCP installed and configured ([Getting Started Guide](getting-started-claude-code.md)) + - Claude Code CLI configured with HoloViz MCP server + +## Step 1: Gather Context + +Before we start building, let's examine an existing project to understand the key elements of an effective weather visualization: + +```text +For context, please analyze the weather visualization at https://altair-viz.github.io/case_studies/exploring-weather.html. Summarize the key features and visualization techniques used. +``` + +Take a moment to review Claude's summary. This will guide our dashboard design! + +## Step 2: Plan Your Dashboard + +Now let's ask Claude to help us plan the dashboard architecture: + +```text +I want to create an awesome dashboard for exploring the Seattle Weather dataset. The dashboard should: + +- Enable filtering by multiple years (default: 2015) +- Include plots for temperature and wind grouped by year +- Include a plot by weather type +- Include a table with the raw data +- Use ECharts with smooth transitions +- Use consistent and modern styling + +Please plan the architecture for this dashboard. What components should I use from Panel? How should the code be organized? +``` + +Claude will provide a detailed architecture including: + +- Data layer with caching and filtering functions +- Chart creation functions using ECharts +- Dashboard class with reactive parameters +- Recommendations for file organization +- Color palette suggestions + +!!! success "What you'll see" + Take time to read through Claude's plan - it's the blueprint for your application! + +## Step 3: Implement the Dashboard + +With a solid plan, let's create the dashboard. We'll create it as a project file: + +```text +Based on the plan above, create a weather_dashboard.py file that implements the Seattle Weather dashboard. Include: + +- Data loading and filtering +- ECharts visualizations for temperature, wind, and weather types +- Panel components for interactivity +- Clean, well-organized code with docstrings +- The vega_datasets package provides the Seattle weather data + +Keep it as a single file for simplicity. +``` + +Claude will create the `weather_dashboard.py` file in your current directory. + +## Step 4: Run Your Dashboard + +Now let's run the dashboard: + +```bash +panel serve weather_dashboard.py --dev --show +``` + +Your browser will open and display your weather dashboard! + +![Dashboard Served](../assets/images/weather-dashboard-served.gif) + +!!! success "Checkpoint" + If you see an interactive dashboard with charts, filters, and a data table - congratulations! Try: + + - Selecting different years in the filter + - Hovering over the charts to see interactive tooltips + - Exploring the animated transitions when filters change + +## Step 5: Review and Understand the Code + +Let's take a look at what was created: + +```bash +cat weather_dashboard.py +``` + +You'll see: + +- **Data functions**: Loading and filtering the Seattle weather dataset +- **Chart functions**: Creating ECharts visualizations +- **Dashboard class**: Reactive Panel application with parameters +- **Main block**: Serving the dashboard + +## Step 6: Add More Features + +Let's enhance the dashboard. Ask Claude: + +```text +Add a precipitation plot to the weather dashboard that shows rainfall patterns by month. Include it in the layout. +``` + +Claude will update the file. The panel server will autoreload the dashboard. + +## Step 7: Improve Styling + +Let's make the dashboard even more visually appealing: + +```text +Improve the dashboard styling: +- Add a descriptive header with title and description +- Use a card layout for the plots +- Add subtle shadows and spacing +- Make it responsive for different screen sizes +``` + +Again, restart the server to see the improvements. + +## Step 8: Use the Display Tool + +For quick iterations, you can also use the `holoviz_display` tool: + +```text +Create a simplified version of the weather dashboard and display it using the holoviz_display tool. Focus on just the temperature plot and year filter. +``` + +Claude will use the display tool and provide a URL. This is faster for prototyping! + +## Common Issues and Solutions + +### Dataset Not Loading + +**What you see**: Error about missing dataset + +**Solution**: Install vega_datasets: + +```bash +pip install vega_datasets +``` + +### Charts Not Rendering + +**What you see**: Empty plots or errors + +**Solution**: + +1. Check that Panel and hvPlot are installed: `pip install panel hvplot` +2. Verify the data is loading correctly +3. Ask Claude to debug: + ```bash + claude "The charts aren't rendering. Here's the error: [paste error]. Please fix this." + ``` + +### Server Won't Start + +**What you see**: Port already in use + +**Solution**: Use a different port: + +```bash +panel serve weather_dashboard.py --dev --show --port 5007 +``` + +## Step 9: Create Tests + +Let's add some tests to ensure our dashboard works correctly: + +```text +Create a test_weather_dashboard.py file that tests: +- Data loading functions +- Data filtering by year +- Chart creation functions +Include pytest fixtures and assertions." +``` + +Run the tests: + +```bash +pytest test_weather_dashboard.py -v +``` + +## Step 10: Package for Sharing + +Create a requirements file and README: + +```text +Create a requirements.txt file with all dependencies needed to run the weather dashboard, and a README.md with setup instructions. +``` + +Now you can share your project with others! + +## What You've Accomplished + +Congratulations! In this tutorial, you have: + +- ✅ Planned and built a complex dashboard with Claude Code +- ✅ Created animated, interactive charts with ECharts +- ✅ Built a Panel dashboard with professional styling +- ✅ Implemented reactive programming with Panel parameters +- ✅ Added features through iterative development +- ✅ Used the display tool for rapid prototyping +- ✅ Created tests for your application +- ✅ Packaged a shareable project + +You now have a production-ready weather dashboard and the skills to build your own data applications from the command line! + +## Next Steps + +Now that you've mastered weather dashboards with Claude Code, try: + +- **Add more metrics**: Include humidity, pressure, or UV index +- **Compare cities**: Extend to analyze weather in multiple locations +- **Time series forecasting**: Add predictions using statsmodels or prophet +- **Real-time data**: Connect to a weather API for live updates +- **Export functionality**: Add buttons to download data or charts + +## Additional Resources + +- [Panel Documentation](https://panel.holoviz.org) +- [ECharts Documentation](https://echarts.apache.org/en/index.html) +- [Vega Datasets](https://github.com/vega/vega-datasets) +- [HoloViz Discourse](https://discourse.holoviz.org) - Share your creation! + +Happy building! 🌤️ diff --git a/docs/tutorials/weather-dashboard.md b/docs/tutorials/weather-dashboard-copilot-vscode.md similarity index 97% rename from docs/tutorials/weather-dashboard.md rename to docs/tutorials/weather-dashboard-copilot-vscode.md index 356b24e..6c040a0 100644 --- a/docs/tutorials/weather-dashboard.md +++ b/docs/tutorials/weather-dashboard-copilot-vscode.md @@ -10,10 +10,10 @@ By the end, you'll have built a complete interactive application with multi-year Before starting, ensure you have: - An understanding of Python, [Panel](https://panel.holoviz.org/index.html), and data visualization concepts - - HoloViz MCP installed and configured ([Getting Started Guide](getting-started.md)) + - HoloViz MCP installed and configured ([Getting Started Guide](getting-started-copilot-vscode.md)) - VS Code with GitHub Copilot or another MCP-compatible AI assistant - - Configured the `HoloViz App Planner` agent ([HoloViz Agents](copilot.md/#using-holoviz-agents)) - - The HoloViz MCP server running ([How to start the server](getting-started.md/#start-the-server)) + - Configured the `HoloViz App Planner` agent ([HoloViz Agents](getting-started-copilot-vscode.md#step-9-using-holoviz-agents)) + - The HoloViz MCP server running ([How to start the server](getting-started-copilot-vscode.md#start-the-server)) ## Step 1: Provide Context diff --git a/mkdocs.yml b/mkdocs.yml index af07ee9..9f4ef6c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ docs_dir: docs theme: name: material - logo: 'assets/logo.svg' + logo: 'assets/logo.png' features: - announce.dismiss - content.action.edit @@ -92,28 +92,47 @@ watch: nav: - Home: index.md - Tutorials: - - Getting Started: tutorials/getting-started.md - - Use with Copilot: tutorials/copilot.md - - Use the Display Server: tutorials/display-server.md - - Use the Display Tool: tutorials/display-tool.md - - Stock Analysis: tutorials/stock-analysis.md - - Weather Dashboard: tutorials/weather-dashboard.md + - Getting Started: + - Claude Code: tutorials/getting-started-claude-code.md + - Claude Desktop: tutorials/getting-started-claude-desktop.md + - Copilot + VS Code: tutorials/getting-started-copilot-vscode.md + - Cursor: tutorials/getting-started-cursor.md + - Windsurf: tutorials/getting-started-windsurf.md + - Display System: tutorials/display-system.md + - Projects: + - Stock Analysis (VS Code): tutorials/stock-analysis-copilot-vscode.md + - Stock Analysis (Claude Code): tutorials/stock-analysis-claude-code.md + - Weather Dashboard (VS Code): tutorials/weather-dashboard-copilot-vscode.md + - Weather Dashboard (Claude Code): tutorials/weather-dashboard-claude-code.md - How-To Guides: - - Install: how-to/installation.md - - Configure your IDE: how-to/ide-configuration.md - - Setup Docker: how-to/docker.md - - Configure holoviz-mcp: how-to/configuration.md + - Installation: + - uv (recommended): how-to/install-uv.md + - pip: how-to/install-pip.md + - conda: how-to/install-conda.md + - Docker: how-to/install-docker.md + - IDE Setup: + - Claude Code: how-to/configure-claude-code.md + - Claude Desktop: how-to/configure-claude-desktop.md + - Copilot + VS Code: how-to/configure-vscode.md + - Cursor: how-to/configure-cursor.md + - Windsurf: how-to/configure-windsurf.md + - Configuration: + - Settings: how-to/configure-settings.md + - Display Server: how-to/configure-display-server.md + - Custom Docs: how-to/add-custom-docs.md + - Docker: + - Development: how-to/docker-development.md + - Production: how-to/docker-production.md - Serve Apps: how-to/serve-apps.md - - Maintain: how-to/updates.md - - Troubleshoot: how-to/troubleshooting.md + - Update: how-to/update-holoviz-mcp.md + - Troubleshooting: how-to/troubleshooting.md - Explanation: - Architecture: explanation/architecture.md - Available Tools: explanation/tools.md - Security Considerations: explanation/security.md - - Display Server: explanation/display-server.md + - Display System: explanation/display-system.md - Reference: - API Documentation: reference/holoviz_mcp.md - - Examples: examples.md - Contributing: contributing.md - Code of Conduct: code-of-conduct.md