mcp-name-cheap/CLAUDE.md

MCP Name Cheap - Development Documentation

This document contains development notes, architecture decisions, and implementation details for the MCP Name Cheap server.

Architecture Overview

The MCP Name Cheap server follows a layered architecture pattern with clear separation of concerns:

Layer 1: Core API Client (server.py)

• Purpose: Low-level HTTP client for Name Cheap API
• Responsibilities:
  • XML request/response handling
  • Comprehensive error classification and handling
  • Rate limiting and timeout management
  • Environment-based configuration loading

Layer 2: High-Level Client (client.py)

• Purpose: Business logic and smart identifier resolution
• Responsibilities:
  • Smart identifier resolution (domain names, SSL hostnames)
  • Input validation using domain format checking
  • Cache management for performance
  • Enhanced data formatting

Layer 3: FastMCP Tools (Resource Modules)

• Purpose: MCP protocol implementation with modular organization
• Modules:
  • domains.py: Domain registration, renewal, and management
  • dns.py: DNS record management and nameserver configuration
  • ssl.py: SSL certificate listing and information
  • account.py: Account information and balance checking

Layer 4: Server Assembly (fastmcp_server.py)

• Purpose: FastMCP server configuration and module mounting
• Responsibilities:
  • Module registration and organization
  • Server lifecycle management

Smart Identifier Resolution

The server implements smart identifier resolution to improve user experience:

Domain Identifiers

• Primary: Domain name (e.g., "example.com")
• Resolution: Exact match against account domains (case-insensitive)
• Validation: RFC-compliant domain format checking

SSL Certificate Identifiers

• Primary: Certificate ID (numeric)
• Secondary: Hostname matching
• Tertiary: SSL type matching
• Resolution: Exact match with fallback to hostname/type lookup

Error Handling Strategy

Comprehensive error handling with specific exception types:

NameCheapAPIError          # Base exception
├── NameCheapAuthError     # Authentication/authorization
├── NameCheapNotFoundError # Resource not found  
├── NameCheapRateLimitError # Rate limit exceeded
└── NameCheapValidationError # Input validation

Error Classification Logic

• Authentication: Keywords "authentication", "authorization", HTTP 401
• Not Found: Keywords "not found", specific error codes
• Validation: Keywords "validation", "invalid"
• Rate Limiting: HTTP 429
• Generic: All other API errors

Configuration Management

Environment-based configuration with validation:

# Required variables
NAMECHEAP_API_KEY      # API key from Name Cheap panel
NAMECHEAP_USERNAME     # Account username
NAMECHEAP_CLIENT_IP    # Whitelisted IP address

# Optional variables  
NAMECHEAP_SANDBOX=true # Sandbox mode (default: false)

Testing Strategy

Multi-layered testing approach:

Unit Tests (test_server.py, test_client.py)

• Individual component testing with mocks
• Error handling verification
• Configuration testing
• Input validation testing

Integration Tests

• Component interaction testing
• Cache behavior verification
• Workflow testing (register → renew → list)

MCP Tests (test_mcp_server.py)

• FastMCP in-memory testing patterns
• Tool functionality verification
• Resource content validation
• Error response testing

Performance Considerations

Caching Strategy

• Domain Cache: Cached after first list_domains() call
• SSL Cache: Cached after first list_ssl_certificates() call
• Cache Invalidation: Cleared after mutating operations (register, renew)

HTTP Configuration

• Total Timeout: 30 seconds
• Connect Timeout: 10 seconds
• Follow Redirects: Enabled
• Connection Reuse: Single httpx.Client instance

API Response Handling

XML Processing

• Uses xmltodict for XML-to-dict conversion
• Handles both single items and arrays consistently
• Preserves XML attributes with @ prefix

Response Normalization

• Single items converted to lists where appropriate
• Enhanced data with computed fields (e.g., _display_name, _is_expired)
• Consistent error response format across all tools

Resource URI Patterns

Standardized resource URI scheme:

namecheap://domains                    # List all domains
namecheap://domain/{domain_name}       # Specific domain info
namecheap://dns/{domain_name}          # DNS records
namecheap://nameservers/{domain_name}  # Nameserver info
namecheap://ssl                        # List SSL certificates
namecheap://ssl/{certificate_id}       # Specific certificate
namecheap://account                    # Account information
namecheap://balance                    # Account balance

CLI Implementation

Command-line interface for direct operations:

Command Structure

mcp-namecheap <category> <action> [arguments] [--json]

Categories

• domains: Domain management (list, check, info)
• dns: DNS management (get)
• ssl: SSL management (list)
• account: Account management (info, balance)

Development Workflow

Code Quality Pipeline

1. Black: Code formatting (88 char line length)
2. isort: Import sorting (black profile)
3. flake8: Linting with E203, E501, W503 ignored
4. mypy: Type checking with strict settings
5. pytest: Test execution with coverage

Pre-commit Hooks

• Trailing whitespace removal
• End-of-file fixing
• YAML validation
• Large file checking
• Merge conflict detection

FastMCP Integration

Server Mounting

Each resource module creates its own FastMCP instance:

domains_mcp = FastMCP("domains")
dns_mcp = FastMCP("dns")
ssl_mcp = FastMCP("ssl")
account_mcp = FastMCP("account")

Tool Organization

Tools are organized by functionality with consistent naming:

• list_*: List resources
• get_*: Get specific resource information
• set_*: Modify resources
• check_*: Validation operations

Resource Implementation

Resources provide human-readable content formatted for display:

• Tabular data with headers
• Status indicators and flags
• Error handling with graceful degradation

Known Limitations

Name Cheap API Constraints

• XML-only response format (no JSON)
• Rate limiting (specific limits not documented)
• Sandbox environment has limited functionality
• Some operations require domain ownership verification

Implementation Limitations

• No async support in underlying httpx client (by design for FastMCP compatibility)
• Cache invalidation is conservative (clears all caches on any mutation)
• SSL smart identifiers limited to hostname and type matching

Future Enhancements

Potential Improvements

1. Bulk Operations: Support for bulk domain operations
2. Webhook Support: Event notifications for domain/certificate changes
3. Advanced DNS: Support for advanced DNS record types
4. Certificate Management: SSL certificate ordering and management
5. Domain Transfer: Support for domain transfer operations

Architecture Considerations

• Consider event-driven cache invalidation
• Evaluate async support for improved performance
• Investigate GraphQL-style querying for complex operations

Debugging and Troubleshooting

Common Issues

1. Authentication Errors: Verify API key, username, and IP whitelisting
2. Domain Not Found: Ensure domain exists in the account
3. Rate Limiting: Implement exponential backoff for retries
4. Timeout Errors: Check network connectivity and Name Cheap API status

Debug Logging

The server includes comprehensive error messages with context:

• HTTP status codes and response bodies
• Name Cheap API error codes and descriptions
• Input validation failures with specific field information

Testing in Sandbox

• Use NAMECHEAP_SANDBOX=true for safe testing
• Sandbox has limited domain TLDs available
• Some operations may not work identically in sandbox vs production

---

This documentation is maintained alongside code changes and should be updated when architecture or implementation details change.