Hhexwave MCP

Wiki / 30

Публикация сервера

Подтверждение пространства имён (namespace), публикация версии и модерация.

1. Регистрация автора

Отправьте POST /api/v1/authors/register с email и display_name. Ответ единственный раз возвращает ключ программного интерфейса hwh_.... Сохраните его в защищённом хранилище секретов: реестр сохраняет только HMAC-хеш ключа.

2. Подтверждение пространства имён через DNS TXT

Пространство имён (namespace) всегда выводится из подтверждаемого домена в обратном порядке:

Домен Разрешённое пространство имён
example.ru ru.example
mcp.example.ru ru.example.mcp
hexwave.ru ru.hexwave

Создайте проверку:

curl -X POST https://mcp.hexwave.ru/api/v1/namespaces \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"prefix":"ru.example","domain":"example.ru"}'

Ответ содержит record_name и одноразовое record_value. В DNS-панели домена создайте запись:

  • тип: TXT;
  • имя или хост: значение record_name (часто DNS-панель ожидает только относительную часть _hexwave-mcp-verification);
  • значение: record_value без изменений;
  • время жизни (TTL): 300–3600 секунд.

После распространения DNS выполните POST /api/v1/namespaces/{prefix}/verify с тем же X-API-Key.

3. Первая публикация

Полное имя сервера соответствует официальному реестру MCP (MCP Registry): namespace/server-name. Например, подтверждённое пространство имён ru.example может публиковать ru.example/weather.

curl -X POST https://mcp.hexwave.ru/api/v1/servers \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "name":"ru.example/weather",
    "display_name":"Пример сервера погоды",
    "description":"Текущая погода и краткосрочный прогноз для российских городов.",
    "endpoint":"https://mcp.example.ru/mcp",
    "version":"1.0.0",
    "tags":["погода","россия"]
  }'

Адрес сервера (endpoint) должен быть HTTPS-адресом без логина, пароля и частного IP-адреса. Новая публикация получает состояние pending_verification («ожидает проверки»): она ещё не видна в публичном каталоге и никогда не получает автоматически доступ через шлюз (Gateway).

4. Новая версия

Нельзя изменить адрес или манифест активной версии. Для обновления создайте новую версию и кандидатный адрес:

curl -X POST https://mcp.hexwave.ru/api/v1/servers/SERVER_ID/releases \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "version":"1.1.0",
    "endpoint":"https://mcp.example.ru/mcp",
    "description":"Обновлённое описание сервера.",
    "tags":["погода","россия"]
  }'

Версия проходит состояния pending_verification («ожидает проверки») → pending_review («ожидает модерации») → active («активна»). До ручного утверждения текущая активная версия и адрес не меняются. После утверждения реестр атомарно переключает текущую версию и адрес, а предыдущий адрес сохраняет с отметкой replaced («заменён») для аудита.

Используйте GET /api/v1/servers/mine/{server_id} для просмотра версии, работоспособности, хеша снимка возможностей и следующего действия.

5. Снятие с публикации

Чтобы скрыть сервер из поиска и публичного каталога, не удаляя исторические данные, вызовите:

curl -X POST https://mcp.hexwave.ru/api/v1/servers/SERVER_ID/withdraw \
  -H 'X-API-Key: YOUR_API_KEY'

Состояния

  1. pending_verification — адрес ожидает безопасной проверки фоновым обработчиком.
  2. pending_review — адрес и снимок возможностей получены, версия ожидает модерации.
  3. active — текущая версия видна в /v0.1/servers.
  4. rejected — версия не прошла модерацию.
  5. withdrawn — сервер скрыт из поиска, а исторические записи о версиях сохраняются для аудита.

Право использования через шлюз (Gateway) определяется отдельным будущим процессом. Состояние active само по себе не даёт права вызывать сервер через шлюз.