leo-claude-mktplace/plugins/cmdb-assistant/commands/initial-setup.md

description

description
Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server

CMDB Assistant Setup Wizard

Visual Output

When executing this command, display the plugin header:

┌──────────────────────────────────────────────────────────────────┐
│  🖥️ CMDB-ASSISTANT · Setup Wizard                                │
└──────────────────────────────────────────────────────────────────┘

Then proceed with the setup.

This command sets up the cmdb-assistant plugin with NetBox integration.

Important Context

• This command uses Bash, Read, Write, and AskUserQuestion tools - NOT MCP tools
• MCP tools won't work until after setup + session restart
• Uses NetBox MCP server (separate from Gitea MCP)

---

Phase 1: Environment Validation

Step 1.1: Check Python Version

python3 --version

If below 3.10, stop setup and inform user.

---

Phase 2: MCP Server Setup

Step 2.1: Locate NetBox MCP Server

find ~/.claude ~/.config/claude -name "mcp_server" -path "*netbox*" 2>/dev/null | head -5

If not found, ask user for marketplace location.

Step 2.2: Check Virtual Environment

ls -la /path/to/mcp-servers/netbox/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"

Step 2.3: Create Virtual Environment (if missing)

cd /path/to/mcp-servers/netbox && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate

---

Phase 3: System Configuration

Step 3.1: Create Config Directory

mkdir -p ~/.config/claude

Step 3.2: Check NetBox Configuration

cat ~/.config/claude/netbox.env 2>/dev/null || echo "FILE_NOT_FOUND"

If file exists with valid values: Skip to Phase 4. If missing or has placeholders: Continue.

Step 3.3: Gather NetBox Information

Use AskUserQuestion:

• Question: "What is your NetBox API URL? (e.g., https://netbox.company.com/api)"
• Header: "NetBox URL"
• Options:
  • "Other (I'll provide the URL)"

Ask user to provide the URL.

Important: The URL must include /api at the end. If the user provides a URL without /api, append it automatically.

Step 3.4: Create Configuration File

cat > ~/.config/claude/netbox.env << 'EOF'
# NetBox API Configuration
# Generated by cmdb-assistant /initial-setup

NETBOX_API_URL=<USER_PROVIDED_URL>
NETBOX_API_TOKEN=PASTE_YOUR_TOKEN_HERE
EOF
chmod 600 ~/.config/claude/netbox.env

Step 3.5: Token Instructions

---

Action Required: Add Your NetBox API Token

I've created ~/.config/claude/netbox.env but you need to add your API token manually.

Steps:

1. Open: nano ~/.config/claude/netbox.env
2. Generate token in NetBox: Admin → API Tokens → Add Token
3. Replace PASTE_YOUR_TOKEN_HERE with your token
4. Save the file

---

Use AskUserQuestion:

• Question: "Have you added your NetBox token?"
• Header: "Token"
• Options:
  • "Yes, I've added the token"
  • "Skip for now"

---

Phase 4: Validation

Step 4.1: Test Configuration (if token was added)

source ~/.config/claude/netbox.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Token $NETBOX_API_TOKEN" "$NETBOX_API_URL/"

Note: The URL already includes /api, so we just append / for the root API endpoint.

Report result:

• 200: Success
• 403: Invalid token
• Other: Connection issue

Step 4.2: Summary

╔════════════════════════════════════════════════════════════╗
║              CMDB-ASSISTANT SETUP COMPLETE                 ║
╠════════════════════════════════════════════════════════════╣
║ MCP Server (NetBox):   ✓ Ready                             ║
║ System Config:         ✓ ~/.config/claude/netbox.env       ║
╚════════════════════════════════════════════════════════════╝

Step 4.3: Session Restart Notice

---

⚠️ Session Restart Required

Restart your Claude Code session for MCP tools to become available.

After restart, you can:

• Run /cmdb-device <hostname> to look up a device
• Run /cmdb-ip <address> to look up an IP address
• Run /cmdb-site <name> to look up a site
• Run /cmdb-search <query> for general search

---

Note on Project Configuration

cmdb-assistant does not require project-level configuration. The NetBox connection is system-wide and not tied to specific repositories.