realtime-register-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Model Context Protocol (MCP) server that integrates AI assistants with the RealtimeRegister API for domain management operations. The server provides domain availability checking, bulk domain processing, and API connectivity testing through MCP tools.

Core Commands

Development Commands

• yarn build - Compile TypeScript to JavaScript in dist/
• yarn dev - Run server in development mode with tsx hot reloading
• yarn type-check - Run TypeScript type checking without compilation
• yarn test - Run Jest test suite
• yarn test:watch - Run tests in watch mode
• yarn test:coverage - Generate test coverage report
• yarn clean - Remove compiled dist/ directory

Production Commands

• yarn start - Run compiled server from dist/

Architecture Overview

Project Structure (Feature-Based)

src/
├── core/           # Core server and configuration
├── api/            # RealtimeRegister API clients
├── cache/          # Caching infrastructure
└── monitoring/     # Performance and reliability

Core Module (src/core/)

Server Architecture (core/server.ts)

• RealtimeRegisterMCPServer - Main MCP server class using stdio transport
• Provides 3 MCP tools: check_domain_availability, check_bulk_domains, test_api_connection
• Lazy initialization pattern for API client (starts without configuration)

Configuration (core/config.ts)

• Functional configuration loading with validation
• Environment variables with sensible defaults
• Type-safe configuration management

Error Handling (core/errors.ts)

• Custom error hierarchy with proper inheritance
• Specific error types: ConfigurationError, ValidationError, ApiError, NetworkError, MCPError
• Proper error chaining and context preservation

Utilities (core/utils.ts)

• Functional programming utilities (pipe, compose, retry, timeout)
• Type-safe Result type for error handling
• Common type guards and validation functions