Headless Domains MCP 서버

Headless Domains를 위한 공식 MCP(Model Context Protocol) 서버입니다. 이 서버는 Claude Desktop, Cursor, Windsurf와 같은 MCP 호환 클라이언트에 Headless Domains API 작업을 노출합니다.

기능

search_domain: 도메인 사용 가능 여부 확인
lookup_whois: 등록된 ID 정보 조회
register_domain: API 키를 사용하여 도메인 등록
sync_bio: API 키를 사용하여 에이전트/프로필 바이오 콘텐츠 동기화
자동 전송 방식 선택:
- 로컬 MCP 클라이언트를 위한 stdio
- 호스팅 배포 시 PORT가 존재할 경우 sse

요구 사항

Python 3.10 이상
선택 사항: 인증된 도구를 사용하기 위한 Headless Domains API 키

로컬 설정

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

환경 변수

변수	필수 여부	기본값	용도
`HEADLESSDOMAINS_API_KEY`	아니요	설정 안 됨	인증된 엔드포인트에 `X-API-Key` 전송
`HEADLESSDOMAINS_API_BASE_URL`	아니요	`https://headlessdomains.com/api/v1`	API 기본 URL 재정의
`HEADLESSDOMAINS_TIMEOUT`	아니요	`20`	HTTP 타임아웃(초)
`HEADLESSDOMAINS_REGISTER_PATH`	아니요	`/domains/register`	API 변경 시 등록 엔드포인트 경로 재정의
`HEADLESSDOMAINS_SYNC_BIO_PATH`	아니요	`/domains/{domain}/bio`	API 변경 시 바이오 동기화 엔드포인트 경로 재정의
`MCP_TRANSPORT`	아니요	자동	`stdio` 또는 `sse`와 같은 전송 방식 강제 지정
`HOST`	아니요	`0.0.0.0`	SSE 모드용 바인드 호스트
`PORT`	아니요	설정 안 됨	값이 존재하면 서버를 `sse` 모드로 시작

로컬 실행

로컬 MCP 클라이언트의 경우, 서버는 기본적으로 stdio를 사용합니다:

python server.py

MCP CLI를 통해서도 실행할 수 있습니다:

mcp run server.py

Claude Desktop 설정

claude_desktop_config.json에 서버 항목을 추가하세요:

{
  "mcpServers": {
    "headlessdomains": {
      "command": "mcp",
      "args": [
        "run",
        "/absolute/path/to/headlessdomains-mcp/server.py"
      ],
      "env": {
        "HEADLESSDOMAINS_API_KEY": "your-api-key-here"
      }
    }
  }
}

아직 인증된 도구가 필요하지 않다면 HEADLESSDOMAINS_API_KEY는 생략할 수 있습니다.

호스팅 SSE 모드

PORT가 존재하면 server.py가 자동으로 SSE 전송을 시작합니다:

PORT=8080 python server.py

일반적인 Railway 스타일 실행:

HOST=0.0.0.0 PORT=8080 python server.py

도구 참고 사항

`register_domain`

HEADLESSDOMAINS_API_KEY 필요
domain, namespace, years, agreed_to_terms (true), payment_method ("gems")를 포함하는 기본 페이로드 전송
도구에 하드코딩되지 않은 API 필드를 위해 extra_payload_json 허용

예시:

{
  "domain": "myagent.agent",
  "years": 1,
  "extra_payload_json": "{\"owner_email\":\"me@example.com\"}"
}

`sync_bio`

HEADLESSDOMAINS_API_KEY 필요
/domains/<domain>/bio 엔드포인트로 동기화
domain, bio, bio_markdown 전송
추가 API 필드(name, x, github 등)를 위해 extra_payload_json 허용

예시:

{
  "domain": "myagent.agent",
  "bio_markdown": "# About Me",
  "extra_payload_json": "{\"name\":\"My Agent Name\", \"x\":\"twitter_handle\"}"
}

Docker

빌드:

docker build -t headlessdomains-mcp .

실행:

docker run --rm -p 8080:8080 \
  -e PORT=8080 \
  -e HEADLESSDOMAINS_API_KEY=your-api-key-here \
  headlessdomains-mcp

스모크 테스트

의존성 설치 후:

python -m py_compile server.py
python - <<'PY'
import server
print(server.search_domain("example.agent"))
print(server.lookup_whois("test.agent"))
PY

참고 사항

/temp-specs는 .gitignore에 포함되어 있어 로컬 계획 문서가 버전 관리 시스템에 포함되지 않습니다.

Headless Domains MCP Server