lmiranda
dafa8db8bb
The /initial-setup command was generating NETBOX_API_URL without the /api suffix, causing all MCP tools to fail with JSON parsing errors. Changes: - Update example URL to include /api suffix - Add instruction to auto-append /api if user forgets - Fix validation test to be consistent with actual usage Root cause: Setup asked for base URL (https://netbox.company.com) but NetBoxClient expects API URL (https://netbox.company.com/api). The validation test incorrectly added /api/ making it pass, while the actual MCP server failed. Fixes #126 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
165 lines
4.4 KiB
Markdown
165 lines
4.4 KiB
Markdown
---
|
|
description: Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server
|
|
---
|
|
|
|
# CMDB Assistant Setup Wizard
|
|
|
|
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
|
|
|
|
```bash
|
|
python3 --version
|
|
```
|
|
|
|
If below 3.10, stop setup and inform user.
|
|
|
|
---
|
|
|
|
## Phase 2: MCP Server Setup
|
|
|
|
### Step 2.1: Locate NetBox MCP Server
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
mkdir -p ~/.config/claude
|
|
```
|
|
|
|
### Step 3.2: Check NetBox Configuration
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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.
|