Servidor MCP de Headless Domains

Servidor oficial del Protocolo de Contexto de Modelo (MCP) para Headless Domains. Este servidor expone las operaciones de la API de Headless Domains a clientes compatibles con MCP como Claude Desktop, Cursor y Windsurf.

Características

• search_domain: comprueba si un dominio está disponible

• lookup_whois: inspecciona una identidad registrada

• register_domain: registra un dominio con una clave API

• sync_bio: sincroniza el contenido de la biografía de un agente/perfil con una clave API

• Selección automática de transporte:

  • stdio para clientes MCP locales

  • sse cuando PORT está presente para despliegues alojados

Requisitos

• Python 3.10+

• Opcional: una clave API de Headless Domains para herramientas autenticadas

Configuración local

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

Variables de entorno

Ejecución local

Para un cliente MCP local, el servidor utiliza stdio por defecto:

python server.py

También puede ejecutarlo a través de la CLI de MCP:

mcp run server.py

Configuración de Claude Desktop

Añada una entrada de servidor a 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"
      }
    }
  }
}

Si aún no necesita herramientas autenticadas, puede omitir HEADLESSDOMAINS_API_KEY.

Modo SSE alojado

Cuando PORT está presente, server.py inicia un transporte SSE automáticamente:

PORT=8080 python server.py

Lanzamiento típico al estilo Railway:

HOST=0.0.0.0 PORT=8080 python server.py

Notas sobre las herramientas

register_domain

• Requiere HEADLESSDOMAINS_API_KEY

• Envía una carga útil base que contiene domain, namespace, years, agreed_to_terms (true) y payment_method ("gems")

• Acepta extra_payload_json para campos de la API que no están codificados en la herramienta

Ejemplo:

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

sync_bio

• Requiere HEADLESSDOMAINS_API_KEY

• Sincroniza con el endpoint /domains/<domain>/bio

• Envía domain, bio y bio_markdown

• Acepta extra_payload_json para cualquier campo adicional de la API (como name, x, github, etc.)

Ejemplo:

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

Docker

Construir:

docker build -t headlessdomains-mcp .

Ejecutar:

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

Pruebas de humo

Después de instalar las dependencias:

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

Notas

• /temp-specs se ignora en .gitignore para que los documentos de planificación local se mantengan fuera del control de versiones.