domotz-mcp/debug-checklist.md

MCP server for Domotz API and BMS (Building Management System) integration with IoT device monitoring

# Domotz MCP Server Debug Checklist

## Issue: New tools not loading after build and restart

### 1. Verify Build Output
```bash
# Check if compiled JS files exist
ls -la dist/tools/MQTT*.js
ls -la dist/tools/HomeAssistant*.js

# Compare timestamps
ls -la src/tools/*.ts | grep -E "(MQTT|HomeAssistant)"
ls -la dist/tools/*.js | grep -E "(MQTT|HomeAssistant)"
```

### 2. Check Running Process
```bash
# Find all node processes running index.js
ps aux | grep -E "node.*index.js" | grep -v grep

# Kill all domotz server processes
pkill -f "domotz.*index.js"

# Verify no processes remain
ps aux | grep -E "node.*index.js" | grep -v grep
```

### 3. Test Direct Execution
```bash
# Run server directly and check output
cd /Users/davidkennedy/Documents/Code/Chaplin/domotz-mcp-server/Domotz-MCP
node dist/index.js

# Look for tool loading messages in console output
```

### 4. Verify Tool Registration
Add debug logging to `dist/index.js`:
```javascript
// After line where tools are discovered
console.error(`[DEBUG] Found tools: ${tools.map(t => t.name).join(', ')}`);
```

### 5. Check MCP Settings
```bash
# Verify mcp_settings.json points to correct location
cat ~/.mcp/mcp_settings.json | jq '.mcpServers.domotz'

# Expected output should show:
# "command": "node",
# "args": ["/Users/davidkennedy/Documents/Code/Chaplin/domotz-mcp-server/Domotz-MCP/dist/index.js"]
```

### 6. Test Tool Discovery Mechanism
Create test script `test-discovery.js`:
```javascript
const fs = require('fs');
const path = require('path');

const toolsDir = path.join(__dirname, 'dist', 'tools');
console.log('Looking for tools in:', toolsDir);

const files = fs.readdirSync(toolsDir);
console.log('Found files:', files);

const toolFiles = files.filter(f => f.endsWith('Tool.js'));
console.log('Tool files:', toolFiles);

// Try to load each tool
for (const file of toolFiles) {
    try {
        const tool = require(path.join(toolsDir, file));
        console.log(`Loaded ${file}:`, Object.keys(tool));
    } catch (e) {
        console.error(`Failed to load ${file}:`, e.message);
    }
}
```

### 7. Version Verification
```bash
# Check version mismatch
grep -n "version" dist/index.js
grep "version" package.json
```

### 8. Clean Rebuild
```bash
# Complete clean and rebuild
rm -rf dist/
rm -rf node_modules/
npm install
npm run build

# Verify new files created
find dist -name "*.js" -newer package.json
```

### 9. Alternative Server Start Methods
Try these alternatives in mcp_settings.json:

Option A - Direct node execution:
```json
"domotz": {
  "command": "node",
  "args": ["/Users/davidkennedy/Documents/Code/Chaplin/domotz-mcp-server/Domotz-MCP/dist/index.js"],
  "env": {
    "DOMOTZ_API_KEY": "YOUR_API_KEY_HERE"
  }
}
```

Option B - NPM script:
```json
"domotz": {
  "command": "npm",
  "args": ["run", "start"],
  "cwd": "/Users/davidkennedy/Documents/Code/Chaplin/domotz-mcp-server/Domotz-MCP",
  "env": {
    "DOMOTZ_API_KEY": "YOUR_API_KEY_HERE"
  }
}
```

Option C - Shell wrapper:
```json
"domotz": {
  "command": "sh",
  "args": ["-c", "cd /Users/davidkennedy/Documents/Code/Chaplin/domotz-mcp-server/Domotz-MCP && node dist/index.js"],
  "env": {
    "DOMOTZ_API_KEY": "YOUR_API_KEY_HERE"
  }
}
```

### 10. MCP Client Cache
```bash
# Clear any MCP client caches
rm -rf ~/.mcp/cache/
rm -rf ~/Library/Caches/*mcp*

# Restart MCP client/Roo
```

## Expected Resolution
After following this checklist, the server should load all tools including:
- mqtt_connect
- mqtt_publish
- mqtt_subscribe
- home_assistant_discovery
- home_assistant_entity
- (plus all existing tools)

## If Still Not Working
1. Check for hardcoded tool lists in the codebase
2. Verify no environment variables are overriding tool discovery
3. Test with a minimal MCP server to isolate the issue
4. Check MCP client logs for additional error details