mcp-installer: Instructions file for Claude Code

MCP Installer Project

Project Vision

The MCP Installer is a comprehensive platform designed to solve the complexity of installing MCP (Model Context Protocol) servers across different AI clients. The goal is to create an "App Store" experience for MCPs where users can browse, discover, and install MCP servers with minimal technical knowledge.

Core Principles

• Simplicity is Paramount: Abstract away all technical complexity
• Client-Agnostic: Support all major MCP clients (Claude Desktop, Cursor, VS Code, etc.)
• Trust and Security: Open-source, transparent, with minimal permissions
• One-Click Experience: Evolve from CLI commands to true one-click installation

Technical Architecture

The Core Challenge

Web applications cannot directly access local files due to browser security sandbox. Our solution bridges this gap through a phased approach:

1. Phase 1: CLI Companion Tool (@mcp-installer/cli)
2. Phase 2: Web Marketplace with copy-paste commands
3. Phase 3: Desktop Agent with custom protocol handlers

System Architecture

Web Frontend (Next.js) ↔ Local CLI Tool ↔ Client Config Files
     ↕                        ↕                ↕
MCP Server Registry     Command Generation    ~/.claude/, ~/.cursor/, etc.

Registry Distribution Architecture

The MCP Server Registry uses a hybrid approach for maximum reliability and performance:

graph TD
    A[CLI Start] --> B{Environment Check}
    B -->|Development| C[Try Local Paths]
    B -->|Production| D[Check Cache]

    C --> C1[packages/registry/servers.json]
    C --> C2[../registry/servers.json]
    C --> C3[./servers.json]
    C1 --> E[Load Successfully]
    C2 --> E
    C3 --> E
    C --> F[Local Failed] --> G[Fallback to Remote]

    D --> D1{Cache Valid?}
    D1 -->|Yes & TTL OK| E
    D1 -->|No/Expired| G

    G --> H[Fetch from GitHub Raw]
    H --> H1{Response?}
    H1 -->|200 OK| I[Parse JSON]
    H1 -->|304 Not Modified| J[Use Cache]
    H1 -->|Error| K[Try Stale Cache]

    I --> L[Save to Cache]
    L --> E
    J --> E
    K --> K1{Cache Exists?}
    K1 -->|Yes| E
    K1 -->|No| M[Final Fallback: Local]

    E --> N[Registry Ready]
    M --> O[All Failed - Error]

    style A fill:#e1f5fe
    style E fill:#c8e6c9
    style O fill:#ffcdd2
    style G fill:#fff3e0
    style L fill:#f3e5f5