delinea-mcp Server

官方

適用於 Delinea Secret Server 與平台 API 的官方 Delinea MCP 伺服器

GitHub
46

文件

DelineaMCP

適用於 Delinea Secret Server 與 Platform API 的 MCP 伺服器

License

功能特色

  • 自動對 Secret Server 進行驗證
  • 廣泛的 Secret Server 工具集，用於管理資料夾、密鑰、使用者、群組與角色。 包含收件匣與存取請求輔助工具，以及編碼代理程式實用工具。
  • ChatGPT 相容工具 (search 與 fetch)，用於受控的 AI 互動。
  • 選用的 Delinea Platform 使用者管理工具
  • 支援伺服器傳送事件 (Server Sent Events) 或 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，並將在未經驗證的情況下重新導向使用者。 部署時必須將此值限制為已核准的回呼 URL；否則攻擊者可能提供惡意 URL 並擷取授權碼。 請參閱 開放式重新導向 以了解背景資訊。

發行說明

請參閱 docs/release_notes.md 以取得最新功能與路線圖項目的摘要。

路線圖

  1. 透通驗證
  2. 串流 HTTP 傳輸支援
  3. 擴展 Delinea Platform 上的工具覆蓋範圍，並新增其他 Delinea 產品

貢獻

歡迎貢獻！ 如有任何改進，請提出議題或拉取請求。 所有新程式碼應包含單元測試，並通過現有的測試套件。

授權

本專案依據 MIT 授權條款 授權。