Installation Guide

This guide will walk you through installing and setting up the ICE Locator MCP Server on your system.

System Requirements

Minimum Requirements

Python: 3.10 or higher
RAM: 512 MB available memory
Storage: 100 MB free disk space
Network: Internet connection for ICE data access

Recommended Requirements

Python: 3.11 or 3.12
RAM: 2 GB available memory
Storage: 1 GB free disk space (for caching)
Network: Stable broadband connection

Supported Operating Systems

Linux: Ubuntu 20.04+, CentOS 8+, Debian 11+
macOS: 10.15 (Catalina) or higher
Windows: Windows 10 or higher with WSL2 (recommended) or native Python

Installation Methods

Method 1: Install from PyPI (Recommended)

# Install via pip
pip install ice-locator-mcp

# Verify installation
ice-locator-mcp --version

Method 2: Install from Source

# Clone the repository
git clone https://github.com/trose/ice-locator-mcp.git
cd ice-locator-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Verify installation
python -m ice_locator_mcp --version

Method 3: Install with Development Dependencies

# Clone and setup for development
git clone https://github.com/trose/ice-locator-mcp.git
cd ice-locator-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install with development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests to verify
pytest

Configuration

Basic Configuration

Create a configuration file at ~/.config/ice-locator-mcp/config.json:

{
  "server": {
    "host": "localhost",
    "port": 8000,
    "debug": false
  },
  "rate_limiting": {
    "enabled": true,
    "requests_per_minute": 10,
    "burst_allowance": 20
  },
  "caching": {
    "enabled": true,
    "ttl": 3600,
    "cache_dir": "~/.cache/ice-locator-mcp"
  },
  "logging": {
    "level": "INFO",
    "file": "~/.logs/ice-locator-mcp.log"
  }
}

Environment Variables

Set these environment variables for configuration:

# Basic configuration
export ICE_LOCATOR_CONFIG="/path/to/config.json"
export ICE_LOCATOR_LOG_LEVEL="INFO"
export ICE_LOCATOR_CACHE_DIR="~/.cache/ice-locator-mcp"

# Rate limiting
export ICE_LOCATOR_RATE_LIMIT="10"
export ICE_LOCATOR_BURST_ALLOWANCE="20"

# Advanced settings
export ICE_LOCATOR_PROXY_ENABLED="true"
export ICE_LOCATOR_DEBUG="false"

Proxy Configuration (Optional)

For enhanced anti-detection, configure proxy settings:

{
  "proxy": {
    "enabled": true,
    "rotation_interval": 1800,
    "health_check_interval": 300,
    "proxy_list_file": "~/.config/ice-locator-mcp/proxies.txt"
  }
}

Create proxies.txt with proxy list:

proxy1.example.com:8080:username:password
proxy2.example.com:8080
socks5://proxy3.example.com:1080

MCP Client Setup

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ice-locator": {
      "command": "ice-locator-mcp",
      "args": [],
      "env": {
        "ICE_LOCATOR_CONFIG": "/Users/yourusername/.config/ice-locator-mcp/config.json"
      }
    }
  }
}

VS Code with MCP Extension

Install the MCP extension for VS Code
Add server configuration in VS Code settings:

{
  "mcp.servers": {
    "ice-locator": {
      "command": "ice-locator-mcp",
      "args": [],
      "cwd": "${workspaceFolder}"
    }
  }
}

Custom Python Client

#!/usr/bin/env python3
"""
Example Python client for ICE Locator MCP Server
"""

import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # Server configuration
    server_params = StdioServerParameters(
        command="ice-locator-mcp",
        args=[],
        env={"ICE_LOCATOR_CONFIG": "/path/to/config.json"}
    )

    # Connect to server
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize connection
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print("Available tools:", [tool.name for tool in tools])

            # Search by name example
            result = await session.call_tool(
                "search_by_name",
                {
                    "first_name": "John",
                    "last_name": "Doe",
                    "fuzzy_match": True
                }
            )

            print("Search result:", result.content[0].text)

if __name__ == "__main__":
    asyncio.run(main())

First Run

Test Installation

# Test basic functionality
ice-locator-mcp --help

# Test server startup
ice-locator-mcp --test-connection

# Run in debug mode
ice-locator-mcp --debug

Validate Configuration

# Check configuration
ice-locator-mcp --validate-config

# Test proxy settings (if configured)
ice-locator-mcp --test-proxies

# Check rate limiting
ice-locator-mcp --test-rate-limits

Example Search

# Simple name search
ice-locator-mcp search --name "John Doe"

# A-Number search
ice-locator-mcp search --alien-number "A123456789"

# Facility search
ice-locator-mcp search --facility "Houston Contract Detention Facility"

Docker Installation

Using Docker Hub

# Pull the image
docker pull trose/ice-locator-mcp:latest

# Run the container
docker run -d \
  --name ice-locator-mcp \
  -p 8000:8000 \
  -v ~/.config/ice-locator-mcp:/config \
  -v ~/.cache/ice-locator-mcp:/cache \
  trose/ice-locator-mcp:latest

Build from Source

# Clone repository
git clone https://github.com/trose/ice-locator-mcp.git
cd ice-locator-mcp

# Build Docker image
docker build -t ice-locator-mcp .

# Run with custom configuration
docker run -d \
  --name ice-locator-mcp \
  -p 8000:8000 \
  -v $(pwd)/config:/config \
  -v $(pwd)/cache:/cache \
  ice-locator-mcp

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  ice-locator-mcp:
    image: trose/ice-locator-mcp:latest
    ports:
      - "8000:8000"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - ./logs:/logs
    environment:
      - ICE_LOCATOR_CONFIG=/config/config.json
      - ICE_LOCATOR_LOG_LEVEL=INFO
    restart: unless-stopped

  # Optional: Add a reverse proxy
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - ice-locator-mcp

Run with:

docker-compose up -d

Verification

Health Check

# Check server health
curl http://localhost:8000/health

# Expected response:
# {"status": "healthy", "version": "0.1.0", "uptime": "0:05:23"}

Test MCP Connection

# Test MCP protocol
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}}, "id": 1}' | ice-locator-mcp

Sample Search Test

#!/usr/bin/env python3
"""
Installation verification script
"""

import asyncio
import subprocess
import sys

async def verify_installation():
    try:
        # Test basic import
        import ice_locator_mcp
        print("✓ Package import successful")

        # Test server startup
        result = subprocess.run([
            sys.executable, "-m", "ice_locator_mcp", "--version"
        ], capture_output=True, text=True, timeout=10)

        if result.returncode == 0:
            print(f"✓ Server startup successful: {result.stdout.strip()}")
        else:
            print(f"✗ Server startup failed: {result.stderr}")
            return False

        # Test configuration
        from ice_locator_mcp.core.config import Config
        config = Config()
        print("✓ Configuration loaded successfully")

        # Test basic functionality
        from ice_locator_mcp.tools.search_tools import SearchTools
        search_tools = SearchTools(None)
        print("✓ Search tools initialized")

        print("\n🎉 Installation verification completed successfully!")
        return True

    except ImportError as e:
        print(f"✗ Import error: {e}")
        return False
    except Exception as e:
        print(f"✗ Verification failed: {e}")
        return False

if __name__ == "__main__":
    success = asyncio.run(verify_installation())
    sys.exit(0 if success else 1)

Troubleshooting

Common Issues

Python Version Error:

# Check Python version
python --version

# If using Python 3.10+, but still getting errors:
python3.11 -m pip install ice-locator-mcp

Permission Errors:

# Use user installation
pip install --user ice-locator-mcp

# Or fix permissions
sudo chown -R $USER ~/.local

Import Errors:

# Clear pip cache
pip cache purge

# Reinstall in clean environment
pip uninstall ice-locator-mcp
pip install ice-locator-mcp

Configuration Not Found:

# Create config directory
mkdir -p ~/.config/ice-locator-mcp

# Copy default configuration
ice-locator-mcp --create-default-config

Getting Help

Check logs: ~/.logs/ice-locator-mcp.log
Run diagnostics: ice-locator-mcp --diagnose
Community support: GitHub Discussions
Report bugs: GitHub Issues

Next Steps

After successful installation:

Uninstallation

Remove Package

# Uninstall via pip
pip uninstall ice-locator-mcp

# Remove configuration and cache
rm -rf ~/.config/ice-locator-mcp
rm -rf ~/.cache/ice-locator-mcp
rm -rf ~/.logs/ice-locator-mcp.log

Clean Docker Installation

# Stop and remove containers
docker-compose down

# Remove images
docker rmi trose/ice-locator-mcp:latest

# Clean volumes
docker volume prune