oitvoip-mcp

MCP-сервер для Oitvoip (хостинговая реселлерская платформа VoIP/UCaaS, построенная на NetSapiens — шаблон хоста API: {tenant-pbx-host}/ns-api/). Предоставляет методы доменов, реселлеров, устройств, абонентов и CDR из NetSapiens ns-api в виде MCP-инструментов.

Примечание о названии: собственная интеграция MSPbots зарегистрирована как «Oitvoip» (subjectCode=NS — сокращение от NetSapiens); базовый API и вся официальная документация ссылаются на «NetSapiens» / «ns-api». Этот MCP охватывает ровно те 5 методов, которые настроены у самого MSPbots.

Обзор

• Stateless HTTP-сервис. Учётные данные никогда не сохраняются — каждый запрос передаёт свои собственные учётные данные через заголовки, которые используются только на время выполнения этого одного запроса.

• Поддерживает конкурентные запросы; изоляция учётных данных для каждого запроса выполняется через Python contextvars, а не через глобальный/общий экземпляр клиента.

• Точки входа: POST /mcp (протокол MCP) и GET /health (проверка работоспособности).

• Порт по умолчанию: 8080 (настраивается через MCP_HTTP_PORT).

Related MCP server: whmcs-mcp-server

Аутентификация

NetSapiens использует стандартный OAuth2 password grant:

POST https://{site}/ns-api/oauth2/token/
  grant_type=password&client_id=...&client_secret=...&username=...&password=...
-> {"access_token": "...", "expires_in": 3600, "token_type": "Bearer", ...}

Полученный access_token действителен в течение 1 часа, но этот сервер заново аутентифицируется при каждом вызове инструмента, а не кэширует токен между MCP-запросами — ничего не кэшируется и не сохраняется. Каждый реальный вызов ns-api затем отправляет Authorization: Bearer <access_token>.

Параметры авторизации в заголовках

Отсутствие любого заголовка возвращает 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Oitvoip-Site, X-Oitvoip-Client-Id, X-Oitvoip-Client-Secret, X-Oitvoip-Username, X-Oitvoip-Password headers",
  "required_headers": ["X-Oitvoip-Site", "X-Oitvoip-Client-Id", "X-Oitvoip-Client-Secret", "X-Oitvoip-Username", "X-Oitvoip-Password"],
  "optional_headers": []
}

Недействительные учётные данные или аутентифицированная, но недостаточно привилегированная учётная запись абонента возвращается как обёртка ошибки unauthorized уровня инструмента (сообщение включает детали от самого вендора, например Invalid Scope [APP001]), а не как ошибка HTTP-уровня от этого сервера — см. «Известные ограничения».

Переменные окружения

Конечная точка MCP

• POST /mcp — протокол MCP (потоковый HTTP-транспорт)

• GET /health — проверка работоспособности, возвращает {"status": "ok"} (чисто локальная проверка, не вызывает API вендора)

Список инструментов

Ответы представляют собой JSON от вендора (массив или объект в зависимости от метода), сериализованный компактно (без отступов, ensure_ascii=False). Если ответ превышает ~20,000 символов, самое большое поле-список усекается, а результат включает truncated: true и исходное количество, вместо возврата неограниченного объёма данных. Все 5 инструментов доступны только для чтения (readOnlyHint) — в этом сервисе нет инструментов записи/удаления.

При ошибке инструменты возвращают структурированную JSON-обёртку ошибки вместо исключения:

{"error": {"code": "unauthorized", "message": "...", "retryable": false}}

code принимает одно из значений not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error; retryable указывает, может ли агент безопасно повторить попытку (true для rate_limited и upstream_error).

Примеры тестирования

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Oitvoip-Site: pbx.example.com" \
  -H "X-Oitvoip-Client-Id: 58900.mspbot" \
  -H "X-Oitvoip-Client-Secret: <your-client-secret>" \
  -H "X-Oitvoip-Username: 1000@example" \
  -H "X-Oitvoip-Password: <your-password>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "oitvoip_get_subscribers",
      "arguments": {"domain": "example.58900.service"}
    }
  }'

Проверено вживую (2026-07-30) на реальном арендаторе: все 5 инструментов вызваны в полном цикле через этот запущенный сервер: oitvoip_get_subscribers вернул реальные записи абонентов/внутренних номеров; oitvoip_get_devices вернул реальные зарегистрированные SIP-устройства (терминалы Polycom, актуальное состояние регистрации); oitvoip_get_cdr2 вернул реальные детализированные записи звонков за указанный диапазон дат. oitvoip_get_domains и oitvoip_get_resellers корректно обратились к API и вернули чистую ожидаемую ошибку уровня инструмента 401 Invalid Scope [APP001] — предоставленные тестовые учётные данные являются учётной записью уровня абонента (scope: "Office Manager"), которая не имеет прав администратора доменов/реселлеров в данном развёртывании NetSapiens; см. «Известные ограничения».

Справочник по API

• Публичный, без входа: https://api.ucaasnetwork.com/ns-api/apidoc/ (полный справочник ns-api, включая объекты OAuth2, Domain, Reseller, Device, Subscriber и CDR)

Известные ограничения

• Охват — ровно 5 настроенных конечных точек MSPbots, а не полная поверхность API вендора — ns-api также покрывает Callqueue, Agent, Phonenumber, Dialplan, Contacts, Presence, Call Queue Report/Stat, управление звонками в реальном времени и другое (согласно списку объектов в публичной документации); всё это выходит за рамки данного сервиса.

• oitvoip_get_domains и oitvoip_get_resellers не удалось полностью проверить вживую на реальных данных — предоставленная тестовая учётная запись успешно проходит аутентификацию (что доказывает корректность потока OAuth2 и данной реализации), но имеет роль «Office Manager» уровня абонента, которую NetSapiens отклоняет для этих двух объектов административного уровня с ошибкой 401 Invalid Scope [APP001]. Это ограничение привилегий конкретной тестовой учётной записи, а не ошибка данного сервера — oitvoip_get_subscribers, oitvoip_get_devices и oitvoip_get_cdr2 успешно работали с реальными данными, используя тот же самый access token от того же самого входа.

• Поля диапазона дат CDR (start_date/end_date) — строки без валидации — передаются вендору как есть в формате YYYY-MM-DD HH:MM:SS, что соответствует собственному сохранённому использованию MSPbots; разбор дат на стороне клиента не выполняется.