CLI Tool for MCP Server Registration and Health Validation (#120)

[aarora79]

Summary

This PR implements a comprehensive CLI tool for MCP server registration, health validation, and lifecycle management, addressing issue #120.

Key Features

1. Service Management Script (cli/service_mgmt.sh)

• Add Command: Register new servers with automated verification
  • Config validation
  • Server registration
  • Scopes update verification
  • FAISS index verification
  • Health check validation
• Delete Command: Remove servers with complete cleanup verification
• Test Command: Validate server discoverability through intelligent search
• Monitor Command: Real-time health status for all or specific services
• Scopes Management: Add/remove servers from custom scopes groups

2. Enhanced MCP Client (cli/mcp_client.py)

• Streamable HTTP transport support
• JSON-formatted output for automation
• Comprehensive error handling
• Support for all MCP operations (ping, list tools, call tools)

3. MCP Utilities Library (cli/mcp_utils.py)

• Token credential management
• Automatic token refresh
• HTTP client with authentication
• Reusable functions for scripts

4. Example Server

• Full-featured example MCP server (servers/example-server/)
• Demonstrates best practices
• Used for testing and validation
• Complete with pyproject.toml and dependencies

5. Registry Management Tools (mcpgw server)

New tools exposed via /mcpgw endpoint:

• list_services - List all registered servers
• healthcheck_services - Get health status for all servers
• register_service - Register new servers
• remove_service - Remove servers
• toggle_service - Enable/disable servers
• add_server_to_scopes_groups - Add servers to specific scopes groups
• remove_server_from_scopes_groups - Remove servers from scopes groups

6. Scopes Management

• New registry/utils/scopes_manager.py for automated scopes.yml updates
• Add/remove servers from scopes groups programmatically
• Automatic auth server reload after scopes changes
• Fix: New servers now only added to unrestricted groups by default (not all groups)

7. Documentation

• Complete CLI guide (docs/cli.md)
• Service management guide (docs/service-management.md)
• Updated testing guide with new workflows
• Integration examples and best practices

Changes

New Files

• cli/service_mgmt.sh - Main service management script (822 lines)
• cli/mcp_client.py - Enhanced MCP client (137 lines)
• cli/mcp_utils.py - Utility library (426 lines)
• cli/examples/ - Example configuration files
• servers/example-server/ - Example MCP server implementation
• registry/utils/scopes_manager.py - Scopes management utilities (408 lines)
• docs/cli.md - CLI documentation (266 lines)
• docs/service-management.md - Service management guide (503 lines)

Modified Files

• servers/mcpgw/server.py - Added registry management tools
• registry/api/server_routes.py - New internal API endpoints
• registry/services/server_service.py - Enhanced server management
• auth_server/server.py - Scopes reload endpoint
• docs/testing.md - Updated with new testing workflows
• README.md - Added service management references

Bug Fixes

• Fixed server registration to only add new servers to unrestricted groups by default
• Fixed service verification in add/delete workflows
• Improved error handling in server registration

Testing

All features have been tested with:

• Server registration and verification
• Health check validation
• Search and discovery testing
• Scopes management operations
• Token credential refresh

Documentation

Complete documentation provided:

• CLI Guide
• Service Management Guide
• Updated Testing Guide
• Example configurations in cli/examples/

Breaking Changes

None - all changes are additive and backward compatible.

Related Issues

Closes #120

Demo

The service management script provides comprehensive output:

# Add a server
./cli/service_mgmt.sh add cli/examples/server-config.json

=== Adding Service: example-server ===
✓ Credentials ready
✓ Registering service completed
✓ Server found in service list
✓ Server found in container scopes.yml (2 occurrences)
✓ Server found in host scopes.yml (2 occurrences)
✓ Server found in FAISS metadata (1 occurrences)
✓ Health check completed

Health Check Results:
==================================================
Service: /example-server
  Status: ✓ healthy
  Last checked: 5 seconds ago
  Tools available: 3

✓ Service example-server successfully added and verified!