# CLAUDE.md

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

## Overview

Namecheap domain management Python library with REST API server and MCP server. Includes TLD price tracking with automatic exchange rate conversion (USD to KRW).

## Commands

```bash
# Run scripts (uses uv for dependency management)
uv run python <script>.py

# API server (runs on port 8000)
uv run python api_server.py

# MCP server (for Claude integration)
uv run python mcp_server.py

# Update TLD prices (fetches from Namecheap API + exchange rate)
uv run python update_prices.py

# Query prices CLI
uv run python prices.py          # All TLDs (cheapest first)
uv run python prices.py com      # Filter by TLD

# Service management
systemctl --user status namecheap-api.service
systemctl --user restart namecheap-api.service
systemctl --user list-timers namecheap-prices.timer
journalctl --user -u namecheap-api.service -f
```

## Architecture

### Core Components

- **namecheap.py**: API client wrapping Namecheap XML API. Classes: `NamecheapConfig`, `NamecheapAPI`, `RegistrantInfo`, `NamecheapError`
- **api_server.py**: FastAPI REST server with X-API-Key authentication. Exposes domain/DNS/pricing endpoints and OpenAI function calling schema at `/openai/schema`
- **mcp_server.py**: MCP server using FastMCP for Claude Code/Desktop integration
- **db.py**: SQLite database for TLD prices and exchange rates
- **update_prices.py**: Fetches Namecheap pricing + exchange rate, calculates KRW prices with formula: `USD × rate × 1.10 (VAT) × 1.03 (margin)`, rounded up to nearest 1000

### Data Flow

Namecheap XML API → `namecheap.py` → REST API (`api_server.py`) / MCP (`mcp_server.py`)
                                    ↓
                           `prices.db` (SQLite)

### Configuration

Environment variables in `.env` (copy from `.env.example`):
- `NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY`, `NAMECHEAP_USERNAME`, `NAMECHEAP_CLIENT_IP` - Namecheap API credentials
- `NAMECHEAP_SANDBOX` - Use sandbox API (true/false)
- `API_SERVER_KEY` - REST API authentication key (stored in Vault: `secret/namecheap/api-server`)
- `REGISTRANT_*` - Default registrant info for domain registration (ORGANIZATION, FIRST_NAME, LAST_NAME, ADDRESS1, ADDRESS2, CITY, STATE_PROVINCE, POSTAL_CODE, COUNTRY, PHONE, EMAIL)

### systemd Services

Located at `~/.config/systemd/user/`:
- `namecheap-api.service` - REST API server
- `namecheap-prices.service` + `namecheap-prices.timer` - Auto price updates (09:30, 12:30, 16:00)