Keel Framework / Keel/MCP / Java
Arquitectura Keel
La arquitectura Keel define la estructura técnica sobre la que se construyen los MCP Servers generados a partir del arquetipo. Está organizada por capas y componentes, separando las capacidades funcionales de las capacidades técnicas transversales proporcionadas por Keel.
Visión general
La arquitectura de Keel combina una Reference Architecture, capacidades funcionales y transversales reutilizables, y mecanismos de build & scaffolding para estandarizar el desarrollo de nuevos servidores MCP.
El siguiente diagrama muestra la visión conceptual de Keel, su relación con Spring AI como framework para la implementación de MCP y con MCP (Model Context Protocol) como protocolo de comunicación, así como el papel de Maven en el build y scaffolding de los proyectos.
Keel en el ecosistema Spring AI MCP
Un MCP Server basado en Keel se construye sobre el stack tecnológico Java / Spring Boot, utilizando Spring AI como framework para la implementación de las capacidades de MCP.
Módulos del Framework
El framework Keel está compuesto por un conjunto de módulos independientes, organizados según su responsabilidad arquitectónica. Cada módulo encapsula una capacidad técnica específica y puede evolucionar de forma independiente, manteniendo contratos y dependencias claramente definidos.
Los módulos se organizan principalmente en las siguientes áreas:
- Common — capacidades y componentes técnicos comunes.
- Adapters — integraciones con servicios y componentes externos.
- Transport — capacidades relacionadas con la seguridad, sesion/autenticacion, protocolo de transporte y la comunicación client x MCP Server.
- Observability — capacidades relacionadas con observabilidad y logging.
Esta organización permite mantener una clara separación de responsabilidades, reducir el acoplamiento entre componentes y facilitar la evolución, reutilización y composición de las capacidades proporcionadas por Keel.
El framework se apoya, además, en dependencias de terceros, como Spring AI, Spring Boot y Caffeine, cuya gestión de versiones y compatibilidad se centraliza mediante el Maven BOM (Bill of Materials) del proyecto.
Todos los módulos comparten el Group ID io.keelframework.mcp y la versión definida a nivel de proyecto, garantizando una gestión de dependencias consistente dentro del stack.
| Módulo | Artefacto | Responsabilidad / Propósito |
|---|---|---|
| 🏗️ Parent | keel-mcp-java |
Gestión centralizada de dependencias, versiones, plugins y propiedades comunes del framework. |
| 🔐 Common | keel-common-jwt |
Decodificación de JWT, verificación de firma y extracción de claims. |
| 🔑 Adapter | keel-adapter-auth-idp |
Integración con proveedores de identidad mediante OIDC, incluyendo Red Hat SSO / Keycloak, JWKS e introspección de tokens. |
| ⚡ Adapter | keel-adapter-cache-caffeine |
Abstracción de caché local basada en Caffeine, con configuración de TTL y tamaño máximo. |
| 🌐 Adapter | keel-adapter-rest-client |
Cliente HTTP estandarizado y preconfigurado para el consumo de APIs REST externas desde las Tools MCP. |
| 🛡️ Transport | keel-transport-auth |
Filtro Servlet responsable de aplicar autenticación sobre los endpoints MCP. |
| 🔄 Transport | keel-transport-session |
Gestión del contexto de sesión de transporte, incluyendo autenticación y Mcp-Session-Id, con mecanismos de creación, validación y expiración. |
| 📡 Transport | keel-transport-streamable |
Implementación del transporte MCP basado en Streamable HTTP, proporcionando el endpoint de comunicación entre clientes y servidores MCP. |
| 🌍 Transport | keel-transport-cors |
Configuración y gestión de CORS para clientes MCP basados en navegador. |
| 📊 Observability | keel-observability-logging |
Generación y estandarización de logs estructurados para facilitar la monitorización y trazabilidad del servidor MCP. |
Estructura Maven del Framework
La estructura Maven de Keel organiza los diferentes componentes del framework en módulos independientes, agrupados por responsabilidad arquitectónica. El proyecto se estructura a partir de un POM padre / BOM, que centraliza la gestión de dependencias, versiones, plugins y propiedades comunes, mientras que los módulos se agrupan en cuatro áreas principales: Common, Adapters, Transport y Observability.
keel-mcp-java/
│
├── keel-mcp-common/
│ ├── keel-common-jwt/
│ └── keel-common-exceptions/
│
├── keel-mcp-adapters/
│ ├── keel-adapter-auth-idp/
│ ├── keel-adapter-cache-caffeine/
│ └── keel-adapter-rest-client/
│
├── keel-mcp-archetype/
│
├── keel-mcp-archetype-installer/
│
├── keel-mcp-transport/
│ ├── keel-transport-auth/
│ ├── keel-transport-cors/
│ ├── keel-transport-session/
│ └── keel-transport-streamable-mvc/
│
└── keel-mcp-observability/
└── keel-observability-logging/
Requisitos del Framework
Para utilizar Keel, generar nuevos MCP Servers y compilar los módulos del framework, el entorno de desarrollo debe cumplir con los siguientes requisitos y versiones de referencia.
Los requisitos definidos a continuación corresponden a las tecnologías base sobre las que se construye Keel. Las dependencias específicas del framework, incluyendo Spring Boot, Spring AI y sus dependencias transitivas, son gestionadas y versionadas de forma centralizada mediante el Maven BOM del proyecto.
| 🏷️ Categoría | 🔧 Requisito | 📌 Versión / Detalle |
|---|---|---|
| ☕ JDK | Java Development Kit | JDK 25 |
| 🌱 Framework | Spring Boot | 4.0.6 |
| 🔌 MCP | Spring AI MCP Server spring-ai-mcp-server-webmvc |
2.0.0-M6 |
| 📦 Build | Maven | Maven 3.9+ |
Stack tecnológico
La arquitectura de Keel se construye sobre un stack tecnológico moderno basado en Java 25, Spring Boot 4 y Spring AI, utilizando MCP (Model Context Protocol) como estándar de comunicación entre clientes y servidores MCP.
Spring AI proporciona las abstracciones necesarias para implementar las capacidades MCP de forma nativa mediante anotaciones como @Tool, @Resource y @Prompt, mientras que Keel aporta la arquitectura, los módulos reutilizables y las capacidades transversales necesarias para estandarizar la construcción de MCP Servers.
La siguiente tabla resume las principales tecnologías y componentes que forman parte del stack de Keel:
| Capa | Tecnología / Componente | Responsabilidad |
|---|---|---|
| ☕ Runtime | JDK 25 · Virtual Threads | Runtime y modelo de concurrencia para las operaciones del servidor y las comunicaciones Streamable HTTP. |
| 🌱 Framework | Spring Framework 7.x · Spring Boot 4.0.6 | IoC/DI, autoconfiguración, configuración y ciclo de vida de la aplicación. |
| 🤖 MCP Framework | Spring AI 2.0.0-M6 | Proporciona las abstracciones para implementar y registrar Tools, Resources y Prompts. |
| 🔌 Protocol | Model Context Protocol (MCP) | Estándar de interacción entre clientes y servidores MCP. |
| 🌐 Transport | Streamable HTTP | Mecanismo de transporte HTTP utilizado para la comunicación entre clientes y servidores MCP. |
| 🔐 Security | Spring Security · JWT · OIDC / JWKS | Autenticación y autorización de peticiones mediante tokens JWT y validación de identidad con OIDC / JWKS. |
| 🔄 Session | MCP Session Management | Gestión del contexto técnico asociado a las sesiones de transporte MCP. |
| ⚡ Caching | Caffeine | Caché local para reducir accesos repetitivos a sistemas y servicios externos. |
| 📊 Observability | JSON Structured Logging | Estandarización de eventos TECHNICAL, FUNCTIONAL y SECURITY. |
| 🏗️ Scaffolding | Maven Archetype | Generación de proyectos MCP basados en la arquitectura y módulos de Keel. |