Skycloak
ทางการเซิร์ฟเวอร์ Model Context Protocol สำหรับ Skycloak ที่จัดการ Keycloak จัดการคลัสเตอร์ รีลึม แอปพลิเคชัน SSO และผู้ใช้จากไคลเอนต์ MCP ใด ๆ
คุณทำอะไรได้บ้างด้วย Skycloak MCP?
- รายการคลัสเตอร์และสถานะการอัปเกรด — แสดงรายการคลัสเตอร์ Keycloak ของคุณ ตรวจสอบว่าคลัสเตอร์ใดล้าหลังการอัปเกรด และดูเส้นทางการอัปเกรดของแต่ละคลัสเตอร์
- การจัดการ Realm และแอปพลิเคชัน — สร้างหรืออัปเดต Realm และแอปพลิเคชัน จัดการบทบาทของแอปพลิเคชัน และหมุนเวียนข้อมูลลับของไคลเอ็นต์
- การตั้งค่าผู้ให้บริการข้อมูลระบุตัวตน — เพิ่มผู้ให้บริการข้อมูลระบุตัวตน OIDC ไปยัง Realm ทดสอบการเชื่อมต่อ และตรวจสอบการเชื่อมต่อ SSO ที่มีอยู่
- การตรวจสอบผู้ใช้และสิทธิ์การเข้าถึง — แสดงรายการผู้ใช้ บทบาท และกลุ่มใน Realm และค้นหาเหตุการณ์เพื่อดูว่าใครถูกเพิ่มหรือมีอะไรเปลี่ยนแปลงเมื่อไม่นานมานี้
- ปลายทาง SIEM และ Webhook — สร้างและทดสอบปลายทาง SIEM หรือการสมัครรับ Webhook ที่ส่งต่อเหตุการณ์ของผู้ดูแลระบบไปยังปลายทางภายนอก
- เวิร์กโฟลว์แบบมีคำแนะนำ — เรียกใช้พรอมป์ต์ เช่น
review_upgradesหรือtriage_failed_loginsซึ่งจะแนะนำให้ใช้เครื่องมือที่เหมาะสมตามลำดับ
เอกสาร
skycloak-mcp
เซิร์ฟเวอร์ Model Context Protocol อย่างเป็นทางการสำหรับ Skycloak (Keycloak แบบมีผู้จัดการดูแล): จัดการคลัสเตอร์ รีล์ม แอปพลิเคชัน และ SSO ของคุณจากไคลเอ็นต์ MCP ใดก็ได้ (Claude Desktop, Claude Code, Cursor)
สถานะ: รุ่นเริ่มต้น ขอบเขตของเครื่องมือกำลังขยาย ดูรายการที่พร้อมใช้งานได้ในบันทึกการเปลี่ยนแปลง
เริ่มต้นอย่างรวดเร็ว
claude mcp add --transport http skycloak https://mcp.skycloak.io
ไม่ต้องใช้ API key, client ID หรือการกำหนดค่าใด ๆ เบราว์เซอร์จะเปิดขึ้น ให้คุณลงชื่อเข้าใช้ Skycloak แล้วเครื่องมือต่าง ๆ จะปรากฏขึ้น ไคลเอ็นต์ MCP ใดก็ตามที่รองรับ streamable HTTP ก็ทำงานในลักษณะเดียวกัน เพียงระบุ URL ให้ไคลเอ็นต์เท่านั้น
จากนั้นลองขอให้ทำสิ่งต่าง ๆ เช่น:
- "คลัสเตอร์ Keycloak ใดของฉันที่ยังไม่ได้อัปเกรด?"
- "สร้างรีล์ม staging บนคลัสเตอร์ EU โดยให้ลงชื่อเข้าใช้ด้วย Google และ GitHub"
- "มีใครบ้างที่ถูกเพิ่มเข้ารีล์ม production ในสัปดาห์ที่ผ่านมา?"
- "ตั้งค่าปลายทาง SIEM ให้ส่งต่อเหตุการณ์ของผู้ดูแลระบบไปยัง webhook ของ Datadog"
การยืนยันตัวตนและความปลอดภัย
- Hosted HTTP พร้อม OAuth (ไม่ต้องกำหนดค่าข้อมูลรับรอง) ชี้ไคลเอ็นต์ของคุณไปที่
https://mcp.skycloak.ioโดยไม่ต้องมี header เซิร์ฟเวอร์จะตอบกลับด้วย401พร้อมตัวชี้ไปยังข้อมูลเมตา RFC 9728 ที่/.well-known/oauth-protected-resourceจากนั้นไคลเอ็นต์จะดำเนินขั้นตอน authorization-code ผ่านเบราว์เซอร์กับรีล์มเข้าสู่ระบบของ Skycloak และ access token ที่ได้รับจะถูกแลกเป็น API key อายุสั้นซึ่งจำกัดขอบเขตไว้ที่ workspace และใช้สำหรับเซสชันนั้น คีย์มีอายุหนึ่งชั่วโมงและต่ออายุโดยอัตโนมัติ ไม่มีการจัดเก็บสิ่งใดไว้ในการกำหนดค่าของไคลเอ็นต์ - Hosted HTTP พร้อม API key สร้างคีย์ใน แดชบอร์ด Skycloak แล้วส่งเป็น
Authorization: Bearer <key>(หรือAPI-Key: <key>) ทุกคำขอจะมีข้อมูลรับรองของตัวเองและดำเนินการได้เฉพาะใน workspace ของข้อมูลรับรองนั้น เซิร์ฟเวอร์ไม่เก็บสถานะเซสชัน ดังนั้นคำขอหนึ่งจะไม่รับช่วงข้อมูลจากผู้เรียกอื่น ระบบจะไม่ตรวจสอบคีย์ก่อนใช้งาน: Skycloak API เป็นผู้มีอำนาจตัดสิน ดังนั้นคีย์ที่ไม่ถูกต้องจะแสดงเป็น401เมื่อเรียกใช้เครื่องมือครั้งแรก แทนที่จะแสดงตอนเชื่อมต่อ - เครื่องมือสอดคล้องกับบทบาทของคุณ เมื่อใช้ OAuth รายการเครื่องมือจะถูกจำกัดให้เหลือเฉพาะเครื่องมือที่ขอบเขตของเซสชันอนุญาต ดังนั้นสมาชิก workspace แบบอ่านอย่างเดียวจะไม่เห็นเครื่องมือเขียนที่อาจตอบกลับด้วย
403เมื่อใช้ API key ระบบจะลงทะเบียนเครื่องมือทั้งหมด เนื่องจากเซิร์ฟเวอร์ไม่เห็นขอบเขตของคีย์ และการเรียกที่ไม่ได้รับอนุญาตจะแสดงเป็น403จาก API - Local stdio เรียกใช้
skycloak-mcp initแล้วอนุมัติผ่านเบราว์เซอร์ (ขั้นตอน device authorization ของ OAuth 2.0) ระบบจะสร้าง API key ที่จำกัดขอบเขตไว้ที่ workspace จัดเก็บไว้ใน keychain ของระบบปฏิบัติการ และตรวจหา workspace เริ่มต้นของคุณโดยอัตโนมัติ (ส่ง--workspace <id>เพื่อเลือก workspace อื่น)skycloak-mcp logoutจะลบคีย์ที่จัดเก็บไว้ - Headless / CI ตั้งค่าตัวแปรสภาพแวดล้อม
SKYCLOAK_API_KEY(สร้างคีย์ใน แดชบอร์ด Skycloak) เพื่อข้ามขั้นตอนเบราว์เซอร์ทั้งหมด คีย์นี้จะมีลำดับความสำคัญเหนือ keychain เสมอ หากไม่มีคีย์และไม่สามารถเข้าถึง keychain ได้ — เช่น ในคอนเทนเนอร์ หรือโฮสต์ที่ไม่มี Secret Service — เซิร์ฟเวอร์ stdio ก็ยังเริ่มทำงานและแสดงรายการเครื่องมือได้ เพื่อให้ไดเรกทอรีสามารถตรวจสอบข้อมูลได้ แต่การเรียกแต่ละครั้งจะล้มเหลวพร้อมข้อผิดพลาดที่ระบุวิธีส่งข้อมูลรับรองทั้งสองแบบ - การเขียนถูกควบคุมด้วยข้อมูลรับรองของคุณ ไม่ใช่แฟล็ก เซิร์ฟเวอร์ hosted ที่
https://mcp.skycloak.ioรองรับการเขียน และสิ่งที่คุณเปลี่ยนแปลงได้จริงจะขึ้นอยู่กับขอบเขตของคีย์และบทบาทใน workspace: สมาชิกแบบอ่านอย่างเดียวจะเปลี่ยนแปลงสิ่งใดไม่ได้ ไม่ว่ารายการเครื่องมือจะแสดงอะไร เพิ่ม?readonly=trueลงใน URL เพื่อบังคับให้เซสชันใช้ชุดเครื่องมือแบบอ่านอย่างเดียว ส่วนไบนารี local จะทำงานในทางกลับกัน โดยจะไม่ลงทะเบียนเครื่องมือเขียน เว้นแต่เริ่มทำงานด้วย--allow-writes - ข้อมูลรับรองคลัสเตอร์เป็นตัวเลือกที่ต้องเปิดใช้เอง
get_cluster_credentialsส่งคืนข้อมูลรับรองผู้ดูแลระบบ Keycloak ของคลัสเตอร์ ซึ่งผู้ช่วยที่ถือคีย์จะมองเห็นได้ ดังนั้นinitจึงไม่ร้องขอขอบเขตนี้เป็นค่าเริ่มต้น ให้ใช้คีย์ที่มีขอบเขตดังกล่าว โดยสร้างคีย์ในแดชบอร์ด หรือเมื่อลงชื่อเข้าใช้ผ่าน stdio ให้ใช้skycloak-mcp init --allow-credentialsหากไม่มีขอบเขตนี้ เครื่องมือจะแสดง 403 พร้อมอธิบายวิธีดำเนินการทั้งสองแบบ - เครื่องมือที่ทำลายข้อมูลต้องได้รับการยืนยัน: ตัวอย่างเช่น การลบรีล์มต้องมีอาร์กิวเมนต์
confirm=trueอย่างชัดเจน - คำขอจะถูกจำกัดอัตราตามแพ็กเกจ Skycloak ของคุณ เมื่อได้รับการตอบกลับ
429เซิร์ฟเวอร์จะแสดงRetry-After
เครื่องมือ
มีเครื่องมือ 143 รายการ: อ่านอย่างเดียว 63 รายการ และเขียน 80 รายการ เครื่องมืออ่านอย่างเดียวพร้อมใช้งานเสมอ บนเซิร์ฟเวอร์ hosted จะลงทะเบียนเครื่องมือเขียนด้วยและควบคุมการใช้งานตามขอบเขตของข้อมูลรับรอง ส่วนไบนารี local จะลงทะเบียนเครื่องมือเหล่านี้เฉพาะเมื่อเริ่มทำงานด้วย --allow-writes
ชื่อเครื่องมือจะมีคำนำหน้า skycloak_ ซึ่งตารางด้านล่างละไว้ ดังนั้น list_clusters ในไคลเอ็นต์ของคุณจึงหมายถึง skycloak_list_clusters
| หมวดหมู่ | อ่านอย่างเดียว | เขียน (--allow-writes) |
|---|---|---|
| คลัสเตอร์ | list_clusters, get_cluster, list_cluster_locations, list_cluster_types, list_cluster_features, list_cluster_versions, list_cluster_upgrades, get_cluster_upgrade_path, get_cluster_credentials, get_cluster_insights, get_cluster_maintenance_window | create_cluster, update_cluster, delete_cluster, cancel_cluster_upgrade, restart_cluster_instances, set_cluster_maintenance_window, delete_cluster_maintenance_window |
| ความปลอดภัย Edge | get_cluster_security, list_cluster_captcha_domains | update_cluster_security, add_cluster_captcha_domain, remove_cluster_captcha_domain |
| ลิงก์ส่วนตัว | get_cluster_private_link | update_cluster_private_link |
| รีล์ม | list_realms, get_realm | create_realm, update_realm, delete_realm |
| แอปพลิเคชัน | list_applications, get_application, list_application_roles, get_application_role, list_application_sessions | create_application, update_application, delete_application, create_application_role, update_application_role, delete_application_role, assign_application_role, remove_application_role, rotate_application_secret |
| ผู้ให้บริการข้อมูลประจำตัว | list_identity_providers, get_identity_provider, list_identity_provider_templates, discover_oidc | create_identity_provider (OIDC), update_identity_provider, delete_identity_provider, test_identity_provider |
| ผู้ใช้ บทบาท และกลุ่ม | list_realm_users, get_realm_user, list_realm_roles, get_realm_role, list_realm_groups, get_realm_group, list_realm_group_members, list_user_roles, list_user_groups | create_realm_user, update_realm_user, delete_realm_user, create_realm_role, update_realm_role, delete_realm_role, create_realm_group, update_realm_group, delete_realm_group, assign_realm_user_role, remove_realm_user_role, add_realm_user_to_group, remove_realm_user_from_group |
| โดเมนที่กำหนดเอง | list_domains, get_domain, list_domain_routes, get_domain_route | create_domain, verify_domain, delete_domain, create_domain_route, update_domain_route, delete_domain_route |
| แบรนด์และธีม | list_themes, get_theme, get_theme_assignment, get_client_theme_assignment, get_login_branding, get_email_branding, download_theme_content, get_theme_settings | set_theme_assignment, set_client_theme_assignment, update_theme, update_theme_content, update_theme_settings, delete_theme, upsert_login_branding, delete_login_branding, upsert_email_branding, delete_email_branding |
| ส่วนขยาย | list_extensions, list_cluster_extensions | install_extension, upgrade_extension, update_extension, uninstall_extension, delete_extension |
| SMTP | get_smtp | upsert_smtp, delete_smtp, test_smtp |
| การส่งออกและบันทึก | list_exports, get_export, get_logs, get_security_logs, query_events | create_export, delete_export, export_cluster_events |
| นำเข้าและส่งออกรีล์ม | get_realm_export, get_realm_import | create_realm_export, create_realm_import, create_realm_import_upload_url |
| SIEM | list_siem_destinations, get_siem_destination | create_siem_destination, update_siem_destination, delete_siem_destination, test_siem_destination |
| Webhook | list_webhook_event_types, list_webhook_subscriptions, get_webhook_subscription | create_webhook_subscription, update_webhook_subscription, delete_webhook_subscription, test_webhook_subscription |
| OpenFGA | list_openfga_instances, get_openfga_instance | create_openfga_instance, delete_openfga_instance |
ข้อกำหนด: เครื่องมือที่ทำลายข้อมูล (delete_*, uninstall_extension, cancel_cluster_upgrade, update_theme_content, update_theme_settings, restart_cluster_instances) ต้องใช้ confirm=true update_theme_settings เปิดหรือปิด exact_theme_names สำหรับ workspace; API key ของผู้เรียกต้องสร้างขึ้นสำหรับเจ้าของหรือผู้ดูแลระบบ workspace มิฉะนั้นจะได้รับ 403 แม้จะมี themes:write การเปิดใช้งานจะย้ายธีมที่มีอยู่ไปยังชื่อที่ให้บริการจริงแบบตรงตัวในเบื้องหลัง ธีมที่เนื้อหาถูกแทนที่ภายใต้ชื่อจริงแบบตรงตัวจะแสดง restart_required: true จาก get_theme/list_themes/update_theme_content จนกว่า restart_cluster_instances จะรีสตาร์ตอินสแตนซ์ Keycloak ของคลัสเตอร์ การรีสตาร์ตอาจเลื่อนไปทำในช่วงเวลาบำรุงรักษาของคลัสเตอร์แทนการดำเนินการทันที โดยรายงานเป็น deferred: true และหากทราบ จะระบุ next_window ด้วย create_cluster ทำงานแบบอะซิงโครนัส: ตรวจสอบ get_cluster ซ้ำจนกว่าคลัสเตอร์จะอยู่ในสถานะ available create_domain ส่งคืนระเบียน DNS ที่ลูกค้าต้องสร้าง ส่วน verify_domain จะเริ่มตรวจสอบ DNS set_theme_assignment เปิดใช้งานธีมที่กำหนดเองแยกตามประเภทธีมของ Keycloak (สตริงว่างจะรีเซ็ตเป็นค่าเริ่มต้นที่มีมาให้) update_theme_content แทนที่ไฟล์ archive ของธีมเดิม (base64 ZIP หรือ Keycloakify JAR ใน content_base64) โดยคง ID ชื่อ และการกำหนดธีมให้กับรีล์มและแอปพลิเคชันไว้ ทำให้การแก้ไขธีมไม่จำเป็นต้องลบแล้วอัปโหลดใหม่ ต้องใช้ confirm=true เนื่องจากไม่สามารถกู้คืน archive ที่ถูกเขียนทับได้ ส่วน update_theme ยังคงเปลี่ยนเฉพาะชื่อ คำอธิบาย และเวอร์ชัน ดูวิธีเรียกใช้ได้ที่ docs/theme-content-update.md update_cluster_security จะไม่เปลี่ยนการตั้งค่า CAPTCHA get_realm ส่งคืน frontend_url ของรีล์มหากมีการกำหนดไว้ และ update_realm จะตั้งค่านั้น หรือหากระบุสตริงว่างก็จะล้างค่า โดยคงการตั้งค่าอื่น ๆ ของรีล์มไว้ การเปลี่ยนค่านี้จะเปลี่ยน issuer ของรีล์ม ลิงก์ และต้นทางของ passkey API จะปฏิเสธด้วย 403 หากคลัสเตอร์ไม่ได้เป็นแบบ dedicated, ด้วย 422 สำหรับรีล์ม master หรือ URL ที่ไม่ถูกต้อง และด้วย 409 สำหรับรีล์มที่ให้บริการบนโดเมนที่กำหนดเอง เครื่องมือจะแสดงข้อความปฏิเสธตามที่ได้รับ update_cluster_private_link กำหนด Azure subscription ID ที่อนุญาตให้เชื่อมต่อกับ private link ของคลัสเตอร์และส่งคืนสถานะใหม่: รายการที่ระบุจะแทนที่รายการเดิม รายการว่างจะล้างค่า และหากไม่ระบุรายการหรือ enabled จะคงส่วนนั้นไว้ตามเดิม API จะปฏิเสธด้วย 403 เมื่อแพ็กเกจไม่มี private networking, ด้วย 422 เมื่อไซต์ของคลัสเตอร์ไม่มี Azure private link หรือ ID ไม่ใช่ GUID ที่ถูกต้อง และด้วย 409 เมื่อปิด private link ขณะที่ปิดการเข้าถึงสาธารณะอยู่ เครื่องมือจะแสดงข้อความปฏิเสธตามที่ได้รับ การนำเข้า/ส่งออกรีล์มจะย้ายการกำหนดค่าของรีล์มหนึ่งรายการ และแยกจาก create_export ซึ่งดัมป์ฐานข้อมูลของทั้งคลัสเตอร์ ทั้งสองอย่างทำงานแบบอะซิงโครนัส และ archive ของรีล์มจะเข้ารหัสเสมอ ดังนั้นต้องใช้รหัสผ่านที่ใช้ส่งออกเพื่อนำเข้ากลับอีกครั้ง สามารถนำเข้ารีล์มโดยตรงจากไฟล์ส่งออกที่มีอยู่ (source_export_id) หรือจาก archive ที่อัปโหลด (create_realm_import_upload_url, PUT แล้วตามด้วย upload_s3_key) การนำเข้าจะสร้างรีล์มใหม่และปฏิเสธหากชื่อซ้ำ แทนที่จะเขียนทับ และต้องใช้ confirm=true เนื่องจากมีการนำผู้ใช้และข้อมูลรับรองมาด้วย
อินสแตนซ์ OpenFGA: เครื่องมือ OpenFGA ทุกตัวต้องใช้ cluster_id create_openfga_instance ผูกอินสแตนซ์ OpenFGA กับ realm หนึ่งรายการของคลัสเตอร์ โดยแต่ละรีล์มมีได้ไม่เกินหนึ่งอินสแตนซ์ ระบบจะส่งคืน 403 เมื่อแพ็กเกจของ workspace ไม่มี OpenFGA หรือ workspace ใช้จำนวนอินสแตนซ์ถึงขีดจำกัดแล้ว, 409 เมื่อรีล์มมีอินสแตนซ์อยู่แล้ว และ 422 เมื่อรีล์มเป็น master, ไม่มีอยู่ หรือถูกปิดใช้งาน การทำงานเป็นแบบอะซิงโครนัส: ตรวจสอบ get_openfga_instance ซ้ำจนกว่า status จะเป็น ready หรือ failed อินสแตนซ์ยอมรับเฉพาะโทเค็นจากรีล์มนั้นที่มี audience ของอินสแตนซ์ และ get_openfga_instance จะส่งคืน api_url, issuer และ audience สำหรับเรียกใช้งาน ตัวแมปเปอร์ audience ที่เพิ่ม audience ลงในโทเค็นของรีล์มจะถูกเพิ่มใน Keycloak การแสดงรายการและการลบทำได้โดยไม่ต้องมีสิทธิ์เข้าถึง OpenFGA delete_openfga_instance ลบ deployment, route และฐานข้อมูล รวมถึงข้อมูลการอนุญาตภายใน ซึ่งไม่สามารถกู้คืนได้ อินสแตนซ์จะแสดง deleting จนกว่าจะถูกลบออกเรียบร้อย
ตำแหน่งคลัสเตอร์: location บน create_cluster และในสิ่งที่ list_clusters, get_cluster และ list_cluster_locations ส่งกลับ จะเป็นหนึ่งใน us (US East), us-west (US West), ca (Canada), eu (Europe) หรือ au (Australia) โดยไม่คำนึงถึงตัวพิมพ์เล็กหรือใหญ่ us หมายถึง US East เสมอ us-west เปิดให้เฉพาะเวิร์กสเปซที่ได้รับสิทธิ์เข้าถึงเท่านั้น: list_cluster_locations แสดงตำแหน่งทั้งหมดที่ตั้งค่า available ไว้สำหรับเวิร์กสเปซของคุณ และการสร้างคลัสเตอร์ในตำแหน่งที่คุณใช้ไม่ได้จะส่งกลับ 400 ของ API ว่า "location not available"
พรอมป์ต์
พรอมป์ต์แปดรายการช่วยให้คุณเริ่มต้นใช้งานเครื่องมือชุดนี้ได้ ไคลเอ็นต์จะแสดงพรอมป์ต์เหล่านี้เป็นคำสั่ง slash หรือการดำเนินการที่แนะนำ โดยแต่ละรายการรับอาร์กิวเมนต์ (realm, cluster, time window) และแนะนำโมเดลให้เรียกใช้เครื่องมือที่เหมาะสมตามลำดับที่ถูกต้อง
| พรอมป์ต์ | ทำอะไร |
|---|---|
audit_self_registration | ค้นหา realm ทั้งหมดที่ยังอนุญาตให้ลงทะเบียนด้วยตนเอง ในคลัสเตอร์เดียวหรือทุกคลัสเตอร์ |
review_upgrades | ตรวจหาคลัสเตอร์ที่ใช้ Keycloak เวอร์ชันเก่า และวางแผนเส้นทางการอัปเกรด |
triage_failed_logins | ดึงข้อมูลการเข้าสู่ระบบที่ล้มเหลวล่าสุดของ realm แล้วจัดกลุ่มตาม IP ต้นทาง |
review_identity_providers | แสดงการเชื่อมต่อ SSO ของ realm และตรวจสอบว่ารายการที่ระบุเปิดใช้งานอยู่หรือไม่ |
review_admin_changes | แสดงว่าใครเปลี่ยนอะไรใน realm เมื่อไม่นานมานี้ โดยเน้นการตั้งค่าการเข้าสู่ระบบและความปลอดภัย |
provision_environment | สร้างคลัสเตอร์ เพิ่ม realm และเชื่อมต่อ identity provider พร้อมยืนยันแต่ละขั้นตอน |
set_up_custom_domain | เพิ่มโดเมนที่กำหนดเอง ส่งคืนระเบียน DNS ที่ถูกต้อง ตรวจสอบยืนยัน แล้วกำหนดเส้นทางไปยัง realm |
rotate_client_secret | สร้าง client secret ใหม่ให้แอปพลิเคชัน โดยระบุผลกระทบที่อาจเกิดขึ้นก่อน |
พรอมป์ต์จะถูกจำกัดสิทธิ์เช่นเดียวกับเครื่องมือที่ระบุไว้: พรอมป์ต์สามรายการที่เปลี่ยนแปลงข้อมูลจะมีให้เฉพาะเซสชันที่เรียกใช้เครื่องมือเขียนที่อ้างถึงได้ และคำแนะนำของพรอมป์ต์จะบอกให้โมเดลยืนยันกับคุณก่อนเปลี่ยนแปลงสิ่งใด ข้อกำหนด confirm=true สำหรับเครื่องมือที่ทำลายข้อมูลยังคงมีผลเพิ่มเติมด้วย
Skills
พรอมป์ต์เป็นจุดเริ่มต้น ส่วน skill คือคู่มือปฏิบัติงานฉบับเต็มที่โมเดลโหลดเมื่อต้องการ เซิร์ฟเวอร์มี skill สี่รายการ ซึ่งให้บริการผ่านส่วนขยาย SEP-2640 Skills extension ฉบับร่าง โดยประกาศ io.modelcontextprotocol/skills ใน capabilities ตอบกลับ skills/list และ skills/get และให้บริการแต่ละ SKILL.md เป็น resource ปกติที่ skill://<name>/SKILL.md พร้อมค่าแฮช sha256 ในรายการของ resource นั้น ไดเรกทอรีปลั๊กอินของ OpenAI นำเข้า skill ในรูปแบบนี้โดยตรง
| Skill | เนื้อหา |
|---|---|
auth-incident-triage | คัดกรองปัญหา "ผู้ใช้เข้าสู่ระบบไม่ได้": แยกเหตุขัดข้องของแพลตฟอร์มออกจากการโจมตีและการเปลี่ยนแปลงการกำหนดค่า โดยใช้ events, WAF logs และสถานะคลัสเตอร์ อ่านอย่างเดียว |
enterprise-sso-rollout | เชื่อมต่อ IdP ระดับองค์กรเข้ากับ realm ตั้งแต่ต้นจนจบ: ตรวจสอบ issuer, การลงทะเบียนแอปต้นทาง, การกำหนดค่า broker, การทดสอบการเชื่อมต่อ และการตรวจสอบกับเหตุการณ์การเข้าสู่ระบบจริง |
keycloak-migration-doctor | ตรวจสอบล่วงหน้าก่อน export, import หรือย้ายข้อมูล Keycloak โดยพิจารณาสิ่งที่มักเป็นอุปสรรคซึ่งฝ่ายสนับสนุนพบจริง (นโยบายสคริปต์ เส้นทาง /auth แบบเดิม และความคาดหวังเกี่ยวกับการ export บางส่วน) และวินิจฉัยงานที่ล้มเหลวโดยอ่าน error_message จริง แทนการดูข้อความแจ้งเตือนทั่วไปบนแดชบอร์ด |
keycloak-upgrade-readiness | ประเมินความแตกต่างของเวอร์ชัน ตรวจสอบว่า Keycloak เวอร์ชันใหม่ทำให้สิ่งใดใช้งานไม่ได้ (ส่วนขยาย ธีม) และจัดลำดับการเปิดตัวในแต่ละสภาพแวดล้อม โดยใช้ export เป็นแผนย้อนกลับ |
Skill จะถูกจำกัดสิทธิ์เช่นเดียวกับเครื่องมือที่ระบุไว้: เวิร์กโฟลว์สามรายการที่ใช้เครื่องมือเขียนจะไม่เปิดให้เซสชันแบบอ่านอย่างเดียว และเซสชันที่มีขอบเขตจำกัดจะเห็นเฉพาะ skill ที่มีเครื่องมือซึ่งเซสชันนั้นใช้งานได้จริง แหล่งข้อมูลอยู่ใน internal/tools/skills/ โดยมีหนึ่งไดเรกทอรีต่อ skill ในรูปแบบมาตรฐาน Agent Skills จึงสามารถคัดลอกไปใช้ในไดเรกทอรี skills ภายในเครื่องได้โดยตรงเช่นกัน
การเชื่อมต่อ
สำหรับ HTTP แบบโฮสต์ วิธีที่ง่ายที่สุดคือ OAuth ซึ่งไม่ต้องใช้ข้อมูลรับรองใด ๆ:
claude mcp add --transport http skycloak https://mcp.skycloak.io
การเรียกครั้งแรกจะเปิดเบราว์เซอร์ ให้คุณอนุมัติบนหน้าเข้าสู่ระบบ Skycloak แล้วเครื่องมือจะปรากฏขึ้น หากคุณอยู่ในเวิร์กสเปซมากกว่าหนึ่งแห่ง ให้ระบุเวิร์กสเปซที่ต้องการ:
claude mcp add --transport http skycloak "https://mcp.skycloak.io?workspace=<workspace-id>"
หรือสร้าง API key ในแดชบอร์ด Skycloak แล้วกำหนดค่าไคลเอ็นต์ MCP ให้ส่งคีย์ดังกล่าวเป็น bearer token:
claude mcp add --transport http skycloak https://mcp.skycloak.io --header "Authorization: Bearer sk_sc_XXX"
การดำเนินการนี้จะเพิ่มรายการต่อไปนี้ลงใน .claude.json:
{
"mcpServers": {
"skycloak": {
"type": "http",
"url": "https://mcp.skycloak.io",
"headers": {
"Authorization": "Bearer sk_sc_XXX"
}
}
}
}
Gemini CLI ติดตั้งเซิร์ฟเวอร์แบบโฮสต์เป็นส่วนขยาย โดยใช้ manifest ใน repository นี้:
gemini extensions install https://github.com/sky-cloak/skycloak-mcp
Antigravity ติดตั้งเซิร์ฟเวอร์แบบโฮสต์เป็นปลั๊กอิน โดยใช้ bundle ใน plugins/skycloak/:
agy plugin install ./plugins/skycloak
Copilot CLI ติดตั้งจาก Agent Plugins manifest ที่ root ของ repository หลังจากอนุมัติรายการแล้ว:
copilot plugin install skycloak@awesome-copilot
สำหรับ stdio ภายในเครื่อง ให้ลงชื่อเข้าใช้หนึ่งครั้ง แล้วชี้ไคลเอ็นต์ไปที่ skycloak-mcp run:
skycloak-mcp init # one-time browser sign-in; stores a key in your keychain
Claude Desktop / Cursor (ภายในเครื่อง, stdio):
{
"mcpServers": {
"skycloak": {
"command": "skycloak-mcp",
"args": ["run", "--transport", "stdio"]
}
}
}
Claude Code:
claude mcp add skycloak -- skycloak-mcp run --transport stdio
สำหรับ headless / CI (ไม่มีเบราว์เซอร์) ให้ข้าม init แล้วส่งคีย์แทน: เพิ่ม "env": { "SKYCLOAK_API_KEY": "sk_sc_..." } ลงในการกำหนดค่า หรือ claude mcp add skycloak --env SKYCLOAK_API_KEY=sk_sc_... -- skycloak-mcp run --transport stdio
เพิ่ม --allow-writes เฉพาะเมื่อคุณตั้งใจจะเปลี่ยนแปลงข้อมูล (ลงชื่อเข้าใช้ด้วย skycloak-mcp init --allow-writes หรือใช้คีย์ที่มีสิทธิ์เขียน)
เพิ่ม ?readonly=true ลงใน URL ของ HTTP แบบโฮสต์เพื่อเปิดเผยเฉพาะเครื่องมืออ่านอย่างเดียวสำหรับเซสชัน HTTP นั้น หรือเพิ่ม ?readonly=false เพื่อขอใช้เครื่องมือที่เขียนข้อมูลได้ พารามิเตอร์ query มีค่าเริ่มต้นเป็น false แต่จะลงทะเบียนเครื่องมือเขียนก็ต่อเมื่อเริ่มเซิร์ฟเวอร์ด้วย --allow-writes
เพิ่ม ?workspace=<uuid> เพื่อเลือกเวิร์กสเปซที่เซสชัน OAuth จะใช้งาน จำเป็นเฉพาะเมื่อคุณอยู่ในเวิร์กสเปซมากกว่าหนึ่งแห่ง หากมีเวิร์กสเปซเดียว เซิร์ฟเวอร์จะเลือกให้โดยอัตโนมัติ และหากคุณอยู่ในหลายเวิร์กสเปซแต่ไม่ได้ระบุ ระบบจะยกเลิกการเชื่อมต่อพร้อมข้อความที่แสดงรายการเวิร์กสเปซเหล่านั้น
การเรียกใช้ HTTP transport
skycloak-mcp run --transport http --http-addr :8080
ไม่จำเป็นต้องมีข้อมูลรับรองของตัวเอง: ผู้เรียกจะส่งข้อมูลรับรองมาในแต่ละคำขอ จึงไม่ต้องแทรกข้อมูลใด ๆ ขณะ deploy GET /healthz และ GET /readyz ไม่ต้องยืนยันตัวตนและรายงานเพียงว่าโปรเซสทำงานอยู่ โดยตั้งใจไม่ตรวจสอบ Skycloak API เพื่อไม่ให้ปัญหาชั่วคราวของระบบต้นทางทำให้การตรวจสอบของทุก replica ล้มเหลวพร้อมกัน เซิร์ฟเวอร์ไม่เก็บสถานะเซสชัน จึงไม่จำเป็นต้องกำหนด session affinity ให้ replica และสามารถปรับขนาดหรือเริ่มใหม่ได้อย่างอิสระ SIGTERM จะหยุดรับการเชื่อมต่อใหม่และรอให้การเรียกที่กำลังดำเนินการอยู่เสร็จสิ้น
เส้นทาง OAuth จะเปิดใช้งานเมื่อกำหนด SKYCLOAK_ISSUER และ SKYCLOAK_DASHBOARD_URL ซึ่งเป็นค่าเริ่มต้นอยู่แล้ว จากนั้นจะให้บริการ GET /.well-known/oauth-protected-resource โดยไม่ต้องยืนยันตัวตน และระบุ realm เป็น authorization server ค่า resource จะใช้ค่าจาก SKYCLOAK_PUBLIC_URL หากมีการกำหนดไว้ มิฉะนั้นจะใช้ Host และ scheme ของคำขอเอง ดังนั้นการ deploy บนโฮสต์เดียวหลัง ingress จึงไม่ต้องกำหนดค่าเพิ่มเติม scheme จะใช้ค่าจาก X-Forwarded-Proto หากมี มิฉะนั้นจะใช้ https สำหรับโฮสต์ที่ไม่ใช่ loopback เนื่องจาก TLS สิ้นสุดที่ระบบต้นทาง และการเผยแพร่ตัวระบุ http:// จะไม่ตรงกับ URL ที่ไคลเอ็นต์เชื่อมต่อมา ให้ตั้งค่า SKYCLOAK_PUBLIC_URL หาก ingress ของคุณเขียน Host ใหม่ เอกสารนี้ยังระบุ openid profile email เป็น scopes_supported และ challenge ของ WWW-Authenticate จะส่งค่าเหล่านี้ซ้ำเป็นพารามิเตอร์ scope ดังนั้นไคลเอ็นต์ที่อ่านค่าใดค่าหนึ่งจะร้องขอค่าเหล่านี้จาก realm: จำเป็นต้องมี openid เพราะการแลกเปลี่ยน token ทำให้แดชบอร์ดเรียก userinfo endpoint ของ Keycloak และ Keycloak จะปฏิเสธ token ที่ออกให้โดยไม่มีค่านี้ หาก token ที่ได้รับไม่มีค่านี้ ระบบจะปฏิเสธระหว่างการตรวจสอบพร้อม 401 และ challenge แทนที่จะส่งต่อไปยังการแลกเปลี่ยนที่ไม่มีทางสำเร็จ ทำให้ไคลเอ็นต์ที่ยังถือ grant จากก่อนหน้านี้หยุดลองซ้ำและลงชื่อเข้าใช้อีกครั้ง การล้างค่าตัวแปร issuer หรือ dashboard ตัวใดตัวหนึ่งจะปิด OAuth ทั้งหมด และเซิร์ฟเวอร์จะกลับไปขอ API key เท่านั้น
OPENAI_APPS_CHALLENGE_TOKEN ให้บริการ token ยืนยันโดเมนของไดเรกทอรีปลั๊กอิน OpenAI
ที่ /.well-known/openai-apps-challenge โดยส่งเป็นข้อความธรรมดาเท่านั้น หากไม่ได้ตั้งค่า
จะไม่มีการลงทะเบียน route และ path ดังกล่าวจะตอบกลับ 404
เมื่อเริ่มทำงาน ระบบจะบันทึกหนึ่งบรรทัดพร้อมการเชื่อมต่อที่ตรวจพบ (oauth=, issuer=, dashboard=, public_url=, endpoint=, allow_writes=) เพื่อให้ตรวจพบการ deploy ที่กำหนดค่าผิดได้โดยไม่ต้อง deploy ใหม่ ทุกคำขอที่ถูกปฏิเสธบนเส้นทาง OAuth จะบันทึกหนึ่งบรรทัดซึ่งระบุขั้นตอนที่ล้มเหลว (verify, exchange หรือ scopes), สถานะที่ผู้เรียกได้รับ และข้อผิดพลาดต้นเหตุ หากการตรวจสอบล้มเหลว จะเพิ่มรายการตรวจสอบที่ปฏิเสธ token (expired, wrong_issuer, bad_signature, unknown_key_id, wrong_token_type, no_openid_scope และอื่น ๆ); หากการแลกเปลี่ยนล้มเหลว จะเพิ่มสถานะของแดชบอร์ดและโฮสต์ที่เรียก ผู้เรียกจะแสดงเป็น subject ของ token หลังจากตรวจสอบยืนยันแล้ว และจะไม่แสดงเป็นข้อมูลรับรอง: access token, ส่วนหัว Authorization และ API key ที่สร้างขึ้นจะไม่ถูกบันทึกลง log
สิ่งที่เซิร์ฟเวอร์ส่งไปยัง Skycloak API
เซิร์ฟเวอร์แบบโฮสต์และไบนารีภายในเครื่องส่งส่วนหัวเดียวกันไปยัง Skycloak API (SKYCLOAK_ENDPOINT):
| ส่วนหัว | ค่า | เหตุผล |
|---|---|---|
API-Key | API key ของคุณหรือคีย์ที่สร้างให้เซสชัน | ใช้ยืนยันคำขอ |
API-Version | SKYCLOAK_API_VERSION | กำหนด API contract ที่เซิร์ฟเวอร์สร้างขึ้นให้แน่นอน |
User-Agent | skycloak-mcp/<version> | ระบุไคลเอ็นต์ |
X-MCP-Tool | ชื่อที่ลงทะเบียนของเครื่องมือ เช่น skycloak_list_realms | ระบุว่าเครื่องมือใดเป็นผู้ส่งคำขอ |
X-MCP-Call-Id | UUID แบบสุ่มที่สร้างขึ้นหนึ่งครั้งต่อการเรียกเครื่องมือ | จัดกลุ่มคำขอทั้งหมดของการเรียกหนึ่งครั้ง |
จะส่ง X-MCP-Tool และ X-MCP-Call-Id เฉพาะในคำขอที่เกิดขึ้นระหว่างให้บริการการเรียกเครื่องมือเท่านั้น การเรียกหนึ่งครั้งอาจส่งคำขอหลายรายการ เช่น หนึ่งครั้งต่อคลัสเตอร์เมื่อไม่ได้ระบุ cluster_id และส่งอีกครั้งเมื่อมีการลอง 429 หรือ 5xx ใหม่ โดยคำขอทั้งหมดจะใช้ ID ของการเรียกเดียวกัน Skycloak ใช้คู่นี้นับความถี่ในการใช้เครื่องมือแต่ละรายการ ซึ่งช่วยให้เราทราบว่าควรปรับปรุง จัดทำเอกสาร หรือเลิกใช้เครื่องมือใด ค่านี้ไม่มีอาร์กิวเมนต์ ผลลัพธ์ หรือข้อมูลเกี่ยวกับคุณนอกเหนือจากที่ API key ระบุอยู่แล้ว และจะส่งไปยัง Skycloak API เท่านั้น ไม่ส่งไปยังคลัสเตอร์ Keycloak ของคุณหรือที่อื่น คำขอที่เกิดขึ้นนอกการเรียกเครื่องมือ เช่น การลงชื่อเข้าใช้และการสร้าง API key จะไม่มีค่านี้ทั้งคู่
การกำหนดค่า
| Env var | ค่าเริ่มต้น |
|---|---|
SKYCLOAK_API_KEY | ไม่มี (ไม่บังคับสำหรับ stdio; ไคลเอ็นต์ HTTP ส่งส่วนหัว API-Key แทน) |
SKYCLOAK_ENDPOINT | https://api.skycloak.io |
SKYCLOAK_API_VERSION | เวอร์ชัน API ปัจจุบัน |
SKYCLOAK_ISSUER | https://login.app.skycloak.io/realms/skycloak (การลงชื่อเข้าใช้ CLI และ authorization server ที่ HTTP transport ใช้ตรวจสอบ token) |
SKYCLOAK_CLIENT_ID | skycloak-mcp (เฉพาะ device flow ของ CLI) |
SKYCLOAK_DASHBOARD_URL | https://app.skycloak.io (สร้างคีย์สำหรับ CLI และคีย์สำหรับเซสชัน HTTP) |
SKYCLOAK_PUBLIC_URL | ไม่มี (อนุมานจากแต่ละคำขอ; ตั้งค่าเมื่อ ingress เขียน Host ใหม่) |
OPENAI_APPS_CHALLENGE_TOKEN | ให้บริการ token ยืนยันของไดเรกทอรีปลั๊กอิน OpenAI ที่ /.well-known/openai-apps-challenge หากไม่ได้ตั้งค่า path ดังกล่าวจะตอบกลับ 404 |
คำสั่ง: init (ลงชื่อเข้าใช้ผ่านเบราว์เซอร์), run (ให้บริการ), logout (ลบคีย์ที่จัดเก็บไว้) init รองรับ --workspace <id>, --allow-writes, --allow-credentials และ --ttl-days (ค่าเริ่มต้น 90)
| Flag | ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|
--transport | stdio | stdio หรือ http |
--http-addr | :8080 | ที่อยู่สำหรับรับฟังของ HTTP transport |
--allow-writes | false | เปิดใช้เครื่องมือที่เปลี่ยนแปลงข้อมูลสำหรับ stdio และอนุญาตให้เซสชัน HTTP ที่ใช้ readonly=false ลงทะเบียนเครื่องมือเขียน |
การพัฒนา
make build # build the server binary
make test # unit tests
make run # run on stdio for local testing
make inspector # MCP Inspector against the local binary
make lint # golangci-lint
make generate # regenerate the API client from the OpenAPI spec
ไคลเอ็นต์ API ใน internal/apiclient สร้างขึ้นจากข้อกำหนด Skycloak OpenAPI
ด้วย oapi-codegen
การซิงค์ให้ตรงกับ API
ไคลเอนต์ใน internal/apiclient สร้างจาก internal/apiclient/openapi.yaml ด้วย oapi-codegen; เรียกใช้ make generate เพื่ออัปเดต CI จะล้มเหลวหากโค้ดที่สร้างและคอมมิตไว้ไม่ตรงกับสเปก คำขอจะลองใหม่เมื่อเกิด 429/5xx โดยใช้การหน่วงเวลาระหว่างการลองใหม่ที่คำนึงถึง Retry-After
การเผยแพร่
เผยแพร่เป็นไบนารีบน GitHub และอิมเมจคอนเทนเนอร์ ghcr.io/sky-cloak/skycloak-mcp ในแต่ละแท็ก และเผยแพร่ไปยัง MCP Registry ในชื่อ io.skycloak/skycloak-mcp คนส่วนใหญ่ไม่จำเป็นต้องใช้ทั้งสองอย่าง เพราะเซิร์ฟเวอร์ที่โฮสต์ไว้ไม่ต้องติดตั้ง
ชุดปลั๊กอิน
plugins/skycloak/ คือโฟลเดอร์เดียวที่รองรับไคลเอนต์สองตัว ได้แก่ .antigravity-plugin/plugin.json พร้อม mcp_config.json สำหรับ Antigravity และ .claude-plugin/plugin.json สำหรับ Claude ทั้งสองตัวเชื่อมต่อกับเซิร์ฟเวอร์ที่โฮสต์ไว้และมาพร้อมสกิลทั้งสี่ ซึ่งเป็นสำเนาที่เหมือนกันทุกไบต์ของ internal/tools/skills/ เนื่องจากตัวติดตั้งได้รับเพียงโฟลเดอร์นั้น
plugin.json และ mcp.json ที่รูทของรีโพซิทอรีคือไฟล์ manifest รูปแบบ Agent Plugins v1.0.0 ที่มาร์เก็ตเพลส awesome-copilot ของ GitHub อ่าน รูปแบบดังกล่าวไม่อนุญาตให้มีฟิลด์โลโก้ ดังนั้นโลโก้ที่แสดงในรายการจึงระบุไว้ใน extensions["com.github.copilot"]
ฟิลด์ version ใน manifest เหล่านั้นและใน .grok-plugin/plugin.json จะถูกกำหนดจากแท็กรีลีสโดย CI เนื่องจากรายการในไดเรกทอรีติดตาม main ส่วน หัวข้อการอัปเดตไดเรกทอรี ใน README ของปลั๊กอินอธิบายเรื่องนี้ไว้
ความปลอดภัย
โปรดรายงานช่องโหว่เป็นการส่วนตัว ดู SECURITY.md
ผู้มีส่วนร่วม
พัฒนาที่ Skycloak โดย Guilliano Molaire, Neville Omangi และ Aphilas ประวัติของรีโพซิทอรีถูก รวมเป็นชุดเดียวเมื่อเปิดให้สาธารณะ จึงไม่สามารถดูได้จากบันทึกคอมมิตว่าใครเขียนส่วนใด
สัญญาอนุญาต
Apache-2.0 คำอธิบาย OpenAPI ใน internal/apiclient/openapi.yaml สร้างจาก API แพลตฟอร์มของ Skycloak และเป็นลิขสิทธิ์ของ Skycloak; รวมไว้ที่นี่เพื่อให้สร้างและตรวจสอบไคลเอนต์ได้ ดู NOTICE