delinea-mcp Server

resmi

Server MCP Delinea resmi untuk Secret Server Delinea dan API Platform

GitHub
46

Dokumentasi

DelineaMCP

Server MCP untuk API Delinea Secret Server dan Platform

License

Fitur

  • Otentikasi otomatis terhadap Secret Server
  • Perangkat Secret Server yang lengkap untuk mengelola folder, secret, pengguna, grup, dan peran. Termasuk pembantu kotak masuk dan permintaan akses serta utilitas agen pengkodean.
  • Alat kompatibilitas ChatGPT (search dan fetch) untuk interaksi AI yang terkontrol.
  • Alat manajemen pengguna Delinea Platform opsional
  • Mendukung mode transport Server Sent Events atau STDIO
  • OAuth 2.0 dengan registrasi klien dinamis sesuai spesifikasi MCP
  • Dukungan TLS untuk koneksi aman
  • Gambar Docker siap pakai dan titik masuk server pengembangan
  • Diuji dengan ChatGPT, Claude Desktop, konektor Claude jarak jauh, VSCode Copilot, dan openwebui

Instalasi

[!NOTE]

Proyek ini menggunakan uv (https://github.com/astral-sh/uv), tetapi jika Anda lebih suka menjalankan perintah tanpa ini, Anda dapat melakukan perintah pip dan venv seperti biasa jika diinginkan.

  • Instal Uv
  • Inisialisasi proyek: uv pip sync requirements.txt
  • Gunakan uv run server.py --config config.json

Konfigurasi

Secret seperti kata sandi tetap berasal dari variabel lingkungan. Sediakan DELINEA_PASSWORD di lingkungan shell Anda. Fitur opsional bergantung pada variabel tambahan seperti AZURE_OPENAI_KEY atau PLATFORM_SERVICE_PASSWORD.

Parameter non-rahasia termasuk dalam 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": []
}

Untuk Secret Server Cloud cukup gunakan URL cloud tanpa /SecretServer. Tentukan ssl_keyfile dan ssl_certfile untuk mengaktifkan HTTPS. Untuk Let's Encrypt, gunakan file privkey.pem dan fullchain.pem.

File konfigurasi mendukung kunci berikut:

  • delinea_username - Nama pengguna Secret Server. Harus berupa pengguna terprogram dengan izin untuk melakukan tugas yang Anda inginkan.
  • delinea_base_url - URL dasar instans Secret Server Anda.
  • platform_hostname - Nama host tenant Platform (mengaktifkan alat Platform).
  • platform_service_account - Akun layanan yang digunakan dengan API Platform.
  • platform_tenant_id - ID Tenant untuk permintaan API Platform.
  • azure_openai_endpoint - Endpoint Azure OpenAI. Hanya jika Anda menginginkan pembuatan laporan otomatis (sebagian besar agen dapat menghasilkan SQL laporan sendiri jadi jangan aktifkan kecuali Anda membutuhkannya).
  • azure_openai_deployment - Nama deployment untuk Azure OpenAI.
  • auth_mode - Mode otentikasi (none atau oauth). OAuth jelas tidak berfungsi dengan transport stdio.
  • transport_mode - stdio untuk baris perintah atau sse untuk HTTP/SSE.
  • chatgpt_disable_scope_checks - Lewati validasi cakupan pada permintaan ChatGPT. Aktifkan hanya jika Anda mengalami masalah saat menghubungkan ke ChatGPT.
  • port - Port untuk server HTTP dalam mode sse.
  • debug - Aktifkan pencatatan verbose.
  • external_hostname - Nama host yang digunakan saat membangun audiens token OAuth. Jangan tambahkan awalan HTTP(S) atau port.
  • ssl_keyfile - Jalur ke kunci SSL untuk HTTPS. (mis. privkey.pem)
  • ssl_certfile - Jalur ke sertifikat SSL untuk HTTPS. (mis. fullchain.pem)
  • registration_psk - Kunci pra-berbagi yang diperlukan untuk mendaftarkan klien OAuth. Anda perlu mengetikkan rahasia ini di browser Anda untuk menyetujui koneksi OAuth.
  • jwt_key_path - Lokasi pasangan kunci RSA yang digunakan untuk token OAuth. Default ke .cache/jwt.json. dibuat otomatis jika tidak ada.
  • oauth_db_path - Jalur ke file database OAuth. Default ke .cache/oauth.db. dibuat otomatis jika tidak ada.
  • enabled_tools - Daftar nama alat yang akan didaftarkan. Daftar kosong mengaktifkan semua alat. Sangat disarankan untuk mengaktifkan alat secara selektif per kasus penggunaan atau tugas. Lihat folder docs/ untuk beberapa contoh.
  • search_objects - Jenis objek yang diizinkan untuk alat search. Default ke ["secret"] tetapi dapat mencakup user, folder, group dan role.
  • fetch_objects - Jenis objek yang diizinkan untuk alat fetch. Default ke ["secret"] tetapi dapat mencakup nilai yang sama seperti search_objects.

Menjalankan Server

Mulai server secara lokal dalam mode pengembangan:

python server.py

Saat startup, server meminta token pembawa dan menyimpannya untuk permintaan API berikutnya. Proyek ini akan diperluas untuk berintegrasi lebih lanjut dengan API Secret Server.

Alat MCP

Server mengekspos beberapa alat MCP untuk berinteraksi dengan Secret Server:

  • run_report(sql_query, report_name=None) - membuat dan menjalankan laporan sementara.
  • ai_generate_and_run_report(description) - menghasilkan SQL menggunakan Azure OpenAI dan menjalankannya. Memerlukan variabel Azure OpenAI.
  • list_example_reports() - daftar kueri sampel dan informasi tabel.
  • get_secret(id, summary=False) - mengambil secret atau detail ringkasan.
  • get_folder(id) - mengambil metadata folder dan anak-anaknya.
  • search_users(query) - mencari pengguna aktif.
  • search_secrets(query, lookup=False) - mencari atau melihat secret.
  • search_folders(query, lookup=False) - mencari atau melihat folder.
  • get_secret_environment_variable(secret_id, environment) - mengeluarkan skrip untuk mengambil kredensial secret di shell yang ditentukan.
  • check_secret_template(template_id) - mengambil detail template secret.
  • check_secret_template_field(template_id, field_id) - memeriksa apakah template berisi bidang.
  • get_secret_template_field(field_id) - mengambil detail tentang bidang template secret tertentu berdasarkan ID.
  • handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - menyetujui atau menolak permintaan akses.
  • get_pending_access_requests() - daftar permintaan akses yang tertunda.
  • get_inbox_messages(read_status_filter=None, take=20, skip=0) - mengambil pesan kotak masuk.
  • mark_inbox_messages_read(message_ids, read=True) - menandai pesan sebagai dibaca atau belum dibaca.
  • user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - operasi pengguna terpadu. action menerima get, create, update, delete, list_sessions, reset_2fa, reset_password atau lock_out. Sediakan user_id saat diperlukan dan berikan isi permintaan melalui data untuk tindakan buat, perbarui, dan atur ulang kata sandi. Contoh: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
  • role_management(action, role_id=None, data=None, params=None) - mengelola peran. action dapat berupa list, get, create atau update. Berikan parameter kueri opsional dengan params saat mendaftar peran. Contoh: role_management("update", role_id=3, data={"name": "New Role"}).
  • user_role_management(action, user_id, role_ids=None) - menetapkan atau menghapus peran dari pengguna. action adalah get, add atau remove dan role_ids adalah daftar pengidentifikasi peran untuk operasi tambah/hapus.
  • group_management(action, group_id=None, data=None, params=None) - menangani grup. action dapat berupa get, list, create atau delete. Sediakan group_id untuk dapatkan/hapus dan data saat membuat grup.
  • folder_management(action, folder_id=None, data=None, params=None) - mengelola folder. action dapat berupa get, list, create, update atau delete. Sediakan folder_id untuk dapatkan, perbarui atau hapus dan berikan data saat membuat atau memperbarui folder.
  • user_group_management(action, user_id, group_ids=None) - mengelola keanggotaan grup untuk pengguna. action adalah get, add atau remove. Berikan daftar group_ids saat menambah atau menghapus keanggotaan.
  • group_role_management(action, group_id, role_ids=None) - mengontrol peran pada grup. Gunakan tindakan list, add atau remove. Sediakan role_ids saat menambah atau menghapus.
  • health_check() - meminta endpoint pemeriksaan kesehatan Secret Server dan mengembalikan status layanan saat ini.

Gunakan variabel konfigurasi server yang dijelaskan di atas untuk otentikasi. Alat AI secara otomatis dinonaktifkan jika variabel Azure OpenAI tidak ada. Hanya nama alat yang tercantum dalam config.json yang akan didaftarkan. Daftar kosong mengaktifkan setiap alat.

Kasus Penggunaan

Dokumentasi mencakup beberapa alur kerja untuk menghubungkan alat ke server:

Mulai Cepat Docker

Sebuah Dockerfile disediakan untuk menjalankan server MCP tanpa menginstal dependensi Python secara lokal.

  1. Bangun gambar:
docker build -t dev.local/delinea-mcp:latest .
  1. Jalankan server (berikan kredensial Anda melalui variabel lingkungan):
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

Isi config.json dengan nama pengguna dan URL Anda seperti yang ditunjukkan di atas.

Kontainer menyimpan oauth.db dan jwt.json di /app/data. Pasang volume (ditunjukkan sebagai mcp-data di atas) agar file-file ini dan sertifikat HTTPS apa pun tetap ada di antara proses berjalan.

Ganti <https://your-secret-server/SecretServer> dengan URL dasar instans Secret Server Anda untuk menghindari kesalahan koneksi.

Server akan mulai pada port 8000 secara default menggunakan python server.py. Atur opsi port di config.json untuk mengganti default. Aktifkan debug: true untuk mencatat semua permintaan HTTP masuk.

Skrip Contoh

Skrip manual_secret_request.py menunjukkan cara mengambil token OAuth untuk ID secret tertentu:

python scripts/manual_secret_request.py <Secret_ID>

Atur variabel lingkungan SECRET_USERNAME_<id> dan SECRET_PASSWORD_<id> untuk secret sebelum menjalankan skrip. Secara opsional atur DELINEA_BASE_URL untuk mengganti default https://localhost/SecretServer.

Menjalankan Tes

Jalankan tes unit dengan cakupan untuk memastikan cakupan kode 100%:

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

Pengujian Langsung

Beberapa tes integrasi memerlukan kredensial yang valid. Atur variabel lingkungan berikut dan LIVE_SECRET_ID opsional sebelum menjalankan rangkaian:

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>

Ketika variabel-variabel ini ada, tes langsung akan melakukan permintaan API nyata.

Deployment Produksi

Dependensi disematkan di requirements.txt dan rilis ditandai menggunakan Semantic Versioning. Bangun gambar Docker dari komit yang ditandai dan deploy ke lingkungan produksi Anda, berikan variabel lingkungan yang diperlukan (DELINEA_USERNAME, DELINEA_PASSWORD, secara opsional DELINEA_BASE_URL). Fitur opsional bergantung pada variabel tambahan:

  • PLATFORM_SERVICE_PASSWORD bersama dengan PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT, dan PLATFORM_TENANT_ID mengaktifkan alat manajemen pengguna.
  • AZURE_OPENAI_KEY bersama dengan AZURE_OPENAI_ENDPOINT dan AZURE_OPENAI_DEPLOYMENT mengaktifkan pembantu pembuatan laporan AI.

Saat berjalan dengan OAuth atau transport SSE, Anda mungkin perlu menyediakan registration_psk dan mengonfigurasi external_hostname atau file sertifikat HTTPS.

Tata Letak Repositori

  • delinea_mcp/ - paket yang berisi alat MCP.
  • server.py - titik masuk tipis yang mendaftarkan semuanya dengan server MCP.
  • docs/ - dokumentasi proyek dan delinea-secret-server-openapi-spec.json yang dihasilkan.
  • scripts/ - contoh pembantu termasuk manual_secret_request.py.

Pertimbangan Keamanan

Endpoint OAuth yang disertakan ditujukan untuk pengembangan dan pengujian. Rute /oauth/authorize menerima redirect_uri apa pun dan akan mengarahkan pengguna tanpa validasi. Deployment harus membatasi nilai ini ke URL panggilan balik yang disetujui; jika tidak, penyerang dapat memberikan URL berbahaya dan menangkap kode otorisasi. Lihat Open Redirection untuk latar belakang.

Catatan Rilis

Lihat docs/release_notes.md untuk ringkasan fitur terbaru dan item peta jalan.

Peta Jalan

  1. Otentikasi passthrough
  2. Dukungan transport HTTP streaming
  3. Memperluas cakupan alat di Delinea Platform dan menambahkan produk Delinea lainnya

Berkontribusi

Kontribusi sangat diterima! Silakan buka isu atau pull request untuk perbaikan apa pun. Semua kode baru harus menyertakan tes unit dan lulus rangkaian tes yang ada.

Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT.