Headless Domains MCPサーバー

Headless Domains用の公式Model Context Protocol (MCP) サーバーです。このサーバーは、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

環境変数

ローカルでの実行

ローカル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 で無視されるため、ローカルの計画ドキュメントはバージョン管理から除外されます。