SIGNAL API

Официальная документация API: swagger, OpenAPI-схема.

Два пакета в одном репозитории

sgnl-mcp построен поверх sgnl-api и зависит от него; sgnl-api ничего не знает про MCP и не тянет его зависимости. Пакеты выпускаются на PyPI независимо. Настройка MCP-сервера, подключение к Claude и запуск в Docker — в mcp/README.md.

sgnl-api — обёртка над API

Установка

pip install -U sgnl-api

Пример

import asyncio
import os
from sgnl_api import DocsApi
from dotenv import load_dotenv

load_dotenv()
CLIENT_ID = os.getenv("CLIENT_ID")
SECRET_ID = os.getenv("SECRET_ID")


async def main():

    async with await DocsApi.create(
        client_id=CLIENT_ID,
        client_secret=SECRET_ID,
        scopes=["project:list"],  # ровно те scope, что включены в интеграции
    ) as docs:
        projects = await docs.project.get_list()
        for project in projects:
            print(project)


if __name__ == "__main__":
    asyncio.run(main())

Клиент можно использовать и без async with — тогда после завершения работы стоит вызвать await docs.aclose(), чтобы закрыть пул соединений.

Scopes

scopes — обязательный параметр: список прав, с которыми запрашивается токен. Он должен совпадать с галочками в интеграции SIGNAL («Редактировать интеграцию»):

• если в списке есть scope, которого нет в интеграции, SIGNAL не выдаёт токен и не говорит, какого именно не хватает. Клиент выясняет это сам (несколько пробных запросов токена на половинах списка) и бросает SgnlScopeError с текстом not enabled for the integration: docs:issue:list и полем missing_scopes; scope без лицензии попадают в unlicensed_scopes;
• лишние галочки в интеграции не мешают: запрашивать можно любое подмножество;
• какой scope нужен методу, написано в его описании (Required scopes: project:list) и в спецификации API.

# только чтение проектов и папок
scopes = ["project:list", "project:read", "docs:folder:list", "docs:item:list"]

Запрашивайте только то, что нужно скрипту: токен без *:create, *:update и *:delete ничего не изменит в SIGNAL, даже если в коде ошибка.

Почему SIGNAL не выдал токен, видно по классу исключения: SgnlScopeError — запрошен scope, которого нет в интеграции; SgnlCredentialError — неверный client_id или client_secret (после «Обновить ключ доступа» старый secret не работает); SgnlLicenseError — у компании нет лицензии на модуль одного из scope.

Обработка ошибок

При ошибке API методы бросают исключение, а не возвращают dict с ключом error — проверять каждый ответ вручную не нужно.

from sgnl_api import DocsApi, SgnlApiError, SgnlNotFoundError

try:
    project = await docs.project.info(project_id)
except SgnlNotFoundError:
    ...
except SgnlApiError as e:
    print(e.status_code, e.message)

Иерархия исключений: SgnlApiError (базовое) → SgnlRequestError (сетевые ошибки/таймауты), SgnlAuthenticationError (401 и отказ в токене; подклассы SgnlScopeError, SgnlCredentialError, SgnlLicenseError), SgnlBadRequestError (400), SgnlForbiddenError (403), SgnlNotFoundError (404), SgnlQuotaExceededError (450), SgnlRateLimitError (429), SgnlServerError (5xx).

Лимиты запросов (429)

API ограничивает частоту запросов (около 10 запросов в секунду на client_id, 50 с пополнением 4 в секунду на компанию). При ответе 429 клиент сам ждёт интервал из заголовка Retry-After (не больше 30 с за раз) и повторяет запрос — по умолчанию до 3 раз. Если лимит не отпустил, бросается SgnlRateLimitError с полем retry_after.

api = await DocsApi.create(client_id=..., client_secret=..., scopes=[...], max_retries=5)  # 0 — отключить повторы

Если токен отозван раньше срока, на ответ 401 клиент один раз получает новый токен и повторяет запрос.

Загрузка файла

Документ из локального файла создаётся в три шага. Файл передаётся в хранилище потоком, поэтому большие файлы (API допускает до 5 ГиБ) не загружаются в память целиком.

uploaded = await docs.file.upload(project_id, "drawings/A-101.pdf")      # {"object_id", "mime_type", "size"}
version_id = await docs.version.create(object_id=uploaded["object_id"], project_id=project_id, name="A-101.pdf")
item_id = await docs.item.create_file("A-101.pdf", folder_id, version_id)  # новый документ
# или новая версия существующего документа:
await docs.item.add_version(item_id, version_id)

Свой HTTP-клиент

В DocsApi.create можно передать свой httpx.AsyncClient — например, с транспортом, который фильтрует или ограничивает запросы (так устроен sgnl-mcp). Такой клиент aclose() не закрывает: его закрывает владелец.

async with httpx.AsyncClient(transport=my_transport, timeout=30) as http:
    docs = await DocsApi.create(client_id=..., client_secret=..., scopes=[...], http_client=http)

Проверка покрытия API

Скрипт сравнивает спецификацию с методами обёртки и показывает новые, удалённые и изменённые эндпоинты:

uv run scripts/check_api_coverage.py                       # скачать спецификацию с api.sgnl.pro
uv run scripts/check_api_coverage.py openapi/schema.yml    # или сохранённую копию из репозитория

Код возврата 1 означает, что обёртка вызывает эндпоинт, которого больше нет, или не передаёт обязательное поле. Копия спецификации в openapi/schema.yml используется и тестами sgnl-mcp: при обновлении API её нужно заменить.

Разработка

Репозиторий — uv workspace из двух пакетов (sgnl-api в корне и sgnl-mcp в mcp/):

uv sync --all-packages                     # оба пакета и dev-зависимости
uv run pytest                              # тесты SDK
uv run --package sgnl-mcp pytest mcp/tests # тесты MCP-сервера
uv build --all-packages                    # sdist и wheel обоих пакетов в dist/
docker build -f mcp/Dockerfile -t sgnl-mcp . # образ MCP-сервера

Методы

Обертка покрывает весь официальный API (swagger). Методы сгруппированы по ресурсам ровно как в спецификации (по тегам).

item

folder

project / project_user / project_user_custom_role

company / company_user / company_user_custom_role

version

file (Object)

attribute / attribute_type / attribute_value

issue и связанные (issue_type, issue_accesses, issue_comment, issue_attachment, issue_events, issue_project_settings)

review и связанные (review_group, review_item, review_type, review_process)

share / storage

подписание (cades_signature, embedded_signature, mchd) и card_public_link

documents_transfer / documents_transfer_item / documents_transfer_type / documents_transfer_acceptance / acceptance_certificate

permissions / application_user

forge / tangl / folder_items_naming_pattern

формы (project_form, project_form_type, project_form_field_type, form_type, form_type_group, form_field_type)

дашборды (board, card, card_group)

бронирования и слоты (booking, slot)

user_log

Для методов, принимающих filter/find/values/items как dict, структура соответствует одноимённой схеме в спецификации API — ключи передаются в camelCase, как в JSON-теле запроса (например {"projectId": "...", "issueIds": [...]}).