delinea-mcp Server

ทางการ

เซิร์ฟเวอร์ Delinea MCP อย่างเป็นทางการสำหรับ Delinea Secret Server และ Platform APIs

GitHub
46

เอกสาร

DelineaMCP

เซิร์ฟเวอร์ MCP สำหรับ Delinea Secret Server และ Platform APIs

License

คุณสมบัติ

  • การตรวจสอบสิทธิ์อัตโนมัติกับ Secret Server
  • ชุดเครื่องมือ Secret Server ที่ครอบคลุมสำหรับการจัดการโฟลเดอร์, ซีเคร็ต, ผู้ใช้, กลุ่ม และบทบาท รวมถึงตัวช่วยกล่องขาเข้าและคำขอเข้าถึง และยูทิลิตี้สำหรับเอเจนต์เขียนโค้ด
  • เครื่องมือความเข้ากันได้กับ ChatGPT (search และ fetch) สำหรับการโต้ตอบกับ AI ที่ควบคุมได้
  • เครื่องมือจัดการผู้ใช้ Delinea Platform (ไม่บังคับ)
  • รองรับโหมดการส่งข้อมูลแบบ Server Sent Events หรือ STDIO
  • OAuth 2.0 พร้อมการลงทะเบียนไคลเอนต์แบบไดนามิกตามข้อกำหนด MCP
  • รองรับ 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

การกำหนดค่า

ซีเคร็ตเช่นรหัสผ่านยังคงมาจากตัวแปรสภาพแวดล้อม ระบุ 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 - URL ฐานของอินสแตนซ์ Secret Server ของคุณ
  • platform_hostname - โฮสต์เนมผู้เช่าแพลตฟอร์ม (เปิดใช้งานเครื่องมือแพลตฟอร์ม)
  • platform_service_account - บัญชีบริการที่ใช้กับ Platform API
  • platform_tenant_id - รหัสผู้เช่าสำหรับคำขอ Platform API
  • azure_openai_endpoint - ปลายทาง Azure OpenAI เฉพาะเมื่อคุณต้องการการสร้างรายงานอัตโนมัติ (เอเจนต์ส่วนใหญ่สามารถสร้าง SQL รายงานของตนเองได้ ดังนั้นอย่าเปิดใช้งานเว้นแต่คุณต้องการ)
  • azure_openai_deployment - ชื่อการปรับใช้สำหรับ Azure OpenAI
  • auth_mode - โหมดการตรวจสอบสิทธิ์ (none หรือ oauth) แน่นอนว่า OAuth ไม่ทำงานกับการส่งข้อมูลแบบ stdio
  • transport_mode - stdio สำหรับบรรทัดคำสั่ง หรือ sse สำหรับ HTTP/SSE
  • chatgpt_disable_scope_checks - ข้ามการตรวจสอบขอบเขตในคำขอ ChatGPT เปิดใช้งานเฉพาะเมื่อคุณพบปัญหาในการเชื่อมต่อกับ ChatGPT
  • port - พอร์ตสำหรับเซิร์ฟเวอร์ HTTP ในโหมด sse
  • debug - เปิดใช้งานการบันทึกแบบละเอียด
  • external_hostname - โฮสต์เนมที่ใช้เมื่อสร้างผู้ชมโทเค็น OAuth อย่าเพิ่มคำนำหน้า HTTP(S) หรือพอร์ต
  • ssl_keyfile - พาธไปยังคีย์ SSL สำหรับ HTTPS (เช่น privkey.pem)
  • ssl_certfile - พาธไปยังใบรับรอง SSL สำหรับ HTTPS (เช่น fullchain.pem)
  • registration_psk - คีย์ที่แชร์ล่วงหน้าที่จำเป็นในการลงทะเบียนไคลเอนต์ OAuth คุณจะต้องพิมพ์ซีเคร็ตนี้ในเบราว์เซอร์ของคุณเพื่ออนุมัติการเชื่อมต่อ OAuth
  • jwt_key_path - ตำแหน่งของคู่คีย์ RSA ที่ใช้สำหรับโทเค็น OAuth ค่าเริ่มต้นคือ .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

เมื่อเริ่มต้นเซิร์ฟเวอร์จะขอโทเค็น bearer และจัดเก็บไว้สำหรับคำขอ API ในภายหลัง โปรเจกต์นี้จะถูกขยายเพื่อรวมเข้ากับ Secret Server API ต่อไป

เครื่องมือ MCP

เซิร์ฟเวอร์เปิดเผยเครื่องมือ MCP หลายตัวสำหรับการโต้ตอบกับ Secret Server:

  • run_report(sql_query, report_name=None) - สร้างและดำเนินการรายงานชั่วคราว
  • ai_generate_and_run_report(description) - สร้าง SQL โดยใช้ Azure OpenAI และรัน ต้องการตัวแปร 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) - แสดงสคริปต์สำหรับการดึงข้อมูลรับรองซีเคร็ตในเชลล์ที่ระบุ
  • check_secret_template(template_id) - ดึงรายละเอียดเทมเพลตซีเคร็ต
  • check_secret_template_field(template_id, field_id) - ตรวจสอบว่าเทมเพลตมีฟิลด์หรือไม่
  • get_secret_template_field(field_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 และส่งคืนสถานะบริการปัจจุบัน

ใช้ตัวแปรการกำหนดค่าเซิร์ฟเวอร์ที่อธิบายไว้ข้างต้นเพื่อตรวจสอบสิทธิ์ เครื่องมือ AI จะถูกปิดใช้งานโดยอัตโนมัติหากไม่มีตัวแปร Azure OpenAI เฉพาะชื่อเครื่องมือที่แสดงใน config.json เท่านั้นที่จะถูกลงทะเบียน รายการว่างจะเปิดใช้งานทุกเครื่องมือ

กรณีการใช้งาน

เอกสารประกอบครอบคลุมเวิร์กโฟลว์หลายแบบสำหรับการเชื่อมต่อเครื่องมือกับเซิร์ฟเวอร์:

เริ่มต้นใช้งาน Docker อย่างรวดเร็ว

มี Dockerfile สำหรับการรันเซิร์ฟเวอร์ MCP โดยไม่ต้องติดตั้งการพึ่งพา Python ในเครื่อง

  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

เติม config.json ด้วยชื่อผู้ใช้และ URL ของคุณตามที่แสดงด้านบน

คอนเทนเนอร์จัดเก็บ oauth.db และ jwt.json ใน /app/data เมาต์โวลุ่ม (แสดงเป็น mcp-data ด้านบน) เพื่อให้ไฟล์เหล่านี้และใบรับรอง HTTPS ใดๆ ยังคงอยู่ระหว่างการรัน

แทนที่ <https://your-secret-server/SecretServer> ด้วย URL ฐานของอินสแตนซ์ Secret Server ของคุณเพื่อหลีกเลี่ยงข้อผิดพลาดในการเชื่อมต่อ

เซิร์ฟเวอร์จะเริ่มต้นที่พอร์ต 8000 โดยค่าเริ่มต้นโดยใช้ python server.py ตั้งค่าตัวเลือก port ใน config.json เพื่อเขียนทับค่าเริ่มต้น เปิดใช้งาน debug: true เพื่อบันทึกคำขอ HTTP ขาเข้าทั้งหมด

สคริปต์ตัวอย่าง

สคริปต์ manual_secret_request.py แสดงวิธีการรับโทเค็น 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 และรีลีสถูกแท็กโดยใช้ Semantic Versioning สร้างอิมเมจ 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 ที่เป็นอันตรายและดักจับรหัสการอนุญาต ดู Open Redirection สำหรับข้อมูลพื้นฐาน

บันทึกประจำรุ่น

ดู docs/release_notes.md สำหรับสรุปคุณสมบัติล่าสุดและรายการแผนงาน

แผนงาน

  1. การตรวจสอบสิทธิ์แบบพาสทรู
  2. รองรับการส่งข้อมูล HTTP แบบสตรีมมิ่ง
  3. ขยายความครอบคลุมเครื่องมือบน Delinea Platform และเพิ่มผลิตภัณฑ์ Delinea อื่นๆ

การมีส่วนร่วม

ยินดีต้อนรับการมีส่วนร่วม! โปรดเปิด issues หรือ pull requests สำหรับการปรับปรุงใดๆ โค้ดใหม่ทั้งหมดควรมีการทดสอบหน่วยและผ่านชุดทดสอบที่มีอยู่

ใบอนุญาต

โปรเจกต์นี้ได้รับอนุญาตภายใต้ MIT License