Skip to content

getting-started.md

Latest commit

 

History

History
302 lines (216 loc) · 6.1 KB

getting-started.md

File metadata and controls

302 lines (216 loc) · 6.1 KB

Getting Started

This guide covers installation, configuration, and initial deployment with Ludus FastMCP.

Prerequisites

Required

Requirement Description
Python 3.11+ python --version to verify
Ludus Server Running Ludus instance with network access
API Credentials Generate with ludus user apikey on server

Optional (Recommended)

Component Description
MCP Client Claude Desktop, VS Code (Cline), AnythingLLM, or OpenWebUI
pipx Isolated Python application management

Installation

Method 1: Using pipx (Recommended)

pipx installs applications in isolated environments while making them globally available.

# Install pipx if not present
pip install pipx
pipx ensurepath

# Install Ludus FastMCP
pipx install git+https://github.com/tjnull/ludus-mcp-python.git

Method 2: From Source

git clone https://github.com/tjnull/ludus-mcp-python.git
cd ludus-mcp-python

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

pip install -e .

Verify Installation

ludus-fastmcp --version
ludus-fastmcp --list-tools  # Should display 157 tools

Configuration

Interactive Setup (Recommended)

Run the setup wizard to configure all prerequisites:

ludus-fastmcp --setup

The wizard will:

  • Verify Python environment and dependencies
  • Configure Ludus API credentials
  • Test connectivity to your Ludus server
  • Generate MCP client configuration files

Manual Configuration

Environment Variables

Create a .env file in your working directory:

LUDUS_API_URL=https://your-ludus-instance:8080
LUDUS_API_KEY=username.your-api-key

Or export directly:

export LUDUS_API_URL="https://your-ludus-instance:8080"
export LUDUS_API_KEY="username.your-api-key"

Test Connection

ludus-fastmcp --verbose

Successful output:

[INFO] Server Configuration:
  API URL: https://your-ludus-instance:8080
  API Key: ********************...

Press Ctrl+C to stop the test server.

MCP Client Configuration

Claude Desktop

  1. Locate 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 server configuration:

{
  "mcpServers": {
    "ludus": {
      "command": "ludus-fastmcp",
      "env": {
        "LUDUS_API_URL": "https://your-ludus-instance:8080",
        "LUDUS_API_KEY": "username.your-api-key"
      }
    }
  }
}

  1. Restart Claude Desktop (quit and reopen, not just close window)

  2. Verify: Ask Claude "List my Ludus ranges"

VS Code with Cline

  1. Install Cline extension from VS Code marketplace

  2. Open Settings (Cmd+, or Ctrl+,)

  3. Search for "Cline MCP Servers"

  4. Edit settings.json:

{
  "cline.mcpServers": {
    "ludus": {
      "command": "ludus-fastmcp",
      "env": {
        "LUDUS_API_URL": "https://your-ludus-instance:8080",
        "LUDUS_API_KEY": "username.your-api-key"
      }
    }
  }
}
  1. Reload VS Code (Cmd+Shift+P > "Developer: Reload Window")

AnythingLLM

  1. Navigate to Settings > Agent Configuration > Agent Skills

  2. Scroll to MCP Servers and click Add new MCP Server

  3. Configure:

    • Transport Type: stdio
    • Name: ludus
    • Command: ludus-fastmcp

  4. Add environment variables:

    LUDUS_API_URL=https://your-ludus-instance:8080
LUDUS_API_KEY=username.your-api-key

  5. Save and enable the MCP server

OpenWebUI

  1. Navigate to Admin Panel > Settings > Tools

  2. Click Add MCP Server:

{
  "name": "ludus",
  "transport": "stdio",
  "command": "ludus-fastmcp",
  "env": {
    "LUDUS_API_URL": "https://your-ludus-instance:8080",
    "LUDUS_API_KEY": "username.your-api-key"
  }
}
  1. Save and refresh

OpenCode

  1. Edit ~/.config/opencode/config.json:
{
  "mcpServers": {
    "ludus": {
      "command": "ludus-fastmcp",
      "env": {
        "LUDUS_API_URL": "https://your-ludus-instance:8080",
        "LUDUS_API_KEY": "username.your-api-key"
      }
    }
  }
}
  1. Alternatively, use CLI:
opencode mcp add ludus --command "ludus-fastmcp" \
  --env "LUDUS_API_URL=https://your-ludus-instance:8080" \
  --env "LUDUS_API_KEY=username.your-api-key"
  1. Restart OpenCode

First Deployment

Once connected to your MCP client:

Check Status

Show my current range status

List Templates

List all available Ludus templates

Deploy Scenario

Deploy the ad-basic scenario

This deploys a basic Active Directory environment:

  • 1 Domain Controller (Windows Server)
  • 1 Workstation (Windows 10/11)

Deployment time: 15-45 minutes depending on scenario complexity.

Monitor Deployment

Show deployment status

Create Snapshot

After deployment completes:

Create a snapshot of all VMs named clean-state

Command Line Usage

ludus-fastmcp Commands

ludus-fastmcp --setup           # Interactive setup wizard
ludus-fastmcp --setup-guide     # Manual setup instructions
ludus-fastmcp --list-tools      # List all 157 tools
ludus-fastmcp --version         # Version information
ludus-fastmcp --verbose         # Start with verbose logging
ludus-fastmcp --daemon          # Run as background service
ludus-fastmcp --status          # Check daemon status
ludus-fastmcp --stop-daemon     # Stop daemon

ludus-ai Commands

ludus-ai --help                 # Show available commands
ludus-ai setup-llm              # Configure local LLM (Ollama)
ludus-ai install anythingllm    # Install AnythingLLM
ludus-ai tool list-tools        # List tools via MCP
ludus-ai tool list-ranges       # List ranges
ludus-ai tool call-tool <name>  # Execute tool directly

Next Steps