feat: Add documentation and scripts for local development environment setup

Author: dima-m711

DEV_ENVIRONMENT.md

@@ -0,0 +1,91 @@
+# MCPM Local Development Environment
+
+This document explains how to test MCPM CLI with local server data during development.
+
+## Environment Variable Configuration
+
+The MCPM CLI can now be configured to use a custom repository URL through the `MCPM_REPO_URL` environment variable.
+
+### Default Behavior
+
+By default, MCPM fetches server data from: `https://mcpm.sh/api/servers.json`
+
+### Override with Environment Variable
+
+You can override the repository URL by setting the `MCPM_REPO_URL` environment variable:
+
+```bash
+# Use local file
+export MCPM_REPO_URL="file:///path/to/local/servers.json"
+
+# Use local development server
+export MCPM_REPO_URL="http://localhost:4000/api/servers.json"
+
+# Use custom remote URL
+export MCPM_REPO_URL="https://your-custom-api.com/servers.json"
+```
+
+## Testing with Local Server Data
+
+### Method 1: Manual Environment Variable
+
+1. Generate local servers.json:
+
+   ```bash
+   ./scripts/prepare.sh _dev
+   ```
+
+2. Run CLI with local data:
+   ```bash
+   MCPM_REPO_URL="file://${PWD}/_dev/api/servers.json" python3 test_cli.py search
+   ```
+
+### Method 2: Helper Script (Recommended)
+
+Use the provided helper script that automatically handles setup:
+
+```bash
+# Make the script executable (first time only)
+chmod +x test_cli_local.sh
+
+# Run any CLI command with local data
+./test_cli_local.sh search
+./test_cli_local.sh info figma
+./test_cli_local.sh search --table
+```
+
+The helper script will:
+
+- Automatically generate `_dev/api/servers.json` if it doesn't exist
+- Set the appropriate `MCPM_REPO_URL` environment variable
+- Run the CLI with local server data
+
+## Supported URL Formats
+
+- **HTTP/HTTPS URLs**: `https://api.example.com/servers.json`
+- **File URLs**: `file:///absolute/path/to/servers.json`
+
+## Use Cases
+
+1. **Testing local server definitions** before submitting to the registry
+2. **Development with offline environments**
+3. **Using custom/private server registries**
+4. **Testing API changes** without affecting production
+
+## File Format
+
+The local `servers.json` file should follow the same format as the remote API:
+
+```json
+{
+  "server-name": {
+    "name": "server-name",
+    "description": "Server description",
+    "categories": ["category1"],
+    "tags": ["tag1", "tag2"]
+    // ... other server metadata
+  }
+}
+```
+
+This file is automatically generated from the individual JSON files in `mcp-registry/servers/` by the prepare script.

src/mcpm/cli.py

@@ -45,7 +45,7 @@ def print_logo():
         " ╚═╝     ╚═╝ ╚═════╝╚═╝     ╚═╝     ╚═╝ ",
         "",
         f"v{__version__}",
-        "Open Source. Forever Free.",
+        "Melio MCP Installer",
         "Built with ❤️ by Path Integral Institute",
     ]
 

src/mcpm/utils/repository.py

@@ -15,8 +15,8 @@
 
 logger = logging.getLogger(__name__)
 
-# Default repository URL
-DEFAULT_REPO_URL = "https://mcpm.sh/api/servers.json"
+# Default repository URL - can be overridden with MCPM_REPO_URL environment variable
+DEFAULT_REPO_URL = os.environ.get("MCPM_REPO_URL", "https://mcpm.sh/api/servers.json")
 
 # Default cache file path
 DEFAULT_CACHE_FILE = os.path.join(DEFAULT_CONFIG_DIR, "servers_cache.json")
@@ -91,16 +91,28 @@ def _fetch_servers(self, force_refresh: bool = False) -> Dict[str, Dict[str, Any
                 return self.servers_cache
 
         try:
-            response = requests.get(self.repo_url)
-            response.raise_for_status()
-            self.servers_cache = response.json()
-            self.last_refresh = datetime.now()
+            # Handle file:// URLs for local development
+            if self.repo_url.startswith("file://"):
+                file_path = self.repo_url[7:]  # Remove 'file://' prefix
+                with open(file_path, "r", encoding="utf-8") as f:
+                    self.servers_cache = json.load(f)
+                self.last_refresh = datetime.now()
+                
+                # Save the updated cache to file
+                self._save_cache_to_file()
+                
+                return self.servers_cache
+            else:
+                response = requests.get(self.repo_url)
+                response.raise_for_status()
+                self.servers_cache = response.json()
+                self.last_refresh = datetime.now()
 
-            # Save the updated cache to file
-            self._save_cache_to_file()
+                # Save the updated cache to file
+                self._save_cache_to_file()
 
-            return self.servers_cache
-        except requests.RequestException as e:
+                return self.servers_cache
+        except (requests.RequestException, FileNotFoundError, json.JSONDecodeError) as e:
             logger.error(f"Failed to fetch servers from {self.repo_url}: {e}")
             # Return empty dict if we can't fetch and have no cache
             return self.servers_cache or {}

test_cli_local.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# MCPM Local Development CLI Helper
+# This script runs the CLI using local server data from mcp-registry/servers
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Get the absolute path to the project directory
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Path to local servers.json file
+LOCAL_SERVERS_JSON="file://${PROJECT_DIR}/_dev/api/servers.json"
+
+# Check if _dev/api/servers.json exists
+if [ ! -f "${PROJECT_DIR}/_dev/api/servers.json" ]; then
+    echo -e "${BLUE}Local servers.json not found. Generating it now...${NC}"
+    
+    # Run prepare script to generate local servers.json
+    if ! ./scripts/prepare.sh _dev; then
+        echo "❌ Failed to generate local servers.json file"
+        exit 1
+    fi
+    
+    echo -e "${GREEN}✅ Local servers.json generated successfully!${NC}"
+fi
+
+# Run the CLI with local repository URL
+echo -e "${BLUE}Running MCPM CLI with local server data...${NC}"
+echo -e "${BLUE}Repository URL: ${LOCAL_SERVERS_JSON}${NC}"
+echo ""
+
+MCPM_REPO_URL="${LOCAL_SERVERS_JSON}" python3 test_cli.py "$@"