Legacy Web MCP Server

Legacy Web MCP Server implements the Model Context Protocol (MCP) to power automated discovery and analysis of legacy web applications. This AI-powered tool helps development teams automatically crawl websites, analyze site structure, and generate comprehensive documentation artifacts for modernization planning.

🚀 Now available on PyPI! Install and run globally with uvx legacy-web-mcp

Getting Started

Quick Start

For Most Users (Recommended)

# Install uvx (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the MCP server directly from PyPI
uvx legacy-web-mcp

That's it! The server is ready for MCP connections.

Detailed Installation Steps

Step 1: Install uvx

The Legacy Web MCP Server uses uvx for isolation and easy installation. Install it if you haven't already:

On macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify Installation:

uvx --version

Step 2: Install Legacy Web MCP Server

Option A: Direct Execution (Recommended)

# Run directly from PyPI - no installation required
uvx legacy-web-mcp

Option B: Global Installation

# Install globally and run
uvx install legacy-web-mcp
legacy-web-mcp

Option C: Specific Version

# Install specific version
uvx --from legacy-web-mcp==0.1.1 legacy-web-mcp

Step 3: Verify Installation

# Check version
uvx legacy-web-mcp --version

# Show help
uvx legacy-web-mcp --help

# Test server startup (Ctrl+C to stop)
uvx legacy-web-mcp

Claude Desktop Configuration

Step 1: Locate Configuration File

📍 Find your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/claude-desktop/config.json

Step 2: Add MCP Server Configuration

📝 Edit the configuration file and add the Legacy Web MCP Server:

{
  "mcpServers": {
    "legacy-web-mcp": {
      "command": "uvx",
      "args": ["legacy-web-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_openai_key_here",
        "ANTHROPIC_API_KEY": "your_anthropic_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here",
        "STEP1_MODEL": "gpt-4o-mini",
        "STEP2_MODEL": "gpt-4o-mini",
        "FALLBACK_MODEL": "gpt-4o-mini",
        "OPENAI_CHAT_MODEL": "gpt-4o-mini",
        "ANTHROPIC_CHAT_MODEL": "claude-3-haiku-20240307",
        "GEMINI_CHAT_MODEL": "gemini-1.5-flash",
        "PLAYWRIGHT_HEADLESS": "true",
        "MAX_CONCURRENT_PAGES": "3",
        "OUTPUT_ROOT": "docs/web_discovery"
      }
    }
  }
}

If you already have other MCP servers configured:

{
  "mcpServers": {
    "existing-server": {
      "command": "existing-command",
      "args": ["existing-args"]
    },
    "legacy-web-mcp": {
      "command": "uvx",
      "args": ["legacy-web-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_openai_key_here",
        "ANTHROPIC_API_KEY": "your_anthropic_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here",
        "STEP1_MODEL": "gpt-4o-mini",
        "STEP2_MODEL": "gpt-4o-mini",
        "FALLBACK_MODEL": "gpt-4o-mini",
        "OPENAI_CHAT_MODEL": "gpt-4o-mini",
        "ANTHROPIC_CHAT_MODEL": "claude-3-haiku-20240307",
        "GEMINI_CHAT_MODEL": "gemini-1.5-flash",
        "PLAYWRIGHT_HEADLESS": "true",
        "MAX_CONCURRENT_PAGES": "3",
        "OUTPUT_ROOT": "docs/web_discovery"
      }
    }
  }
}

Step 3: Configure Environment Variables

🔐 Important: Replace the placeholder values with your actual API keys and desired configuration.

Security Note: For better security, you can use environment variable references instead:

{
  "mcpServers": {
    "legacy-web-mcp": {
      "command": "uvx",
      "args": ["legacy-web-mcp"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "STEP1_MODEL": "gpt-4o-mini"
      }
    }
  }
}

Then set the environment variables in your shell profile:

export OPENAI_API_KEY="your_openai_key_here"
export ANTHROPIC_API_KEY="your_anthropic_key_here"
export GEMINI_API_KEY="your_gemini_key_here"

Step 4: Restart Claude Desktop

1. Quit Claude Desktop completely
2. Restart Claude Desktop
3. Look for the MCP connection indicator (🔌 icon)
4. Verify connection - you should see "legacy-web-mcp" in the MCP panel

Environment Configuration (Optional)

For AI-powered analysis features, configure LLM providers:

Step 1: Create Environment File

# If using development version, copy template
cp .env.template .env

Step 2: Configure LLM Providers

Edit .env with your API keys:

# LLM Providers (choose one or more)
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here
GEMINI_API_KEY=your_gemini_key_here

# Model Configuration (Required if using LLMs)
STEP1_MODEL=gpt-4o-mini
STEP2_MODEL=gpt-4o-mini
FALLBACK_MODEL=gpt-4o-mini

# Provider-specific chat models
OPENAI_CHAT_MODEL=gpt-4o-mini
ANTHROPIC_CHAT_MODEL=claude-3-haiku-20240307
GEMINI_CHAT_MODEL=gemini-1.5-flash

# Browser & Concurrency Settings
PLAYWRIGHT_HEADLESS=true
MAX_CONCURRENT_PAGES=3

# Output Directory
OUTPUT_ROOT=docs/web_discovery

Step 3: Install Browser Dependencies (Optional)

For enhanced website crawling:

# Install Playwright browsers
uvx --from legacy-web-mcp playwright install

Available MCP Tools

The server provides comprehensive website analysis and documentation tools:

🔍 Discovery & Analysis Tools

• discover_website - Comprehensive website structure discovery via sitemap/crawling
• analyze_legacy_site - Complete automated analysis workflow for legacy applications
• intelligent_analyze_site - AI-driven website analysis with natural language insights
• analyze_with_recommendations - Analysis with AI-powered modernization recommendations

📊 System & Health Tools

• ping - Server health and status information
• health_check - Comprehensive system health report with diagnostics
• validate_dependencies - Check Playwright browser installations
• test_llm_connectivity - Verify LLM provider connections and API health
• show_config - Display current configuration (redacted for security)

📁 File Management & Documentation

• setup_project_documentation_structure - Create project documentation folders
• organize_project_artifacts - Organize analysis results into project structure
• generate_master_analysis_report - Create comprehensive analysis reports
• generate_url_slug - Convert URLs to safe filenames
• create_gitignore_for_web_discovery - Generate version control guidance

🔧 Browser & Workflow Tools

• validate_browser_dependencies - Detailed browser installation status
• get_browser_metrics - Performance metrics for browser sessions
• execute_sequential_workflow - Multi-page analysis workflows
• capture_page_screenshot - Page screenshot capture
• simulate_page_interactions - Interactive element discovery and testing

🛠️ Debugging & Development Tools

• inspect_debug_session - Analysis debugging and quality inspection
• list_analysis_artifacts - View available analysis results
• export_analysis_artifacts - Export analysis data for external use
• validate_analysis_quality - Quality scoring and validation
• cleanup_old_artifacts - Maintenance and cleanup operations

Testing Your Installation

Basic Functionality Test

# Test server version
uvx legacy-web-mcp --version

# Test help command
uvx legacy-web-mcp --help

MCP Integration Test

With Claude Desktop running and configured:

1. Start a conversation in Claude Desktop
2. Look for the MCP connection indicator (🔌)
3. Try a simple command like asking Claude to "check the health of the legacy web MCP server"

Direct Tool Testing

# Clone the repository for testing scripts
git clone https://github.com/hieutrtr/web-discovery-mcp.git
cd web-discovery-mcp

# Test basic tools
uv run python scripts/test_mcp_client.py ping
uv run python scripts/test_mcp_client.py health_check

# Test website discovery
uv run python scripts/test_mcp_client.py discover_website https://example.com

# Test AI analysis (requires LLM configuration)
uv run python scripts/test_mcp_client.py analyze_legacy_site https://example.com

Advanced Configuration Options

Using Development Version

{
  "mcpServers": {
    "legacy-web-mcp": {
      "command": "uv",
      "args": ["run", "legacy-web-mcp"],
      "cwd": "/path/to/web-discovery-mcp"
    }
  }
}

Using Local Build

{
  "mcpServers": {
    "legacy-web-mcp": {
      "command": "uvx",
      "args": ["--from", ".", "legacy-web-mcp"],
      "cwd": "/path/to/web-discovery-mcp"
    }
  }
}

Using Specific Version

{
  "mcpServers": {
    "legacy-web-mcp": {
      "command": "uvx",
      "args": ["--from", "legacy-web-mcp==0.1.1", "legacy-web-mcp"]
    }
  }
}

Troubleshooting

MCP Connection Issues

Problem: Claude Desktop doesn't show MCP connection

Solutions:

1. Check configuration file location and syntax

   # Verify file exists and is valid JSON
   cat ~/.config/claude-desktop/config.json | jq .
   

2. Test uvx installation

   uvx --version
   uvx legacy-web-mcp --version
   

3. Check Claude Desktop logs (if available)

4. Restart Claude Desktop completely

Server Startup Issues

Problem: Server fails to start

Solutions:

1. Check Python version

   python3 --version  # Should be 3.11+
   

2. Reinstall the package

   uvx uninstall legacy-web-mcp
   uvx install legacy-web-mcp
   

3. Check for port conflicts

   # Test basic startup
   uvx legacy-web-mcp --help
   

Browser Dependencies Issues

Problem: Browser automation fails

Solutions:

1. Install Playwright browsers

   uvx --from legacy-web-mcp playwright install
   

2. Validate installation

   uv run python scripts/test_mcp_client.py validate_dependencies
   

3. Check system requirements for Playwright

LLM Configuration Issues

Problem: AI analysis tools fail

Solutions:

1. Verify API keys in environment

   # For development setup
   grep -E "API_KEY|MODEL" .env
   

2. Test LLM connectivity

   uv run python scripts/test_mcp_client.py test_llm_connectivity
   

3. Check model configuration

   uv run python scripts/test_mcp_client.py show_config
   

What It Does

The Legacy Web MCP Server automatically:

• 🔍 Discovers website structure via sitemaps and intelligent crawling
• 🧠 Analyzes legacy applications using AI-powered insights
• 📊 Documents findings in comprehensive reports
• 🔧 Recommends modernization strategies and technical approaches
• 📁 Organizes results in structured project documentation

Perfect for development teams planning legacy application modernization, conducting technical audits, or understanding complex website architectures.

Getting Help

Support Resources

• GitHub Issues: Report bugs or request features
• PyPI Package: View package details
• Documentation: Check the docs/ directory for detailed guides

Common Questions

Q: Do I need to install Python separately? A: No, uvx manages Python environments automatically.

Q: Can I use this with other MCP clients? A: Yes, any MCP-compatible client should work.

Q: Do I need LLM API keys to use basic features? A: No, website discovery works without LLM configuration. AI analysis features require API keys.

Q: How do I update to a newer version? A: Run uvx install --force legacy-web-mcp or use uvx directly which always uses the latest version.

Next Steps

After successful installation:

1. Try basic website discovery with Claude Desktop
2. Configure LLM providers for AI-powered analysis
3. Explore the available tools in the MCP interface
4. Check the documentation for advanced usage patterns

Happy analyzing! 🚀

License

Distributed under the MIT License. See LICENSE for details.