delinea-mcp Server

chính thức

Máy chủ MCP chính thức của Delinea cho Delinea Secret Server và Platform APIs

GitHub
46

Tài liệu

DelineaMCP

Máy chủ MCP cho API Secret Server và Nền tảng Delinea

License

Tính năng

  • Xác thực tự động với Secret Server
  • Bộ công cụ Secret Server phong phú để quản lý thư mục, bí mật, người dùng, nhóm và vai trò. Bao gồm các trình trợ giúp hộp thư đến và yêu cầu truy cập cùng các tiện ích cho tác nhân lập trình.
  • Các công cụ tương thích ChatGPT (search và fetch) cho các tương tác AI có kiểm soát.
  • Công cụ quản lý người dùng Nền tảng Delinea tùy chọn
  • Hỗ trợ cả hai chế độ truyền tải Server Sent Events hoặc STDIO
  • OAuth 2.0 với đăng ký máy khách động theo đặc tả MCP
  • Hỗ trợ TLS cho các kết nối an toàn
  • Hình ảnh Docker sẵn sàng chạy và điểm vào máy chủ phát triển
  • Đã kiểm thử với ChatGPT, Claude Desktop, trình kết nối Claude từ xa, VSCode Copilot và openwebui

Cài đặt

[!LƯU Ý]

Dự án này sử dụng uv (https://github.com/astral-sh/uv), nhưng nếu bạn muốn chạy lệnh mà không cần nó, bạn có thể thực hiện các lệnh pip và venv như bình thường nếu muốn.

  • Cài đặt Uv
  • Khởi tạo dự án: uv pip sync requirements.txt
  • Sử dụng uv run server.py --config config.json

Cấu hình

Các bí mật như mật khẩu tiếp tục đến từ biến môi trường. Cung cấp DELINEA_PASSWORD trong môi trường shell của bạn. Các tính năng tùy chọn dựa vào các biến bổ sung như AZURE_OPENAI_KEY hoặc PLATFORM_SERVICE_PASSWORD.

Các tham số không phải bí mật thuộc về 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": []
}

Đối với Secret Server Cloud, chỉ cần sử dụng URL đám mây mà không có /SecretServer. Chỉ định ssl_keyfile và ssl_certfile để bật HTTPS. Đối với Let's Encrypt, sử dụng các tệp privkey.pem và fullchain.pem.

Tệp cấu hình hỗ trợ các khóa sau:

  • delinea_username - Tên người dùng Secret Server. Phải là người dùng lập trình có quyền thực hiện các tác vụ bạn muốn.
  • delinea_base_url - URL cơ sở của phiên bản Secret Server của bạn.
  • platform_hostname - Tên máy chủ tenant Nền tảng (bật các công cụ Nền tảng).
  • platform_service_account - Tài khoản dịch vụ được sử dụng với API Nền tảng.
  • platform_tenant_id - ID Tenant cho các yêu cầu API Nền tảng.
  • azure_openai_endpoint - Điểm cuối Azure OpenAI. Chỉ khi bạn muốn tạo báo cáo tự động (hầu hết các tác nhân có thể tự tạo SQL báo cáo nên đừng bật trừ khi bạn cần).
  • azure_openai_deployment - Tên triển khai cho Azure OpenAI.
  • auth_mode - Chế độ xác thực (none hoặc oauth). OAuth rõ ràng không hoạt động với truyền tải stdio.
  • transport_mode - stdio cho dòng lệnh hoặc sse cho HTTP/SSE.
  • chatgpt_disable_scope_checks - Bỏ qua xác thực phạm vi trên các yêu cầu ChatGPT. Chỉ bật nếu bạn gặp sự cố khi kết nối với ChatGPT.
  • port - Cổng cho máy chủ HTTP ở chế độ sse.
  • debug - Bật ghi nhật ký chi tiết.
  • external_hostname - Tên máy chủ được sử dụng khi xây dựng đối tượng token OAuth. Đừng thêm tiền tố HTTP(S) hoặc cổng.
  • ssl_keyfile - Đường dẫn đến khóa SSL cho HTTPS. (ví dụ: privkey.pem)
  • ssl_certfile - Đường dẫn đến chứng chỉ SSL cho HTTPS. (ví dụ: fullchain.pem)
  • registration_psk - Khóa chia sẻ trước cần thiết để đăng ký máy khách OAuth. Bạn sẽ cần nhập bí mật này vào trình duyệt để phê duyệt kết nối OAuth.
  • jwt_key_path - Vị trí của cặp khóa RSA được sử dụng cho token OAuth. Mặc định là .cache/jwt.json. tự động tạo nếu không tồn tại.
  • oauth_db_path - Đường dẫn đến tệp cơ sở dữ liệu OAuth. Mặc định là .cache/oauth.db. tự động tạo nếu không tồn tại.
  • enabled_tools - Danh sách tên công cụ để đăng ký. Một danh sách trống sẽ bật tất cả các công cụ. Rất khuyến khích bật công cụ có chọn lọc theo từng trường hợp sử dụng hoặc tác vụ. Xem thư mục docs/ để biết một số ví dụ.
  • search_objects - Các loại đối tượng được phép cho công cụ search. Mặc định là ["secret"] nhưng có thể bao gồm user, folder, group và role.
  • fetch_objects - Các loại đối tượng được phép cho công cụ fetch. Mặc định là ["secret"] nhưng có thể bao gồm các giá trị tương tự như search_objects.

Chạy Máy chủ

Khởi động máy chủ cục bộ ở chế độ phát triển:

python server.py

Khi khởi động, máy chủ yêu cầu token bearer và lưu trữ nó cho các yêu cầu API tiếp theo. Dự án này sẽ được mở rộng để tích hợp sâu hơn với API Secret Server.

Công cụ MCP

Máy chủ hiển thị một số công cụ MCP để tương tác với Secret Server:

  • run_report(sql_query, report_name=None) - tạo và thực thi một báo cáo tạm thời.
  • ai_generate_and_run_report(description) - tạo SQL bằng Azure OpenAI và chạy nó. Yêu cầu các biến Azure OpenAI.
  • list_example_reports() - liệt kê các truy vấn mẫu và thông tin bảng.
  • get_secret(id, summary=False) - truy xuất bí mật hoặc chi tiết tóm tắt.
  • get_folder(id) - lấy siêu dữ liệu thư mục và các mục con.
  • search_users(query) - tìm kiếm người dùng đang hoạt động.
  • search_secrets(query, lookup=False) - tìm kiếm hoặc tra cứu bí mật.
  • search_folders(query, lookup=False) - tìm kiếm hoặc tra cứu thư mục.
  • get_secret_environment_variable(secret_id, environment) - xuất ra một tập lệnh để lấy thông tin xác thực bí mật trong shell được chỉ định.
  • check_secret_template(template_id) - lấy chi tiết mẫu bí mật.
  • check_secret_template_field(template_id, field_id) - kiểm tra xem mẫu có chứa một trường hay không.
  • get_secret_template_field(field_id) - truy xuất chi tiết về một trường mẫu bí mật cụ thể theo ID.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - phê duyệt hoặc từ chối yêu cầu truy cập.
  • get_pending_access_requests() - liệt kê các yêu cầu truy cập đang chờ xử lý.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - truy xuất tin nhắn hộp thư đến.
  • mark_inbox_messages_read(message_ids, read=True) - đánh dấu tin nhắn là đã đọc hoặc chưa đọc.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - các thao tác người dùng hợp nhất. action chấp nhận get, create, update, delete, list_sessions, reset_2fa, reset_password hoặc lock_out. Cung cấp user_id khi được yêu cầu và cung cấp nội dung yêu cầu qua data cho các hành động tạo, cập nhật và đặt lại mật khẩu. Ví dụ: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - quản lý vai trò. action có thể là list, get, create hoặc update. Truyền các tham số truy vấn tùy chọn với params khi liệt kê vai trò. Ví dụ: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - gán hoặc xóa vai trò khỏi người dùng. action là get, add hoặc remove và role_ids là danh sách các định danh vai trò cho các thao tác thêm/xóa.
  • group_management(action, group_id=None, data=None, params=None) - xử lý nhóm. action có thể là get, list, create hoặc delete. Cung cấp group_id cho get/delete và data khi tạo nhóm.
  • folder_management(action, folder_id=None, data=None, params=None) - quản lý thư mục. action có thể là get, list, create, update hoặc delete. Cung cấp folder_id cho get, update hoặc delete và cung cấp data khi tạo hoặc cập nhật thư mục.
  • user_group_management(action, user_id, group_ids=None) - quản lý tư cách thành viên nhóm cho người dùng. action là get, add hoặc remove. Cung cấp danh sách group_ids khi thêm hoặc xóa tư cách thành viên.
  • group_role_management(action, group_id, role_ids=None) - kiểm soát vai trò trên một nhóm. Sử dụng các hành động list, add hoặc remove. Cung cấp role_ids khi thêm hoặc xóa.
  • health_check() - truy vấn điểm cuối kiểm tra tình trạng Secret Server và trả về trạng thái dịch vụ hiện tại.

Sử dụng các biến cấu hình máy chủ được mô tả ở trên để xác thực. Công cụ AI tự động bị vô hiệu hóa nếu thiếu các biến Azure OpenAI. Chỉ các tên công cụ được liệt kê trong config.json mới được đăng ký. Một danh sách trống sẽ bật mọi công cụ.

Trường hợp sử dụng

Tài liệu bao gồm một số quy trình làm việc để kết nối các công cụ với máy chủ:

Khởi động nhanh Docker

Một Dockerfile được cung cấp để chạy máy chủ MCP mà không cần cài đặt phụ thuộc Python cục bộ.

  1. Xây dựng hình ảnh:
docker build -t dev.local/delinea-mcp:latest .
  1. Chạy máy chủ (truyền thông tin xác thực của bạn qua biến môi trường):
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

Điền config.json với tên người dùng và URL của bạn như được hiển thị ở trên.

Container lưu trữ oauth.db và jwt.json trong /app/data. Gắn một ổ đĩa (được hiển thị là mcp-data ở trên) để các tệp này và bất kỳ chứng chỉ HTTPS nào tồn tại giữa các lần chạy.

Thay thế <https://your-secret-server/SecretServer> bằng URL cơ sở của phiên bản Secret Server của bạn để tránh lỗi kết nối.

Máy chủ sẽ khởi động trên cổng 8000 theo mặc định sử dụng python server.py. Đặt tùy chọn port trong config.json để ghi đè mặc định. Bật debug: true để ghi nhật ký tất cả các yêu cầu HTTP đến.

Tập lệnh ví dụ

Tập lệnh manual_secret_request.py cho thấy cách truy xuất token OAuth cho một ID bí mật cụ thể:

python scripts/manual_secret_request.py <Secret_ID>

Đặt các biến môi trường SECRET_USERNAME_<id> và SECRET_PASSWORD_<id> cho bí mật trước khi chạy tập lệnh. Tùy chọn đặt DELINEA_BASE_URL để ghi đè https://localhost/SecretServer mặc định.

Chạy Kiểm thử

Chạy các bài kiểm thử đơn vị với độ bao phủ để đảm bảo độ bao phủ mã 100%:

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

Kiểm thử trực tiếp

Một số bài kiểm thử tích hợp yêu cầu thông tin xác thực hợp lệ. Đặt các biến môi trường sau và LIVE_SECRET_ID tùy chọn trước khi chạy bộ kiểm thử:

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>

Khi các biến này có mặt, các bài kiểm thử trực tiếp sẽ thực hiện các yêu cầu API thực tế.

Triển khai sản xuất

Các phụ thuộc được ghim trong requirements.txt và các bản phát hành được gắn thẻ bằng Semantic Versioning. Xây dựng hình ảnh Docker từ một commit được gắn thẻ và triển khai nó vào môi trường sản xuất của bạn, truyền các biến môi trường cần thiết (DELINEA_USERNAME, DELINEA_PASSWORD, tùy chọn DELINEA_BASE_URL). Các tính năng tùy chọn dựa vào các biến bổ sung:

  • PLATFORM_SERVICE_PASSWORD cùng với PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT và PLATFORM_TENANT_ID bật các công cụ quản lý người dùng.
  • AZURE_OPENAI_KEY cùng với AZURE_OPENAI_ENDPOINT và AZURE_OPENAI_DEPLOYMENT bật trình trợ giúp tạo báo cáo AI.

Khi chạy với truyền tải OAuth hoặc SSE, bạn có thể cần cung cấp registration_psk và định cấu hình external_hostname hoặc các tệp chứng chỉ HTTPS.

Bố cục Kho lưu trữ

  • delinea_mcp/ - gói chứa các công cụ MCP.
  • server.py - điểm vào mỏng đăng ký mọi thứ với máy chủ MCP.
  • docs/ - tài liệu dự án và delinea-secret-server-openapi-spec.json được tạo.
  • scripts/ - các ví dụ trợ giúp bao gồm manual_secret_request.py.

Cân nhắc Bảo mật

Các điểm cuối OAuth đi kèm được dành cho phát triển và kiểm thử. Tuyến /oauth/authorize chấp nhận bất kỳ redirect_uri nào và sẽ chuyển hướng người dùng mà không xác thực. Các triển khai phải hạn chế giá trị này thành các URL gọi lại được phê duyệt; nếu không, kẻ tấn công có thể cung cấp URL độc hại và thu thập mã ủy quyền. Xem Open Redirection để biết thông tin cơ bản.

Ghi chú Phát hành

Xem docs/release_notes.md để biết tóm tắt về các tính năng mới nhất và các mục lộ trình.

Lộ trình

  1. Xác thực chuyển tiếp
  2. Hỗ trợ truyền tải HTTP phát trực tuyến
  3. Mở rộng phạm vi công cụ trên Nền tảng Delinea và thêm các sản phẩm Delinea khác

Đóng góp

Rất hoan nghênh các đóng góp! Vui lòng mở các vấn đề hoặc yêu cầu kéo cho bất kỳ cải tiến nào. Tất cả mã mới nên bao gồm các bài kiểm thử đơn vị và vượt qua bộ kiểm thử hiện có.

Giấy phép

Dự án này được cấp phép theo Giấy phép MIT.