sgnl-mcp — MCP-сервер для SIGNAL Integration API

MCP-сервер, через который LLM-агент (Claude и др.) работает с документацией в SIGNAL: смотрит проекты и папки, ищет и скачивает документы, загружает новые документы и версии, работает с замечаниями, передачами и рассмотрениями.

Агент остаётся под контролем: чтение без ограничений, запись — только после предпросмотра и согласия пользователя, отправка передач и запуск рассмотрений — только после подтверждения пользователем в диалоге. Удалять, перемещать и переименовывать документы и папки, а также менять права агент не может вообще.

Построен на sgnl-api — обёртке над API из этого же репозитория.

Как обеспечивается контроль

Нагрузка на SIGNAL ограничена: по умолчанию не больше 3 запросов в секунду и 4 параллельных на весь сервер, у каждого вызова инструмента свой бюджет запросов, справочники кэшируются на 5 минут.

Установка

uvx sgnl-mcp          # запуск без установки
# или
pip install sgnl-mcp

Нужен Python 3.11+.

Настройка

Вся настройка — через переменные окружения (или файл .env в рабочем каталоге). Агент не может их изменить.

При запуске сервер получает токен и проверяет, что интеграции выданы все права профиля, а для write/workflow — что пользователь SGNL_MCP_ACTOR_USER_ID есть в компании. Если что-то не так, сервер не запускается и пишет, чего не хватает.

Права интеграции по профилям

Отправка передачи и запуск рассмотрения в SIGNAL используют те же права, что и их наполнение. Поэтому их отделяет сам MCP-сервер: в профиле write этих инструментов нет, а в workflow они всегда требуют подтверждения пользователя.

Подключение к Claude

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "sgnl": {
      "command": "uvx",
      "args": ["sgnl-mcp"],
      "env": {
        "SGNL_CLIENT_ID": "…",
        "SGNL_CLIENT_SECRET": "…",
        "SGNL_MCP_PROFILE": "read"
      }
    }
  }
}

Claude Code:

claude mcp add sgnl -e SGNL_CLIENT_ID=… -e SGNL_CLIENT_SECRET=… -e SGNL_MCP_PROFILE=read -- uvx sgnl-mcp

Для профиля write добавьте SGNL_MCP_ACTOR_USER_ID и SGNL_MCP_UPLOAD_ROOT.

Разрешения в клиенте

• Инструменты чтения можно разрешить без вопросов.
• Инструменты записи и Workflow не добавляйте в «разрешить всегда»: клиент должен спрашивать перед каждым вызовом. Это один из рубежей контроля.
• Для профиля workflow клиент должен поддерживать MCP elicitation (диалог подтверждения). Без неё отправка передач и запуск рассмотрений завершаются ошибкой и ничего не делают.

Инструменты

Как проходит запись

1. Агент вызывает инструмент без confirmation_token. Сервер проверяет объекты и возвращает предпросмотр («было → станет», путь папки, состав передачи и т.п.) и токен. В SIGNAL ничего не меняется.
2. Агент показывает предпросмотр пользователю.
3. После согласия агент вызывает инструмент с теми же аргументами и токеном. Сервер перепроверяет объекты: если с момента предпросмотра что-то изменилось (другой файл, кто-то правил замечание), токен отклоняется.

Токен одноразовый, действует 5 минут и привязан к аргументам. Повторный вызов с уже использованным токеном возвращает сохранённый результат, а не выполняет операцию второй раз.

Если запрос на запись завершился без ясного ответа (таймаут, ошибка сервера), сервер не повторяет его сам, а возвращает OUTCOME_UNKNOWN с тем, что удалось выяснить. Для загрузки файла можно завершить операцию параметром resume_version_id, не загружая файл заново.

Ограничения

• В API SIGNAL нет поиска передач по документу, поэтому блок transfers в get_document_context всегда not_supported.
• Создание замечаний, удаление, перемещение, переименование, изменение прав и пользователей в MCP-сервер намеренно не включены.

Ответы и ошибки

Все инструменты возвращают {"success": true, "data": …, "page": …, "warnings": […], "request_id": …} или {"success": false, "error": {"code", "message", "details"}, "request_id": …}.