CLI Tool for MCP Server Registration and Health Validation

[aarora79]

Summary

Create a CLI tool that allows users to register new MCP servers with the MCP Gateway Registry without requiring the web UI, including automated health checks and search index updates.

Background

Currently, the only way to register a new MCP server with the registry is through the web UI. This creates friction for automation, CI/CD pipelines, and power users who prefer command-line tools.

Proposed Solution

CLI Tool Development

Create a new CLI tool that leverages the existing mcpgw client and its register_server tool to provide command-line MCP server registration capabilities.

Input Format

The CLI should accept a JSON configuration file similar to the existing server definitions in the registry:

Example Input File: registry/servers/currenttime.json

{
  "server_name": "Current Time API",
  "description": "A simple API that returns the current server time in various formats.",
  "path": "/currenttime/",
  "proxy_pass_url": "http://currenttime-server:8000/",
  "auth_type": "none",
  "tags": [],
  "num_tools": 1,
  "num_stars": 0,
  "is_python": true,
  "license": "MIT-0",
  "tool_list": [
    {
      "name": "current_time_by_timezone",
      "parsed_description": {
        "main": "Get the current time for a specified timezone using the timeapi.io API.",
        "args": "params: TZ_Name object containing the timezone name",
        "returns": "str: JSON response from the API with current time information",
        "raises": "Exception: If the API request fails after maximum retries"
      },
      "schema": {
        "$defs": {
          "TZ_Name": {
            "description": "Parameters for specifying the name of the timezone for which to find out the current time.",
            "properties": {
              "tz_name": {
                "default": "America/New_York",
                "description": "Name of the timezone for which to find out the current time",
                "title": "Tz Name",
                "type": "string"
              }
            },
            "title": "TZ_Name",
            "type": "object"
          }
        },
        "properties": {
          "params": {
            "$ref": "#/$defs/TZ_Name"
          }
        },
        "required": [
          "params"
        ],
        "title": "current_time_by_timezoneArguments",
        "type": "object"
      }
    }
  ]
}

Implementation Plan

Phase 1: Review and Update mcpgw Client

1. Audit Existing Tool: Review the current register_server tool in the mcpgw client
2. Update If Needed: Ensure the tool is compatible with current registry API
3. Test Current Functionality: Verify the tool works with the existing registry

Phase 2: CLI Development

Create a new CLI tool with the following interface:

# Register a new MCP server
mcp-registry-cli register --config server-config.json

# Register with additional options
mcp-registry-cli register \
  --config server-config.json \
  --registry-url https://mcpgateway.company.com \
  --auth-token ${MCP_AUTH_TOKEN} \
  --validate-health \
  --update-search-index

# Validate configuration without registering
mcp-registry-cli validate --config server-config.json

# List registered servers
mcp-registry-cli list

# Health check specific server
mcp-registry-cli health-check --server-name "Current Time API"

Phase 3: Integration with mcpgw Client

# cli_implementation.py
import json
import argparse
from mcpgw_client import MCPGatewayClient

class MCPRegistryCLI:
    def __init__(self, registry_url: str, auth_token: str):
        self.client = MCPGatewayClient(registry_url, auth_token)
    
    def register_server(self, config_file: str, validate_health: bool = True):
        """Register MCP server from JSON configuration"""
        with open(config_file, 'r') as f:
            server_config = json.load(f)
        
        # Call existing register_server tool
        result = self.client.call_tool(
            'register_server',
            params=server_config
        )
        
        if validate_health:
            self.perform_health_checks(server_config['server_name'])
        
        return result
    
    def perform_health_checks(self, server_name: str):
        """Comprehensive health validation"""
        print(f"Performing health checks for {server_name}...")
        
        # 1. Registry health check
        health_result = self.client.call_tool(
            'health_check_server',
            params={'server_name': server_name}
        )
        
        # 2. Verify FAISS index update
        search_result = self.client.call_tool(
            'intelligent_tool_finder',
            params={'query': f'tools from {server_name}'}
        )
        
        # 3. Tool discovery validation
        tools_result = self.client.call_tool(
            'list_tools',
            params={'server_name': server_name}
        )
        
        return {
            'health_check': health_result,
            'search_index': search_result,
            'tool_discovery': tools_result
        }

Comprehensive Testing Strategy

1. Health Check Validation

• Registry Connection: Verify the registry can reach the new MCP server
• Authentication: Test auth flow (if applicable)
• Tool Enumeration: Confirm all tools are discoverable
• Tool Execution: Test sample tool calls to ensure functionality

2. Search Index Updates

• FAISS Index: Verify the vector search index includes new server tools
• Tool Finder: Test intelligent tool finder can discover new tools
• Semantic Search: Validate tools are findable via natural language queries

Example test queries:

# Should find the current_time_by_timezone tool
mcp-registry-cli test-search "What time is it in New York?"
mcp-registry-cli test-search "Get current time for timezone"
mcp-registry-cli test-search "time zone information"

3. End-to-End Validation

# Complete registration and validation workflow
mcp-registry-cli register \
  --config examples/new-server.json \
  --validate-health \
  --test-search "relevant query for new tools" \
  --verify-tool-execution

CLI Features

Configuration Validation

• Schema Validation: Ensure JSON follows expected format
• URL Validation: Check that proxy_pass_url is reachable
• Tool Schema Validation: Verify tool schemas are valid MCP format

Interactive Mode

# Interactive server registration
mcp-registry-cli register --interactive

# Prompts user for:
# - Server name
# - Description  
# - Endpoint URL
# - Authentication type
# - Auto-discovery of tools (if supported)

Automation Support

• CI/CD Integration: Return appropriate exit codes for automation
• JSON Output: Machine-readable output format for scripting
• Dry Run Mode: Validate configuration without making changes

Success Criteria

• CLI tool successfully registers MCP servers from JSON configuration
• Integration with existing mcpgw client register_server tool
• Automated health checks verify server accessibility
• FAISS search index automatically updates with new server tools
• Intelligent tool finder can discover tools from newly registered servers
• Comprehensive validation ensures server is fully operational
• CLI supports both interactive and automated usage patterns
• Documentation and examples provided for common use cases

This CLI tool will significantly improve the developer experience for MCP server registration while ensuring comprehensive validation and testing of newly registered servers.