delinea-mcp Server

официальный

Официальный Del

GitHub
46

Документация

DelineaMCP

MCP-сервер для API Delinea Secret Server и платформы

License

Возможности

  • Автоматическая аутентификация в Secret Server
  • Обширный набор инструментов Secret Server для управления папками, секретами, пользователями, группами и ролями. Включает помощники для входящих сообщений и запросов доступа, а также утилиты для агентов кодирования.
  • Инструменты совместимости с ChatGPT (search и fetch) для контролируемого взаимодействия с ИИ.
  • Опциональные инструменты управления пользователями платформы Delinea
  • Поддержка режимов передачи Server Sent Events или STDIO
  • OAuth 2.0 с динамической регистрацией клиентов согласно спецификации MCP
  • Поддержка TLS для безопасных соединений
  • Готовый к запуску образ Docker и точка входа для сервера разработки
  • Протестировано с ChatGPT, Claude Desktop, удалённым коннектором Claude, VSCode Copilot и openwebui

Установка

[!NOTE]

В этом проекте используется uv (https://github.com/astral-sh/uv), но если вы предпочитаете выполнять команды без него, вы можете использовать команды pip и venv как обычно.

  • Установите Uv
  • Инициализируйте проект: uv pip sync requirements.txt
  • Используйте uv run server.py --config config.json

Конфигурация

Секреты, такие как пароли, по-прежнему берутся из переменных окружения. Укажите DELINEA_PASSWORD в вашем shell-окружении. Опциональные функции зависят от дополнительных переменных, таких как AZURE_OPENAI_KEY или PLATFORM_SERVICE_PASSWORD.

Несекретные параметры указываются в config.json:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Для Secret Server Cloud просто используйте облачный URL без /SecretServer. Укажите ssl_keyfile и ssl_certfile для включения HTTPS. Для Let's Encrypt используйте файлы privkey.pem и fullchain.pem.

Файл конфигурации поддерживает следующие ключи:

  • delinea_username - Имя пользователя Secret Server. Должен быть программным пользователем с правами на выполнение нужных вам задач.
  • delinea_base_url - Базовый URL вашего экземпляра Secret Server.
  • platform_hostname - Имя хоста арендатора платформы (включает инструменты платформы).
  • platform_service_account - Сервисная учётная запись для API платформы.
  • platform_tenant_id - ID арендатора для запросов к API платформы.
  • azure_openai_endpoint - Конечная точка Azure OpenAI. Только если вам нужна автоматическая генерация отчётов (большинство агентов могут генерировать собственный SQL для отчётов, поэтому не включайте, если нет необходимости).
  • azure_openai_deployment - Имя развёртывания Azure OpenAI.
  • auth_mode - Режим аутентификации (none или oauth). OAuth, очевидно, не работает с транспортом stdio.
  • transport_mode - stdio для командной строки или sse для HTTP/SSE.
  • chatgpt_disable_scope_checks - Пропустить проверку области действия для запросов ChatGPT. Включайте только при проблемах с подключением к ChatGPT.
  • port - Порт для HTTP-сервера в режиме sse.
  • debug - Включить подробное логирование.
  • external_hostname - Имя хоста, используемое при формировании аудитории токенов OAuth. Не добавляйте префикс HTTP(S) или порт.
  • ssl_keyfile - Путь к ключу SSL для HTTPS. (например, privkey.pem)
  • ssl_certfile - Путь к сертификату SSL для HTTPS. (например, fullchain.pem)
  • registration_psk - Предварительный ключ, необходимый для регистрации клиентов OAuth. Вам нужно будет ввести этот секрет в браузере для подтверждения подключений OAuth.
  • jwt_key_path - Расположение пары ключей RSA, используемой для токенов OAuth. По умолчанию .cache/jwt.json. Автоматически генерируется, если не существует.
  • oauth_db_path - Путь к файлу базы данных OAuth. По умолчанию .cache/oauth.db. Автоматически генерируется, если не существует.
  • enabled_tools - Список имён инструментов для регистрации. Пустой список включает все инструменты. Настоятельно рекомендуется включать инструменты выборочно для каждого случая использования или задачи. См. папку docs/ для примеров.
  • search_objects - Разрешённые типы объектов для инструмента search. По умолчанию ["secret"], но может включать user, folder, group и role.
  • fetch_objects - Разрешённые типы объектов для инструмента fetch. По умолчанию ["secret"], но может включать те же значения, что и search_objects.

Запуск сервера

Запустите сервер локально в режиме разработки:

python server.py

При запуске сервер запрашивает токен-носитель и сохраняет его для последующих запросов к API. В будущем проект будет расширен для более глубокой интеграции с API Secret Server.

Инструменты MCP

Сервер предоставляет несколько инструментов MCP для взаимодействия с Secret Server:

  • run_report(sql_query, report_name=None) - создать и выполнить временный отчёт.
  • ai_generate_and_run_report(description) - сгенерировать SQL с помощью Azure OpenAI и выполнить его. Требует переменных Azure OpenAI.
  • list_example_reports() - вывести список примеров запросов и информацию о таблицах.
  • get_secret(id, summary=False) - получить секрет или сводную информацию.
  • get_folder(id) - получить метаданные папки и дочерние элементы.
  • search_users(query) - поиск активных пользователей.
  • search_secrets(query, lookup=False) - поиск или просмотр секретов.
  • search_folders(query, lookup=False) - поиск или просмотр папок.
  • get_secret_environment_variable(secret_id, environment) - вывести скрипт для получения учётных данных секрета в указанной оболочке.
  • check_secret_template(template_id) - получить детали шаблона секрета.
  • check_secret_template_field(template_id, field_id) - проверить, содержит ли шаблон поле.
  • get_secret_template_field(field_id) - получить сведения о конкретном поле шаблона секрета по ID.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - одобрить или отклонить запрос доступа.
  • get_pending_access_requests() - вывести список ожидающих запросов доступа.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - получить сообщения из входящих.
  • mark_inbox_messages_read(message_ids, read=True) - отметить сообщения как прочитанные или непрочитанные.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - унифицированные операции с пользователями. action принимает get, create, update, delete, list_sessions, reset_2fa, reset_password или lock_out. Укажите user_id при необходимости и передайте тело запроса через data для действий создания, обновления и сброса пароля. Пример: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - управление ролями. action может быть list, get, create или update. Передайте необязательные параметры запроса с помощью params при перечислении ролей. Пример: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - назначить или удалить роли у пользователя. action — это get, add или remove, а role_ids — список идентификаторов ролей для операций добавления/удаления.
  • group_management(action, group_id=None, data=None, params=None) - работа с группами. action может быть get, list, create или delete. Укажите group_id для получения/удаления и data при создании группы.
  • folder_management(action, folder_id=None, data=None, params=None) - управление папками. action может быть get, list, create, update или delete. Укажите folder_id для получения, обновления или удаления и передайте data при создании или обновлении папки.
  • user_group_management(action, user_id, group_ids=None) - управление членством пользователя в группах. action — это get, add или remove. Передайте список group_ids при добавлении или удалении членства.
  • group_role_management(action, group_id, role_ids=None) - управление ролями в группе. Используйте действия list, add или remove. Укажите role_ids при добавлении или удалении.
  • health_check() - запросить конечную точку проверки работоспособности Secret Server и вернуть текущий статус службы.

Используйте переменные конфигурации сервера, описанные выше, для аутентификации. Инструмент ИИ автоматически отключается, если отсутствуют переменные Azure OpenAI. Будут зарегистрированы только имена инструментов, перечисленные в config.json. Пустой список включает все инструменты.

Варианты использования

Документация охватывает несколько рабочих процессов подключения инструментов к серверу:

Быстрый старт с Docker

Предоставлен Dockerfile для запуска MCP-сервера без локальной установки зависимостей Python.

  1. Соберите образ:
docker build -t dev.local/delinea-mcp:latest .
  1. Запустите сервер (передайте свои учётные данные через переменные окружения):
docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

Заполните config.json вашими именами пользователей и URL, как показано выше.

Контейнер хранит oauth.db и jwt.json в /app/data. Смонтируйте том (показан как mcp-data выше), чтобы эти файлы и любые HTTPS-сертификаты сохранялись между запусками.

Замените <https://your-secret-server/SecretServer> на базовый URL вашего экземпляра Secret Server, чтобы избежать ошибок подключения.

Сервер запустится на порту 8000 по умолчанию, используя python server.py. Установите параметр port в config.json, чтобы переопределить значение по умолчанию. Включите debug: true для логирования всех входящих HTTP-запросов.

Примеры скриптов

Скрипт manual_secret_request.py показывает, как получить токен OAuth для конкретного ID секрета:

python scripts/manual_secret_request.py <Secret_ID>

Перед запуском скрипта установите переменные окружения SECRET_USERNAME_<id> и SECRET_PASSWORD_<id> для секрета. При необходимости установите DELINEA_BASE_URL, чтобы переопределить значение по умолчанию https://localhost/SecretServer.

Запуск тестов

Запустите модульные тесты с покрытием, чтобы обеспечить 100% покрытие кода:

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Живое тестирование

Некоторые интеграционные тесты требуют действительных учётных данных. Установите следующие переменные окружения и необязательную LIVE_SECRET_ID перед запуском набора:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

Когда эти переменные присутствуют, живые тесты будут выполнять реальные запросы к API.

Развёртывание в production

Зависимости зафиксированы в requirements.txt, а релизы помечаются с использованием Семантического версионирования. Соберите образ Docker из помеченного коммита и разверните его в вашем production-окружении, передав необходимые переменные окружения (DELINEA_USERNAME, DELINEA_PASSWORD, опционально DELINEA_BASE_URL). Опциональные функции зависят от дополнительных переменных:

  • PLATFORM_SERVICE_PASSWORD вместе с PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT и PLATFORM_TENANT_ID включает инструменты управления пользователями.
  • AZURE_OPENAI_KEY вместе с AZURE_OPENAI_ENDPOINT и AZURE_OPENAI_DEPLOYMENT включает помощник генерации отчётов ИИ.

При работе с OAuth или транспортом SSE вам может потребоваться указать registration_psk и настроить external_hostname или файлы HTTPS-сертификатов.

Структура репозитория

  • delinea_mcp/ - пакет, содержащий инструменты MCP.
  • server.py - тонкая точка входа, которая регистрирует всё на MCP-сервере.
  • docs/ - документация проекта и сгенерированный delinea-secret-server-openapi-spec.json.
  • scripts/ - вспомогательные примеры, включая manual_secret_request.py.

Вопросы безопасности

Включённые конечные точки OAuth предназначены для разработки и тестирования. Маршрут /oauth/authorize принимает любой redirect_uri и перенаправляет пользователя без проверки. При развёртывании необходимо ограничить это значение одобренными URL обратного вызова; в противном случае злоумышленники могут передать вредоносный URL и перехватить коды авторизации. См. Открытое перенаправление для справки.

Примечания к выпуску

См. docs/release_notes.md для сводки последних функций и пунктов дорожной карты.

Дорожная карта

  1. Сквозная аутентификация
  2. Поддержка потоковой передачи HTTP
  3. Расширение охвата инструментов на платформе Delinea и добавление других продуктов Delinea

Участие в разработке

Приветствуется участие в разработке! Пожалуйста, открывайте issues или pull requests для любых улучшений. Весь новый код должен включать модульные тесты и проходить существующий набор тестов.

Лицензия

Этот проект лицензирован под MIT License.