legacy-web-mcp 0.1.4

AI-powered legacy web application analysis and documentation generation via MCP

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.