Binary Troubleshooting

This guide covers issues specific to binary installation and execution of the WhoisXML API MCP Server. Binary installation provides maximum control and minimal dependencies, but can encounter platform-specific challenges.

Quick Resolution

Most binary issues can be resolved by:

  1. Checking file permissions: ls -la mcp-whoisxmlapi
  2. Making executable: chmod +x mcp-whoisxmlapi
  3. Testing execution: ./mcp-whoisxmlapi --help
  4. Using absolute paths in configuration files

File and Permission Issues

Binary Not Found or Executable

Symptoms:

  • "command not found" or "No such file or directory"
  • "Permission denied" when trying to execute
  • Binary exists but won't run

Diagnosis:

# Check if file exists and permissions
ls -la mcp-whoisxmlapi

# Check file type and architecture
file mcp-whoisxmlapi

# Test execution
./mcp-whoisxmlapi --help

# Check PATH
echo $PATH
which mcp-whoisxmlapi

Solutions:

  1. Make file executable:

    chmod +x mcp-whoisxmlapi

# Verify permissions
ls -la mcp-whoisxmlapi
# Should show: -rwxr-xr-x or similar

  2. Use absolute path:

    # Find full path
pwd
realpath mcp-whoisxmlapi

# Use absolute path in configuration
/full/path/to/mcp-whoisxmlapi --help

  3. Install to system PATH:

    # Copy to system bin directory
sudo cp mcp-whoisxmlapi /usr/local/bin/
sudo chmod +x /usr/local/bin/mcp-whoisxmlapi

# Test system-wide access
mcp-whoisxmlapi --version

  4. Create symlink:

    # Create symlink in PATH
sudo ln -s $(pwd)/mcp-whoisxmlapi /usr/local/bin/mcp-whoisxmlapi

# Test
mcp-whoisxmlapi --help

Wrong Architecture or Platform

Symptoms:

  • "Bad CPU type in executable" (macOS)
  • "cannot execute binary file: Exec format error" (Linux)
  • Binary runs but crashes immediately

Diagnosis:

# Check system architecture
uname -m
uname -s

# Check binary architecture
file mcp-whoisxmlapi

# For detailed info (Linux)
readelf -h mcp-whoisxmlapi

# For detailed info (macOS)
otool -f mcp-whoisxmlapi

Solutions:

  1. Download correct binary:

    # Check your platform
echo "OS: $(uname -s), Arch: $(uname -m)"

# Download appropriate binary:
# Linux x86_64: mcp-whoisxmlapi-linux-amd64
# Linux ARM64: mcp-whoisxmlapi-linux-arm64
# macOS Intel: mcp-whoisxmlapi-darwin-amd64
# macOS Apple Silicon: mcp-whoisxmlapi-darwin-arm64
# Windows x86_64: mcp-whoisxmlapi-windows-amd64.exe

  2. Verify download integrity:

    # Check file size (should be several MB)
ls -lh mcp-whoisxmlapi

# Verify it's not HTML error page
head -n 5 mcp-whoisxmlapi

  3. Use alternative installation method:

    # If binary doesn't work, try Docker or npm
docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1
# or
npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

macOS-Specific Issues

Quarantine and Security

Symptoms:

  • "mcp-whoisxmlapi cannot be opened because the developer cannot be verified"
  • "mcp-whoisxmlapi is damaged and can't be opened"
  • System blocks execution with security warning

Diagnosis:

# Check quarantine attributes
xattr -l mcp-whoisxmlapi

# Look for com.apple.quarantine
ls -la@ mcp-whoisxmlapi

Solutions:

  1. Remove quarantine (recommended):

    # Remove quarantine attribute
xattr -dr com.apple.quarantine mcp-whoisxmlapi

# Verify removal
xattr -l mcp-whoisxmlapi

# Test execution
./mcp-whoisxmlapi --version

  2. System Preferences method:

    # Step 1: Try to run the binary (will fail)
./mcp-whoisxmlapi --help

# Step 2: Go to System Preferences → Security & Privacy → General
# Step 3: Click "Allow Anyway" next to the blocked binary
# Step 4: Try running again and click "Open"

  3. Right-click method:

    # In Finder:
# 1. Right-click the binary
# 2. Select "Open" from context menu
# 3. Click "Open" in the security dialog

  4. Command line bypass:

    # For one-time execution
spctl --add mcp-whoisxmlapi

# Then run normally
./mcp-whoisxmlapi --help

Code Signing Issues

Symptoms:

  • Binary is quarantined repeatedly
  • "Malicious software" warnings
  • Gatekeeper blocks execution

Solutions:

  1. Check code signing:

    # Check signature
codesign -dv mcp-whoisxmlapi

# Check if signature is valid
codesign -v mcp-whoisxmlapi

  2. Temporary Gatekeeper disable (not recommended):

    # Disable Gatekeeper temporarily
sudo spctl --master-disable

# Run binary
./mcp-whoisxmlapi --help

# Re-enable Gatekeeper
sudo spctl --master-enable

  3. Use alternative methods:

    # Use Docker instead
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Or npm
npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

Linux-Specific Issues

Missing Dependencies

Symptoms:

  • "error while loading shared libraries"
  • "No such file or directory" despite file existing
  • Binary starts but crashes with library errors

Diagnosis:

# Check shared library dependencies
ldd mcp-whoisxmlapi

# Check for missing libraries
objdump -p mcp-whoisxmlapi | grep NEEDED

# Check system libraries
ldconfig -p | grep libc

Solutions:

  1. Install missing libraries (Ubuntu/Debian):

    # Update package list
sudo apt-get update

# Install common dependencies
sudo apt-get install libc6 libgcc-s1 libstdc++6

# For older systems
sudo apt-get install libc6-dev

  2. Install missing libraries (CentOS/RHEL/Fedora):

    # Update packages
sudo yum update
# or
sudo dnf update

# Install common dependencies
sudo yum install glibc libgcc libstdc++
# or
sudo dnf install glibc libgcc libstdc++

  3. Check architecture compatibility:

    # Check if trying to run 32-bit on 64-bit
file mcp-whoisxmlapi
getconf LONG_BIT

# Install 32-bit compatibility (if needed)
sudo apt-get install libc6:i386 libgcc1:i386

SELinux Issues

Symptoms:

  • "Permission denied" despite correct file permissions
  • SELinux denials in system logs
  • Binary blocked by security policy

Diagnosis:

# Check SELinux status
sestatus

# Check SELinux denials
sudo ausearch -m avc -ts recent | grep mcp-whoisxmlapi

# Check file context
ls -Z mcp-whoisxmlapi

Solutions:

  1. Set correct SELinux context:

    # Set executable context
sudo chcon -t bin_t mcp-whoisxmlapi

# Or use restorecon
sudo restorecon -v mcp-whoisxmlapi

  2. Temporary permissive mode:

    # Set SELinux to permissive (temporary)
sudo setenforce 0

# Test execution
./mcp-whoisxmlapi --help

# Re-enable SELinux
sudo setenforce 1

  3. Create SELinux policy (advanced):

    # Generate policy from denials
sudo audit2allow -a -M mcp-whoisxmlapi
sudo semodule -i mcp-whoisxmlapi.pp

Windows-Specific Issues

Windows Defender and Antivirus

Symptoms:

  • Binary deleted by antivirus
  • "Threat detected" notifications
  • Execution blocked by Windows Defender

Diagnosis:

# Check Windows Defender status
Get-MpComputerStatus

# Check threat history
Get-MpThreatDetection

Solutions:

  1. Add exclusion to Windows Defender:

    # Add file exclusion (as Administrator)
Add-MpPreference -ExclusionPath "C:\path\to\mcp-whoisxmlapi.exe"

# Add process exclusion
Add-MpPreference -ExclusionProcess "mcp-whoisxmlapi.exe"

  2. Temporarily disable real-time protection:

    # Disable temporarily (as Administrator)
Set-MpPreference -DisableRealtimeMonitoring $true

# Test execution
.\mcp-whoisxmlapi.exe --help

# Re-enable
Set-MpPreference -DisableRealtimeMonitoring $false

  3. Use alternative installation:

    # Use npx instead
npx -y @whoisxmlapidotcom/mcp-whoisxmlapi --help

# Or Docker
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

PowerShell Execution Policy

Symptoms:

  • Cannot run binary from PowerShell
  • Execution policy restrictions
  • Script execution disabled

Solutions:

  1. Check and set execution policy:

    # Check current policy
Get-ExecutionPolicy

# Set policy for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or bypass for single execution
PowerShell -ExecutionPolicy Bypass -Command ".\mcp-whoisxmlapi.exe --help"

  2. Use Command Prompt instead:

    REM Use cmd instead of PowerShell
mcp-whoisxmlapi.exe --help

Configuration and Integration Issues

MCP Client Configuration

Symptoms:

  • Binary works standalone but not with MCP client
  • Configuration file not found
  • Path issues in MCP configuration

Diagnosis:

# Test binary independently
./mcp-whoisxmlapi --help
WHOISXMLAPI_TOKEN=test ./mcp-whoisxmlapi --help

# Check configuration file syntax
python -m json.tool config.json
# or
jq . config.json

# Verify path in configuration
ls -la /path/specified/in/config

Solutions:

  1. Use absolute paths:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token-here"
      }
    }
  }
}

  2. Verify binary location:

    # Find exact path
which mcp-whoisxmlapi
realpath mcp-whoisxmlapi

# Use in configuration
{
  "command": "/exact/path/to/mcp-whoisxmlapi"
}

  3. Test configuration:

    # Test the exact command from config
/usr/local/bin/mcp-whoisxmlapi --help

# Test with environment
WHOISXMLAPI_TOKEN=test /usr/local/bin/mcp-whoisxmlapi --help

Environment Variable Issues

Symptoms:

  • "API key token environment variable is required"
  • Binary doesn't read environment variables
  • Environment not passed correctly

Solutions:

  1. Test environment directly:

    # Set and test environment
export WHOISXMLAPI_TOKEN="your-token"
./mcp-whoisxmlapi --help

# Or inline
WHOISXMLAPI_TOKEN=your-token ./mcp-whoisxmlapi --help

  2. Check shell environment:

    # Verify variable is set
echo $WHOISXMLAPI_TOKEN
env | grep WHOISXMLAPI

# Add to shell profile if needed
echo 'export WHOISXMLAPI_TOKEN="your-token"' >> ~/.bashrc
source ~/.bashrc

  3. Use MCP client environment:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token-here"
      }
    }
  }
}

Performance and Resource Issues

Memory and CPU Usage

Symptoms:

  • High memory usage
  • Binary killed by OOM killer
  • Slow performance

Diagnosis:

# Monitor resource usage
top -p $(pgrep mcp-whoisxmlapi)
htop -p $(pgrep mcp-whoisxmlapi)

# Check memory limits
ulimit -a

# Check system resources
free -h
df -h

Solutions:

  1. Monitor resource usage:

    # Watch resource usage
watch 'ps aux | grep mcp-whoisxmlapi'

# Check memory limits
cat /proc/$(pgrep mcp-whoisxmlapi)/status | grep Vm

  2. Increase system limits:

    # Increase memory limit
ulimit -m 1048576  # 1GB

# Or edit /etc/security/limits.conf
echo "* soft memlock 1048576" | sudo tee -a /etc/security/limits.conf

  3. Use resource monitoring:

    # Run with resource monitoring
time ./mcp-whoisxmlapi --help

# Use systemd for process management (Linux)
sudo systemctl edit --force --full mcp-whoisxmlapi.service

Debugging and Diagnostics

Comprehensive Binary Check

# File information
ls -la mcp-whoisxmlapi
file mcp-whoisxmlapi
stat mcp-whoisxmlapi

# Architecture and dependencies
uname -m
ldd mcp-whoisxmlapi  # Linux
otool -L mcp-whoisxmlapi  # macOS

# Execution test
./mcp-whoisxmlapi --version
./mcp-whoisxmlapi --help
WHOISXMLAPI_TOKEN=test ./mcp-whoisxmlapi --help

# Security attributes (macOS)
xattr -l mcp-whoisxmlapi
codesign -dv mcp-whoisxmlapi

# SELinux context (Linux)
ls -Z mcp-whoisxmlapi

System Environment Check

# System information
uname -a
cat /etc/os-release  # Linux
sw_vers  # macOS

# Shell and environment
echo $SHELL
echo $PATH
env | grep WHOISXMLAPI

# Permissions and ownership
whoami
groups
umask

Binary Integrity Verification

# Check if binary is corrupted
hexdump -C mcp-whoisxmlapi | head -20

# Check file size (should be several MB)
ls -lh mcp-whoisxmlapi

# Compare with known good binary
sha256sum mcp-whoisxmlapi  # If checksums are provided

Prevention and Best Practices

Installation Best Practices

  1. Download verification:

    # Always download from official sources
# Verify file size and type after download
ls -lh mcp-whoisxmlapi
file mcp-whoisxmlapi

  2. Secure installation:

    # Set proper permissions
chmod 755 mcp-whoisxmlapi

# Install to standard location
sudo cp mcp-whoisxmlapi /usr/local/bin/
sudo chown root:root /usr/local/bin/mcp-whoisxmlapi

  3. Environment setup:

    # Use absolute paths in configurations
# Set environment variables in shell profile
# Test independently before integrating

Configuration Best Practices

  1. Always use absolute paths:

    {
  "command": "/usr/local/bin/mcp-whoisxmlapi"
}

  2. Test configuration:

    # Always test binary independently first
/usr/local/bin/mcp-whoisxmlapi --help

  3. Environment management:

    # Use shell profiles for permanent variables
echo 'export WHOISXMLAPI_TOKEN="your-token"' >> ~/.bashrc

Getting Help

Information to Collect

When seeking help, provide:

# System and binary information
uname -a
ls -la mcp-whoisxmlapi
file mcp-whoisxmlapi

# Execution attempts
./mcp-whoisxmlapi --version 2>&1
./mcp-whoisxmlapi --help 2>&1

# Environment
echo $PATH
env | grep WHOISXMLAPI

# Configuration (remove tokens)
cat your-mcp-config.json

Common Commands Reference

# File operations
chmod +x mcp-whoisxmlapi          # Make executable
ls -la mcp-whoisxmlapi           # Check permissions
file mcp-whoisxmlapi             # Check file type
which mcp-whoisxmlapi            # Find in PATH

# Installation
sudo cp mcp-whoisxmlapi /usr/local/bin/
sudo chmod +x /usr/local/bin/mcp-whoisxmlapi

# Testing
./mcp-whoisxmlapi --version       # Version check
./mcp-whoisxmlapi --help          # Help output
WHOISXMLAPI_TOKEN=test ./mcp-whoisxmlapi --help

# Debugging
ldd mcp-whoisxmlapi              # Dependencies (Linux)
otool -L mcp-whoisxmlapi         # Dependencies (macOS)
xattr -l mcp-whoisxmlapi         # Attributes (macOS)
Last Updated: