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:

```python
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:

```python
# 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
```bash
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:
```python
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.*