delinea-mcp Server

官方

Delinea Secret Server 和 Platform API 的官方 Delinea MCP 服务器

GitHub
46

文档

DelineaMCP

适用于 Delinea Secret Server 和 Platform API 的 MCP 服务器

License

功能特性

  • 自动对 Secret Server 进行身份验证
  • 丰富的 Secret Server 工具集，用于管理文件夹、机密、用户、组和角色。 包含收件箱和访问请求助手以及编码代理实用工具。
  • ChatGPT 兼容工具（search 和 fetch），用于受控的 AI 交互。
  • 可选的 Delinea Platform 用户管理工具
  • 支持服务器发送事件或 STDIO 传输模式
  • 符合 MCP 规范的 OAuth 2.0 动态客户端注册
  • 支持 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

配置

密码等机密信息继续通过环境变量提供。 在您的 shell 环境中提供 DELINEA_PASSWORD。 可选功能依赖于额外的变量，例如 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 - Secret Server 实例的基础 URL。
  • platform_hostname - Platform 租户主机名（启用 Platform 工具）。
  • platform_service_account - 用于 Platform API 的服务账户。
  • platform_tenant_id - Platform API 请求的租户 ID。
  • azure_openai_endpoint - Azure OpenAI 端点。仅在需要自动生成报告时使用（大多数代理可以生成自己的报告 SQL，因此除非必要，否则不要启用）。
  • azure_openai_deployment - Azure OpenAI 的部署名称。
  • auth_mode - 身份验证模式（none 或 oauth）。OAuth 显然不适用于 stdio 传输。
  • transport_mode - 命令行使用 stdio，HTTP/SSE 使用 sse。
  • chatgpt_disable_scope_checks - 跳过对 ChatGPT 请求的范围验证。仅在连接 ChatGPT 遇到问题时启用。
  • port - sse 模式下 HTTP 服务器的端口。
  • debug - 启用详细日志记录。
  • external_hostname - 构建 OAuth 令牌受众时使用的主机名。不要添加 HTTP(S) 前缀或端口。
  • ssl_keyfile - HTTPS 的 SSL 密钥文件路径。（例如 privkey.pem）
  • ssl_certfile - HTTPS 的 SSL 证书文件路径。（例如 fullchain.pem）
  • registration_psk - 注册 OAuth 客户端所需的预共享密钥。您需要在浏览器中输入此密钥以批准 OAuth 连接。
  • jwt_key_path - 用于 OAuth 令牌的 RSA 密钥对的位置。默认为 .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 请求使用。 本项目将扩展以进一步与 Secret Server API 集成。

MCP 工具

服务器公开了多个用于与 Secret Server 交互的 MCP 工具：

  • run_report(sql_query, report_name=None) - 创建并执行临时报告。
  • ai_generate_and_run_report(description) - 使用 Azure OpenAI 生成 SQL 并运行。 需要 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) - 输出一个脚本，用于在指定 shell 中获取机密凭据。
  • 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 变量，AI 工具将自动禁用。 只有 config.json 中列出的工具名称才会被注册。 空列表将启用所有工具。

用例

文档涵盖了将工具连接到服务器的几种工作流程：

Docker 快速入门

提供了一个 Dockerfile，用于在本地无需安装 Python 依赖项即可运行 MCP 服务器。

  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

如上所示，使用您的用户名和 URL 填充 config.json。

容器将 oauth.db 和 jwt.json 存储在 /app/data 中。 挂载一个卷（如上所示的 mcp-data），以便这些文件和任何 HTTPS 证书在运行之间持久化。

将 <https://your-secret-server/SecretServer> 替换为您的 Secret Server 实例的基础 URL，以避免连接错误。

默认情况下，服务器将使用 python server.py 在端口 8000 上启动。 在 config.json 中设置 port 选项以覆盖默认值。 启用 debug: true 以记录所有传入的 HTTP 请求。

示例脚本

manual_secret_request.py 脚本展示了如何为特定机密 ID 检索 OAuth 令牌：

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 请求。

生产部署

依赖项固定在 requirements.txt 中，发布版本使用语义化版本控制进行标记。 从标记的提交构建 Docker 镜像，并将其部署到您的生产环境，传递所需的环境变量（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 启用 AI 报告生成助手。

当使用 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，并将重定向用户而不进行验证。 部署时必须将此值限制为已批准的 callback URL；否则攻击者可能会提供恶意 URL 并捕获授权码。 有关背景信息，请参阅开放重定向。

发布说明

有关最新功能和路线图项目的摘要，请参阅 docs/release_notes.md。

路线图

  1. 直通身份验证
  2. 流式 HTTP 传输支持
  3. 扩展 Delinea Platform 上的工具覆盖范围，并添加其他 Delinea 产品

贡献

欢迎贡献！ 请为任何改进提交问题或拉取请求。 所有新代码都应包含单元测试并通过现有的测试套件。

许可证

本项目根据 MIT 许可证 授权。