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 в рабочем каталоге). Агент не может их изменить.

Пользователю нужен только ключ (SGNL_CLIENT_ID и SGNL_CLIENT_SECRET), scope он не задаёт: сервер сам запрашивает права своего профиля.

Если в интеграции включены не все scope, сервер всё равно запускается, но без недостающих:

• операции, которым они нужны, отвечают ошибкой SCOPE_MISSING с готовым текстом для администратора, например: «У вашего ключа SIGNAL ограниченные права… Передайте администратору SIGNAL: „В интеграции (client_id …) включите scope: docs:issue:list“»;
• запрос в SIGNAL при этом не отправляется;
• инструмент get_access_status заранее показывает, чего не хватает;
• то же сообщение сервер пишет в свой журнал при запуске.

Сервер не запускается, только если ключ неверный или в интеграции нет ни одного scope профиля. Для write и workflow при запуске проверяется, что пользователь SGNL_MCP_ACTOR_USER_ID есть в компании. Если для этой проверки нет company:user:list, запись недоступна, а чтение работает.

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

Это раздел для администратора SIGNAL. Включите в интеграции эти scope, чтобы были доступны все инструменты профиля:

Список составляется автоматически из запросов, которые разрешены профилю. Тест сверяет его со спецификацией SIGNAL, поэтому лишнего сервер не запросит. Обратите внимание: нужен docs:issue:list, а не docs:issue:read.

Отправка передачи и запуск рассмотрения в 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.

Запуск в Docker

Готовый образ для linux/amd64 и linux/arm64 (в том числе Mac на Apple Silicon) публикуется в GitHub Container Registry:

docker pull ghcr.io/gritsyuk/sgnl-mcp:latest   # или конкретная версия, например :0.1.0
docker tag ghcr.io/gritsyuk/sgnl-mcp:latest sgnl-mcp

Для работы стоит закрепить версию (:0.1.0), а не latest: тогда образ не обновится без вашего ведома. Можно и собрать образ самостоятельно из корня репозитория (ему нужны оба пакета рабочего пространства):

docker build -f mcp/Dockerfile -t sgnl-mcp .

Сервер общается с клиентом через stdin/stdout, поэтому контейнер запускается с -i, а клиент сам стартует его на каждую сессию. Секреты удобно держать в env-файле, а не в конфигурации клиента. Например, ~/.sgnl-mcp.env:

SGNL_CLIENT_ID=…
SGNL_CLIENT_SECRET=…
SGNL_MCP_PROFILE=read

Claude Desktop — claude_desktop_config.json (пути — абсолютные):

{
  "mcpServers": {
    "sgnl": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--read-only", "--tmpfs", "/tmp",
        "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
        "--env-file", "/Users/me/.sgnl-mcp.env",
        "-v", "sgnl-mcp-data:/data",
        "sgnl-mcp"
      ]
    }
  }
}

Claude Code:

claude mcp add sgnl -- docker run -i --rm --init --read-only --tmpfs /tmp --cap-drop ALL \
  --security-opt no-new-privileges --env-file ~/.sgnl-mcp.env -v sgnl-mcp-data:/data sgnl-mcp

Windows. В конфигурации Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json) обратные слеши в путях удваиваются: "--env-file", "C:\\Users\\Admin\\.sgnl-mcp.env", а папка для загрузки подключается как "-v", "C:\\SIGNAL\\outgoing:/uploads:ro". В командной строке cmd вместо /dev/null используется NUL. Проверить, что образ запускается:

docker run -i --rm --init ghcr.io/gritsyuk/sgnl-mcp:0.1.0 < NUL

Без учётных данных сервер сразу завершится с ошибкой проверки настроек (не заданы SGNL_CLIENT_ID / SGNL_CLIENT_SECRET) — значит, образ рабочий.

Что внутри образа:

• Процесс работает от непривилегированного пользователя (uid 10001), зависимости зафиксированы uv.lock.
• /data — том для журнала аудита (audit.jsonl) и журнала выполненных операций (state.sqlite). Именованный том sgnl-mcp-data сохраняет их между запусками; без него защита от повторов и аудит теряются при каждом перезапуске.
• /uploads — каталог загрузки (SGNL_MCP_UPLOAD_ROOT уже указывает на него). Для профилей write/workflow смонтируйте туда папку с файлами только на чтение: -v /path/to/outgoing:/uploads:ro. Тогда агент физически не может ни изменить файлы на компьютере, ни прочитать что-то за пределами этой папки.
• Файл .env в образ не попадает (.dockerignore пропускает только исходники пакетов).

Флаги --read-only, --cap-drop ALL и no-new-privileges необязательны, но сервер с ними работает, и это ещё один рубеж: контейнер не может ничего записать, кроме /data и /tmp.

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

• Инструменты чтения можно разрешить без вопросов.
• Инструменты записи и 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": …}.