delinea-mcp Server

oficial

Official Delinea MCP server for the Delinea Secret Server and Platform APIs

GitHub
46

Documentación

DelineaMCP

Servidor MCP para las API de Delinea Secret Server y Platform

License

Características

  • Autenticación automática contra Secret Server
  • Amplio conjunto de herramientas de Secret Server para gestionar carpetas, secretos, usuarios, grupos y roles. Incluye ayudantes de bandeja de entrada y solicitudes de acceso, y utilidades para agentes de codificación.
  • Herramientas de compatibilidad con ChatGPT (search y fetch) para interacciones controladas con IA.
  • Herramientas opcionales de gestión de usuarios de Delinea Platform
  • Soporta modos de transporte Server Sent Events o STDIO
  • OAuth 2.0 con registro dinámico de clientes según la especificación MCP
  • Soporte TLS para conexiones seguras
  • Imagen Docker lista para ejecutar y punto de entrada de servidor de desarrollo
  • Probado con ChatGPT, Claude Desktop, conector remoto de Claude, VSCode Copilot y openwebui

Instalación

[!NOTE]

Este proyecto usa uv (https://github.com/astral-sh/uv), pero si prefieres ejecutar comandos sin esto, puedes usar los comandos pip y venv como de costumbre si lo deseas.

  • Instalar Uv
  • Inicializar proyecto: uv pip sync requirements.txt
  • Usar uv run server.py --config config.json

Configuración

Los secretos como contraseñas siguen proviniendo de variables de entorno. Proporciona DELINEA_PASSWORD en tu entorno de shell. Las características opcionales dependen de variables adicionales como AZURE_OPENAI_KEY o PLATFORM_SERVICE_PASSWORD.

Los parámetros no secretos pertenecen a 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": []
}

Para Secret Server Cloud simplemente usa la URL de la nube sin /SecretServer. Especifica ssl_keyfile y ssl_certfile para habilitar HTTPS. Para Let's Encrypt, usa los archivos privkey.pem y fullchain.pem.

El archivo de configuración soporta las siguientes claves:

  • delinea_username - Nombre de usuario de Secret Server. Debe ser un usuario programático con permiso para realizar las tareas que desees.
  • delinea_base_url - URL base de tu instancia de Secret Server.
  • platform_hostname - Nombre de host del tenant de Platform (habilita las herramientas de Platform).
  • platform_service_account - Cuenta de servicio usada con la API de Platform.
  • platform_tenant_id - ID de tenant para las solicitudes a la API de Platform.
  • azure_openai_endpoint - Endpoint de Azure OpenAI. Solo si deseas la generación automática de informes (la mayoría de los agentes pueden generar su propio SQL de informe, así que no lo habilites a menos que lo necesites).
  • azure_openai_deployment - Nombre de despliegue para Azure OpenAI.
  • auth_mode - Modo de autenticación (none o oauth). OAuth obviamente no funciona con transporte stdio.
  • transport_mode - stdio para línea de comandos o sse para HTTP/SSE.
  • chatgpt_disable_scope_checks - Omitir validación de alcance en solicitudes de ChatGPT. Habilítalo solo si encuentras problemas al conectarte a ChatGPT.
  • port - Puerto para el servidor HTTP en modo sse.
  • debug - Habilitar registro detallado.
  • external_hostname - Nombre de host usado al construir audiencias de token OAuth. No añadas prefijo HTTP(S) ni puerto.
  • ssl_keyfile - Ruta a la clave SSL para HTTPS. (ej. privkey.pem)
  • ssl_certfile - Ruta al certificado SSL para HTTPS. (ej. fullchain.pem)
  • registration_psk - Clave precompartida requerida para registrar clientes OAuth. Necesitarás escribir este secreto en tu navegador para aprobar conexiones OAuth.
  • jwt_key_path - Ubicación del par de claves RSA usado para tokens OAuth. Por defecto .cache/jwt.json. Se autogenera si no existe.
  • oauth_db_path - Ruta al archivo de base de datos OAuth. Por defecto .cache/oauth.db. Se autogenera si no existe.
  • enabled_tools - Lista de nombres de herramientas a registrar. Una lista vacía habilita todas las herramientas. Se recomienda encarecidamente habilitar herramientas selectivamente por caso de uso o tarea. Consulta la carpeta docs/ para algunos ejemplos.
  • search_objects - Tipos de objeto permitidos para la herramienta search. Por defecto ["secret"] pero puede incluir user, folder, group y role.
  • fetch_objects - Tipos de objeto permitidos para la herramienta fetch. Por defecto ["secret"] pero puede incluir los mismos valores que search_objects.

Ejecutar el Servidor

Inicia el servidor localmente en modo desarrollo:

python server.py

Al iniciar, el servidor solicita un token de portador y lo almacena para solicitudes API posteriores. Este proyecto se ampliará para integrarse más con la API de Secret Server.

Herramientas MCP

El servidor expone varias herramientas MCP para interactuar con Secret Server:

  • run_report(sql_query, report_name=None) - crear y ejecutar un informe temporal.
  • ai_generate_and_run_report(description) - generar SQL usando Azure OpenAI y ejecutarlo. Requiere las variables de Azure OpenAI.
  • list_example_reports() - listar consultas de ejemplo e información de tablas.
  • get_secret(id, summary=False) - recuperar un secreto o detalles resumidos.
  • get_folder(id) - obtener metadatos de carpeta e hijos.
  • search_users(query) - buscar usuarios activos.
  • search_secrets(query, lookup=False) - buscar o consultar secretos.
  • search_folders(query, lookup=False) - buscar o consultar carpetas.
  • get_secret_environment_variable(secret_id, environment) - generar un script para obtener credenciales de secreto en el shell especificado.
  • check_secret_template(template_id) - obtener detalles de plantilla de secreto.
  • check_secret_template_field(template_id, field_id) - verificar si una plantilla contiene un campo.
  • get_secret_template_field(field_id) - recuperar detalles sobre un campo específico de plantilla de secreto por ID.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - aprobar o denegar una solicitud de acceso.
  • get_pending_access_requests() - listar solicitudes de acceso pendientes.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - recuperar mensajes de la bandeja de entrada.
  • mark_inbox_messages_read(message_ids, read=True) - marcar mensajes como leídos o no leídos.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - operaciones unificadas de usuario. action acepta get, create, update, delete, list_sessions, reset_2fa, reset_password o lock_out. Proporciona user_id cuando sea necesario y suministra el cuerpo de la solicitud mediante data para acciones de crear, actualizar y restablecer contraseña. Ejemplo: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - gestionar roles. action puede ser list, get, create o update. Pasa parámetros de consulta opcionales con params al listar roles. Ejemplo: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - asignar o eliminar roles de un usuario. action es get, add o remove y role_ids es una lista de identificadores de rol para operaciones de añadir/eliminar.
  • group_management(action, group_id=None, data=None, params=None) - manejar grupos. action puede ser get, list, create o delete. Proporciona group_id para obtener/eliminar y data al crear un grupo.
  • folder_management(action, folder_id=None, data=None, params=None) - gestionar carpetas. action puede ser get, list, create, update o delete. Proporciona folder_id para obtener, actualizar o eliminar y suministra data al crear o actualizar una carpeta.
  • user_group_management(action, user_id, group_ids=None) - gestionar pertenencia a grupos para un usuario. action es get, add o remove. Suministra una lista de group_ids al añadir o eliminar pertenencia.
  • group_role_management(action, group_id, role_ids=None) - controlar roles en un grupo. Usa acciones list, add o remove. Proporciona role_ids al añadir o eliminar.
  • health_check() - consultar el endpoint de verificación de salud de Secret Server y devolver el estado actual del servicio.

Usa las variables de configuración del servidor descritas arriba para autenticarte. La herramienta de IA se deshabilita automáticamente si faltan las variables de Azure OpenAI. Solo se registrarán los nombres de herramienta listados en config.json. Una lista vacía habilita todas las herramientas.

Casos de Uso

La documentación cubre varios flujos de trabajo para conectar herramientas al servidor:

Inicio Rápido con Docker

Se proporciona un Dockerfile para ejecutar el servidor MCP sin instalar dependencias de Python localmente.

  1. Construir la imagen:
docker build -t dev.local/delinea-mcp:latest .
  1. Ejecutar el servidor (pasa tus credenciales mediante variables de entorno):
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

Rellena config.json con tus nombres de usuario y URLs como se muestra arriba.

El contenedor almacena oauth.db y jwt.json en /app/data. Monta un volumen (mostrado como mcp-data arriba) para que estos archivos y cualquier certificado HTTPS persistan entre ejecuciones.

Reemplaza <https://your-secret-server/SecretServer> con la URL base de tu instancia de Secret Server para evitar errores de conexión.

El servidor se iniciará en el puerto 8000 por defecto usando python server.py. Establece la opción port en config.json para anular el valor por defecto. Habilita debug: true para registrar todas las solicitudes HTTP entrantes.

Scripts de Ejemplo

El script manual_secret_request.py muestra cómo recuperar un token OAuth para un ID de secreto específico:

python scripts/manual_secret_request.py <Secret_ID>

Establece las variables de entorno SECRET_USERNAME_<id> y SECRET_PASSWORD_<id> para el secreto antes de ejecutar el script. Opcionalmente establece DELINEA_BASE_URL para anular el https://localhost/SecretServer por defecto.

Ejecutar Pruebas

Ejecuta las pruebas unitarias con cobertura para asegurar 100% de cobertura de código:

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

Pruebas en Vivo

Algunas pruebas de integración requieren credenciales válidas. Establece las siguientes variables de entorno y el LIVE_SECRET_ID opcional antes de ejecutar la suite:

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>

Cuando estas variables están presentes, las pruebas en vivo realizarán solicitudes API reales.

Despliegue en Producción

Las dependencias están fijadas en requirements.txt y las versiones se etiquetan usando Versionado Semántico. Construye la imagen Docker desde un commit etiquetado y despliégala en tu entorno de producción, pasando las variables de entorno requeridas (DELINEA_USERNAME, DELINEA_PASSWORD, opcionalmente DELINEA_BASE_URL). Las características opcionales dependen de variables adicionales:

  • PLATFORM_SERVICE_PASSWORD junto con PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT y PLATFORM_TENANT_ID habilita las herramientas de gestión de usuarios.
  • AZURE_OPENAI_KEY junto con AZURE_OPENAI_ENDPOINT y AZURE_OPENAI_DEPLOYMENT habilita el ayudante de generación de informes con IA.

Al ejecutar con transporte OAuth o SSE puede que necesites proporcionar registration_psk y configurar un external_hostname o archivos de certificado HTTPS.

Estructura del Repositorio

  • delinea_mcp/ - paquete que contiene las herramientas MCP.
  • server.py - punto de entrada ligero que registra todo con el servidor MCP.
  • docs/ - documentación del proyecto y el delinea-secret-server-openapi-spec.json generado.
  • scripts/ - ejemplos de ayuda incluyendo manual_secret_request.py.

Consideraciones de Seguridad

Los endpoints OAuth incluidos están destinados para desarrollo y pruebas. La ruta /oauth/authorize acepta cualquier redirect_uri y redirigirá al usuario sin validación. Los despliegues deben restringir este valor a URLs de callback aprobadas; de lo contrario, los atacantes podrían suministrar una URL maliciosa y capturar códigos de autorización. Consulta Redirección Abierta para más información.

Notas de la Versión

Consulta docs/release_notes.md para un resumen de las últimas características y elementos de la hoja de ruta.

Hoja de Ruta

  1. Autenticación de paso a través
  2. Soporte de transporte HTTP en streaming
  3. Ampliar la cobertura de herramientas en Delinea Platform y añadir otros productos de Delinea

Contribuir

¡Las contribuciones son bienvenidas! Por favor, abre issues o pull requests para cualquier mejora. Todo el código nuevo debe incluir pruebas unitarias y pasar la suite de pruebas existente.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.