domain-search-mcp 1.2.8 → 1.2.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +91 -0
- package/README.md +1541 -20
- package/package.json +1 -1
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
## Build & Development Commands
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm run build # Compile TypeScript to dist/
|
|
9
|
+
npm run dev # Watch mode with tsx
|
|
10
|
+
npm start # Run compiled server
|
|
11
|
+
npm test # Run all tests
|
|
12
|
+
npm run test:unit # Run unit tests only
|
|
13
|
+
npm run coverage # Run tests with coverage
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Run a single test file:
|
|
17
|
+
```bash
|
|
18
|
+
npx jest tests/unit/cache.test.ts
|
|
19
|
+
npx jest --testPathPattern="validators"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Architecture Overview
|
|
23
|
+
|
|
24
|
+
This is an MCP (Model Context Protocol) server for domain availability searches. It aggregates data from multiple registrars and fallback sources.
|
|
25
|
+
|
|
26
|
+
### Core Flow
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
server.ts (MCP Server)
|
|
30
|
+
↓
|
|
31
|
+
tools/*.ts (Tool definitions + executors)
|
|
32
|
+
↓
|
|
33
|
+
services/domain-search.ts (Orchestration layer)
|
|
34
|
+
↓
|
|
35
|
+
registrars/*.ts (API adapters) → Porkbun, Namecheap, GoDaddy
|
|
36
|
+
or
|
|
37
|
+
fallbacks/*.ts (RDAP, WHOIS)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Key Components
|
|
41
|
+
|
|
42
|
+
**Tools** (`src/tools/`): Each MCP tool has three exports:
|
|
43
|
+
- `*Tool`: Tool definition (name, description, schema)
|
|
44
|
+
- `*Schema`: Zod validation schema
|
|
45
|
+
- `execute*`: Execution function
|
|
46
|
+
|
|
47
|
+
**Registrar Adapters** (`src/registrars/`): All extend `RegistrarAdapter` base class which provides:
|
|
48
|
+
- Token bucket rate limiting
|
|
49
|
+
- Retry with exponential backoff
|
|
50
|
+
- Timeout handling
|
|
51
|
+
- Standardized `DomainResult` creation
|
|
52
|
+
|
|
53
|
+
**Domain Search Service** (`src/services/domain-search.ts`): Orchestrates source selection:
|
|
54
|
+
1. Porkbun API (if configured)
|
|
55
|
+
2. Namecheap API (if configured)
|
|
56
|
+
3. GoDaddy MCP (always available, no auth)
|
|
57
|
+
4. RDAP fallback
|
|
58
|
+
5. WHOIS last resort
|
|
59
|
+
|
|
60
|
+
**Utilities** (`src/utils/`):
|
|
61
|
+
- `cache.ts`: TTL-based in-memory cache
|
|
62
|
+
- `errors.ts`: Structured error types with retry hints
|
|
63
|
+
- `premium-analyzer.ts`: Domain quality scoring and premium detection
|
|
64
|
+
- `semantic-engine.ts`: AI-powered domain name generation
|
|
65
|
+
|
|
66
|
+
### Type System
|
|
67
|
+
|
|
68
|
+
Core types in `src/types.ts`:
|
|
69
|
+
- `DomainResult`: Complete domain availability/pricing info
|
|
70
|
+
- `SearchResponse`: Results + insights + next_steps
|
|
71
|
+
- `DataSource`: Enum of where data came from
|
|
72
|
+
- `Config`: Environment configuration shape
|
|
73
|
+
|
|
74
|
+
### Configuration
|
|
75
|
+
|
|
76
|
+
Server works without API keys (falls back to RDAP/WHOIS). For pricing data, configure in `.env`:
|
|
77
|
+
- `PORKBUN_API_KEY` + `PORKBUN_API_SECRET`: Fast with pricing
|
|
78
|
+
- `NAMECHEAP_API_KEY` + `NAMECHEAP_API_USER`: Requires IP whitelist
|
|
79
|
+
|
|
80
|
+
### Adding a New Tool
|
|
81
|
+
|
|
82
|
+
1. Create `src/tools/new_tool.ts` with schema, tool definition, and executor
|
|
83
|
+
2. Export from `src/tools/index.ts`
|
|
84
|
+
3. Add to `TOOLS` array and `executeToolCall` switch in `server.ts`
|
|
85
|
+
|
|
86
|
+
### Adding a New Registrar
|
|
87
|
+
|
|
88
|
+
1. Create `src/registrars/new_registrar.ts` extending `RegistrarAdapter`
|
|
89
|
+
2. Implement `search()`, `getTldInfo()`, `isEnabled()`
|
|
90
|
+
3. Export from `src/registrars/index.ts`
|
|
91
|
+
4. Add to source selection logic in `services/domain-search.ts`
|