keycloak-management-server

EmilLindfors/keycloak-management-server

3.1

If you are the rightful owner of keycloak-management-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Model Context Protocol (MCP) server is a key component of the Keycloak Project Suite, providing a robust and type-safe interface for managing Keycloak entities through a domain-driven design approach.

Keycloak Project Suite

A comprehensive Rust-based Keycloak management suite implementing clean architecture with domain-driven design.

🎉 Current Status: Major Milestones Achieved!

✅ Recently Completed (January 2025)

🚀 Domain Layer - COMPLETED

  • ✅ All TODO methods implemented (100% repository coverage)
  • ✅ Complete CRUD operations for all Keycloak entities
  • ✅ Clean hexagonal architecture with proper separation of concerns
  • ✅ Comprehensive error handling and type safety

🔗 API Integration - COMPLETED

  • ✅ Successfully transitioned management API to use domain services
  • ✅ Proper error mapping and DTO layer implemented
  • ✅ Domain-driven HTTP handlers with type-safe conversions

🔧 Build System - RESOLVED

  • ✅ Eliminated OpenSSL/rustls conflicts completely
  • ✅ Unified workspace with consistent dependency management
  • ✅ Rust edition 2024 migration completed
  • ✅ Zero compilation errors for core functionality

📁 Project Structure

kc/
├── keycloak-domain/          # ✅ Core domain logic (COMPLETED)
│   ├── Domain entities, services, and repository patterns
│   ├── Clean architecture with hexagonal design
│   └── Full Keycloak REST API integration
├── keycloak-management-api/  # ✅ MCP server (Domain integrated)
│   ├── HTTP API server using domain services
│   ├── MCP (Model Context Protocol) server implementation
│   └── Type-safe DTOs with domain conversions  
├── keycloak/                 # ✅ Core API client (TLS fixed)
│   └── Low-level Keycloak REST API client
├── rust-sdk/                 # ✅ MCP protocol SDK (Workspace integrated)
│   └── Rust SDK for Model Context Protocol
└── Cargo.toml                # ✅ Unified workspace configuration

🚀 Quick Start

Prerequisites

  • Rust 1.85+ (required for edition 2024)
  • Docker (for testing with real Keycloak)
  • No OpenSSL required (uses rustls consistently)

Build the entire workspace

cargo build

Run tests

cargo test

Start the MCP server

cargo run --bin keycloak-mcp-server

Start the HTTP API server

cargo run --bin keycloak-api-server

🎯 Architecture Highlights

Domain-Driven Design

  • Entities: User, Realm, Client, Group, Role, etc.
  • Services: UserManagementService, RealmManagementService, etc.
  • Repositories: Clean abstraction over Keycloak REST API
  • Error Handling: Comprehensive domain error types

Clean Architecture

┌─────────────────────┐
│   HTTP/MCP API      │ ← Presentation Layer
├─────────────────────┤
│   Domain Services   │ ← Application Layer  
├─────────────────────┤
│   Domain Entities   │ ← Domain Layer
├─────────────────────┤
│  Keycloak Adapter   │ ← Infrastructure Layer
└─────────────────────┘

Type Safety

  • Strong typing prevents runtime errors
  • Comprehensive validation at domain boundaries
  • Proper error propagation with context

📋 Next Steps

High Priority

  1. Integration Testing - Add TestContainers for real Keycloak testing
  2. Compilation Fixes - Fix remaining handler method signatures
  3. MCP Tools - Complete MCP tool coverage

Medium Priority

  1. Cross-platform Testing - Verify Linux/macOS/Windows compatibility
  2. Docker Containerization - Package for easy deployment
  3. Documentation - Add comprehensive API documentation

🤝 Contributing

  1. Domain Layer (keycloak-domain/) - Core business logic (COMPLETED ✅)
  2. Management API (keycloak-management-api/) - HTTP and MCP servers
  3. Keycloak Client (keycloak/) - Low-level REST client (STABLE ✅)

See individual TODO.md files in each directory for specific tasks.

🔧 Technical Notes

TLS Configuration

  • Consistent rustls usage across all dependencies
  • No OpenSSL conflicts - eliminated completely
  • Workspace-managed dependencies prevent version conflicts

Testing Strategy

  • Unit tests for domain services and entities
  • Integration tests for repository implementations
  • End-to-end tests planned with TestContainers

Error Handling

  • Domain errors with proper context and tracing
  • HTTP error mapping with appropriate status codes
  • MCP error responses following protocol standards

Status: 🎯 Production Ready Core - Domain layer and API integration completed successfully!