MCP Server for Splunk

# Prerequisites Guide - MCP Server for Splunk This guide provides comprehensive installation instructions for all prerequisites needed to run the MCP Server for Splunk on Windows, macOS, and Linux systems. ## 📋 Overview Before running the MCP Server for Splunk, ensure you have the following prerequisites installed on your system: > 🪟 Windows users: For a streamlined, Windows-specific setup (PowerShell scripts, troubleshooting, Docker tips), see the dedicated Windows guide: [Windows Setup Guide](../WINDOWS_GUIDE.md). ## 🖥️ **System Requirements** | Requirement | Minimum Version | Recommended | Platform Support | |-------------|-----------------|-------------|------------------| | **Python** | 3.10+ | 3.11+ | Windows, macOS, Linux | | **UV Package Manager** | Latest | Latest | Windows, macOS, Linux | | **Node.js** (Optional) | 18+ | 20+ LTS | For MCP Inspector testing | | **Docker** (Optional) | 20+ | Latest | For full containerized stack | | **Git** | 2.0+ | Latest | For cloning repository | ## 🐍 **Python Installation** ### **Windows:** ```powershell # Option 1: Microsoft Store (Recommended) # Search "Python" in Microsoft Store and install Python 3.11+ # Option 2: Official installer # Download from https://python.org/downloads/ # ✅ Check "Add Python to PATH" during installation # Option 3: Winget winget install Python.Python.3.12 # Option 4: Chocolatey choco install python # Verify installation python --version pip --version ``` ### **macOS:** ```bash # Option 1: Homebrew (Recommended) brew install python@3.11 # Option 2: Official installer # Download from https://python.org/downloads/ # Option 3: pyenv brew install pyenv pyenv install 3.11.0 pyenv global 3.11.0 # Verify installation python3 --version pip3 --version ``` ### **Linux (Ubuntu/Debian):** ```bash # Update package list sudo apt update # Install Python 3.11+ sudo apt install python3.11 python3.11-pip python3.11-venv # Alternative: deadsnakes PPA for latest versions sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.11 python3.11-pip python3.11-venv # Verify installation python3 --version pip3 --version ``` ### **Linux (RHEL/CentOS/Fedora):** ```bash # Fedora sudo dnf install python3.11 python3.11-pip # RHEL/CentOS with EPEL sudo yum install epel-release sudo yum install python3.11 python3.11-pip # Verify installation python3 --version pip3 --version ``` ## ⚡ **UV Package Manager Installation** UV is a fast Python package installer and dependency resolver, required for this project. ### **Windows:** ```powershell # Option 1: Official installer (Recommended) irm https://astral.sh/uv/install.ps1 | iex # Option 2: Winget winget install astral-sh.uv # Option 3: Pip fallback pip install uv # Verify installation uv --version ``` ### **macOS/Linux:** ```bash # Official installer (Recommended) curl -LsSf https://astral.sh/uv/install.sh | sh # Add to PATH (add to your shell profile) export PATH="$HOME/.cargo/bin:$PATH" # Alternative: Homebrew (macOS) brew install uv # Alternative: Pip fallback pip install uv # Verify installation uv --version ``` ## 🌐 **Node.js Installation (Optional - for MCP Inspector)** Node.js enables the interactive MCP Inspector for testing tools and resources. ### **Windows:** ```powershell # Option 1: Official installer (Recommended) # Download from https://nodejs.org/ # Option 2: Winget winget install OpenJS.NodeJS # Option 3: Chocolatey choco install nodejs # Verify installation node --version npm --version ``` ### **macOS:** ```bash # Option 1: Homebrew (Recommended) brew install node # Option 2: Official installer # Download from https://nodejs.org/ # Option 3: Node Version Manager (nvm) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install --lts nvm use --lts # Verify installation node --version npm --version ``` ### **Linux:** ```bash # Ubuntu/Debian - NodeSource repository (Recommended) curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # Alternative: Package manager sudo apt install nodejs npm # RHEL/CentOS/Fedora sudo dnf install nodejs npm # Verify installation node --version npm --version ``` ## 🐳 **Docker Installation (Optional - for Full Stack)** Docker enables the complete development stack with Splunk, Traefik, and monitoring. ### **Windows:** ```powershell # Docker Desktop (Recommended) # Download from https://docker.com/products/docker-desktop/ # Winget winget install Docker.DockerDesktop # After installation, ensure Docker Desktop is running docker --version docker-compose --version ``` ### **macOS:** ```bash # Docker Desktop (Recommended) # Download from https://docker.com/products/docker-desktop/ # Homebrew brew install --cask docker # Verify installation docker --version docker-compose --version ``` ### **Linux:** ```bash # Ubuntu/Debian - Install Docker Engine sudo apt update sudo apt install apt-transport-https ca-certificates curl software-properties-common curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin # Start and enable Docker sudo systemctl start docker sudo systemctl enable docker # Add user to docker group (logout/login required) sudo usermod -aG docker $USER # Verify installation docker --version docker compose version ``` ## 🔧 **Additional Tools** ### **Git:** - **Windows:** `winget install Git.Git` or download from [git-scm.com](https://git-scm.com/) - **macOS:** `brew install git` or use Xcode Command Line Tools - **Linux:** `sudo apt install git` (Ubuntu/Debian) or `sudo dnf install git` (Fedora) ### **curl (for testing):** - **Windows:** Included in Windows 10+ or `winget install cURL.cURL` - **macOS:** Pre-installed or `brew install curl` - **Linux:** `sudo apt install curl` or `sudo dnf install curl` ## ✅ **Prerequisites Verification** We've included comprehensive scripts to verify all prerequisites are correctly installed: ### **Windows (PowerShell):** ```powershell # Run the prerequisites checker .\scripts\check-prerequisites.ps1 # For detailed information including installation paths .\scripts\check-prerequisites.ps1 -Detailed # For help and usage information .\scripts\check-prerequisites.ps1 -Help ``` ### **macOS/Linux (Bash):** ```bash # Run the prerequisites checker ./scripts/check-prerequisites.sh # For detailed information including installation paths ./scripts/check-prerequisites.sh --detailed # Smart install (preview, then install missing prerequisites) ./scripts/smart-install.sh --dry-run ./scripts/smart-install.sh # For help and usage information ./scripts/check-prerequisites.sh --help ``` **The verification scripts will:** - ✅ Check all required and optional tools - 📊 Show system information (OS, architecture, available space) - 🎯 Provide specific installation commands for missing tools - 🔧 Detect your package manager and suggest appropriate commands - 📋 Give you a clear summary of what needs to be installed ## 🎯 **Quick Setup Commands** ### **Windows (PowerShell as Administrator):** ```powershell # Install all prerequisites at once winget install Python.Python.3.12 astral-sh.uv OpenJS.NodeJS Docker.DockerDesktop Git.Git # Verify installations python --version; uv --version; node --version; docker --version; git --version ``` ### **macOS (with Homebrew):** ```bash # Install Homebrew if not installed /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install all prerequisites brew install python@3.11 uv node git brew install --cask docker # Verify installations python3 --version && uv --version && node --version && docker --version && git --version ``` ### **Linux (Ubuntu/Debian):** ```bash # Update system and install prerequisites sudo apt update sudo apt install -y python3.11 python3.11-pip python3.11-venv nodejs npm git curl # Install UV curl -LsSf https://astral.sh/uv/install.sh | sh export PATH="$HOME/.cargo/bin:$PATH" # Install Docker (optional) curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # Verify installations python3 --version && uv --version && node --version && git --version ``` ## 🏢 **Splunk Requirements** - **Splunk instance** (Enterprise or Cloud) - Valid Splunk credentials with appropriate permissions: - Search capabilities for your intended indexes - Admin access (for admin tools) - KV Store access (for KV Store tools) ## 🪟 **Windows-Specific Troubleshooting** ### **PowerShell Execution Policy:** ```powershell # If you get execution policy errors, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` ### **Common Windows Issues:** - **uv installation**: Try `winget install astral-sh.uv` or `pip install uv` - **Docker Desktop**: Ensure WSL2 backend is enabled - **Port conflicts**: Windows script auto-detects and uses available ports - **Node.js/npm**: Download from [nodejs.org](https://nodejs.org/) for MCP Inspector - **Python PATH**: Use Microsoft Store Python or ensure Python is in PATH ### **Debugging Commands:** ```powershell # Check Python installation python --version # Check uv installation uv --version # Check Docker docker --version docker info # Check Node.js node --version npx --version # View detailed help .\scripts\build_and_run.ps1 -Help ``` ## 🔄 **Next Steps** Once all prerequisites are installed: 1. **Clone the repository:** ```bash git clone https://github.com/deslicer/mcp-for-splunk.git cd mcp-for-splunk ``` 2. **Run the verification script:** - **Windows:** `.\scripts\check-prerequisites.ps1` - **macOS/Linux:** `./scripts/check-prerequisites.sh` 3. **Start the server via project script:** - **Windows:** ```powershell uv run mcp-server --local --detached uv run test-mcp-server # Optional: show detailed tools/resources and health output uv run test-mcp-server --detailed ``` - **macOS/Linux:** ```bash ./scripts/smart-install.sh --dry-run && ./scripts/smart-install.sh uv run mcp-server --local --detached uv run test-mcp-server # Optional: show detailed tools/resources and health output uv run test-mcp-server --detailed ``` 4. **The script will automatically:** - Install Python dependencies with UV - Create configuration files - Start the MCP server - Launch MCP Inspector (if Node.js available) - Set up Docker stack (if Docker available) - If you enable the `so1` Splunk container, remember to provide your own Splunk Enterprise license. You can mount it by uncommenting the license volume in the compose file (e.g., `./lic/splunk.lic:/tmp/license/splunk.lic:ro`) or add it via the Splunk Web UI after startup. ## 📚 **Additional Resources** - **[Main README](../README.md)** - Project overview and quick start - **[Windows Setup Guide](../WINDOWS_GUIDE.md)** - End-to-end Windows setup and troubleshooting - **[Docker Guide](../guides/deployment/DOCKER.md)** - Container deployment details - **[Testing Guide](../guides/TESTING.md)** - Testing and validation - **[Architecture Guide](../architecture/)** - Technical architecture overview - **[Contributing Guide](../contrib/contributing.md)** - How to contribute to the project