@ironclads/namecheap-mcp/CLAUDE.md

MCP server for Namecheap API integration - domain management, DNS, and domain suggestions

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Namecheap MCP (Model Context Protocol) server built with TypeScript that provides programmatic access to Namecheap domain management services through the MCP protocol. The server enables AI assistants to perform domain operations, DNS management, and generate domain suggestions.

## Development Commands

```bash
# Install dependencies
npm install

# Development mode (with hot reload)
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run production server
npm start

# Type checking
npm run typecheck

# Linting
npm run lint

# Run tests
npm test

# Package for distribution
npm pack
```

## Architecture

The project follows a clean architecture pattern:

- **`src/index.ts`**: Main MCP server entry point and request routing
- **`src/namecheap-client.ts`**: Namecheap API client with HTTP request handling
- **`src/tools.ts`**: MCP tool definitions and schemas
- **`src/types.ts`**: TypeScript type definitions and Zod schemas
- **`src/validation.ts`**: Input validation and sanitization functions
- **`src/domain-generator.ts`**: Domain suggestion algorithm and scoring system

## Configuration

Configuration can be provided via CLI arguments or environment variables. CLI arguments take precedence over environment variables.

### Environment Variables

- `NAMECHEAP_API_USER`: Your Namecheap API user
- `NAMECHEAP_API_KEY`: Your Namecheap API key
- `NAMECHEAP_USERNAME`: Your Namecheap username  
- `NAMECHEAP_CLIENT_IP`: Your whitelisted IP address
- `NAMECHEAP_SANDBOX`: Set to 'true' for sandbox mode (default: true)

### Running the Server

```bash
# Using CLI arguments
namecheap-mcp --api-user myuser --api-key mykey --username myuser --client-ip 1.2.3.4 --sandbox

# Using environment variables (recommended for security)
export NAMECHEAP_API_USER=myuser
export NAMECHEAP_API_KEY=mykey
export NAMECHEAP_USERNAME=myuser
export NAMECHEAP_CLIENT_IP=1.2.3.4
export NAMECHEAP_SANDBOX=true
namecheap-mcp

# Mix of both (CLI overrides environment)
export NAMECHEAP_API_USER=myuser
namecheap-mcp --api-key mykey --username myuser --client-ip 1.2.3.4 --sandbox
```

### Claude Desktop Configuration

The preferred method for Claude Desktop integration:

```json
{
  "mcpServers": {
    "namecheap": {
      "command": "namecheap-mcp",
      "args": [],
      "env": {
        "NAMECHEAP_API_USER": "your-api-user",
        "NAMECHEAP_API_KEY": "your-api-key",
        "NAMECHEAP_USERNAME": "your-username",
        "NAMECHEAP_CLIENT_IP": "your-whitelisted-ip",
        "NAMECHEAP_SANDBOX": "true"
      }
    }
  }
}
```

**Installation requirement**: Global installation is required for this configuration:
```bash
npm install -g @ironclads/namecheap-mcp@1.4.4
```

## Available MCP Tools

### Domain Management
- `check_domain`: Check domain availability
- `check_domains_bulk`: Check availability of multiple domains at once (up to 50)
- `list_domains`: List all domains in your Namecheap account with pagination and filtering
- `get_domain_info`: Get domain registration info
- `register_domain`: Register a new domain
- `renew_domain`: Renew existing domain
- `suggest_domains`: Generate domain suggestions based on keywords

### Nameserver Management  
- `get_nameservers`: Get current nameservers
- `set_nameservers`: Set custom nameservers

## Domain List Features

The `list_domains` tool provides comprehensive domain management:

- **Pagination**: Support for page-based navigation through large domain lists
- **Sorting**: Sort by name, creation date, or expiration date (ascending/descending)
- **Search**: Filter domains by search terms
- **Detailed Info**: Shows domain status, expiration, auto-renewal, and privacy settings
- **Account Overview**: Total domain count and status summaries

Example usage:
```json
{
  "tool": "list_domains",
  "arguments": {
    "page": 1,
    "pageSize": 20,
    "sortBy": "EXPIREDATE",
    "searchTerm": "example"
  }
}
```

## Domain Suggestion Features

The `suggest_domains` tool uses intelligent algorithms to generate domain suggestions:

- **Smart Generation**: Uses prefixes, suffixes, and alternative words
- **Real-time Availability**: Checks actual domain availability through Namecheap API
- **Scoring System**: Rates suggestions based on length, pronounceability, and brandability
- **Multiple TLDs**: Supports checking across different top-level domains
- **Flexible Options**: Configurable parameters for hyphens, numbers, length limits
- **Suggestion Types**: Categorizes suggestions as exact, prefix, suffix, alternate, or related

## Error Handling

All API errors are properly caught and returned as MCP-compliant error responses:

- **Validation Errors**: Input validation uses Zod schemas for type safety
- **API Errors**: Namecheap API errors are properly parsed and formatted
- **Network Errors**: HTTP request failures are handled gracefully
- **Authentication Errors**: Clear messages for API key and authentication issues

## Testing

The project includes comprehensive tests:

- **Unit Tests**: Test individual components and functions
- **Integration Tests**: Test MCP tool functionality
- **Validation Tests**: Test input validation schemas
- **Domain Generation Tests**: Test domain suggestion algorithms

Run tests with:
```bash
npm test
```

## Security Considerations

- **Environment Variables**: Store API credentials in environment variables, never in code
- **IP Whitelisting**: Namecheap requires IP address whitelisting for API access
- **Sandbox Mode**: Always test in sandbox mode before production operations
- **Key Rotation**: Regularly rotate API keys for security
- **Input Validation**: All inputs are validated using Zod schemas

## Deployment

### Global Installation
```bash
npm install -g @ironclads/namecheap-mcp@1.4.4
```

### Package Distribution
```bash
npm run build
npm pack
npm publish
```

### Version Management
```bash
# Update version
npm version patch|minor|major

# Update internal version strings
# (Remember to update src/index.ts version strings)
```

## Troubleshooting

### Common Development Issues

1. **Build Failures**: Check TypeScript configuration and dependencies
2. **Test Failures**: Ensure all dependencies are installed and API mocks are working
3. **API Errors**: Verify Namecheap API credentials and IP whitelisting
4. **MCP Connection**: Check Claude Desktop configuration and global installation

### Debug Mode
```bash
# Enable debug logging
DEBUG=* namecheap-mcp

# Check configuration
namecheap-mcp --help
```

## API Limitations

- **Rate Limits**: Namecheap API has rate limits (specific limits not documented)
- **IP Restrictions**: API access limited to whitelisted IP addresses
- **Sandbox Limitations**: Some features may not be available in sandbox mode
- **Bulk Operations**: Domain bulk checks limited to 50 domains per request