mcp-sessionize: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Qué es

Servidor MCP (Model Context Protocol) que expone datos de eventos de Sessionize (speakers, sesiones, agenda) como herramientas y prompts para asistentes IA. Construido con Quarkus 3.33.2 + Java 25 + Quarkus MCP Server 1.13.0 (combo certificada por la doc oficial del MCP server). Se distribuye como ejecutable nativo (Mandrel) y vía npx mcp-sessionize.

Comandos

./mvnw quarkus:dev          # Dev mode (HTTP habilitado, log DEBUG, live reload)
./mvnw verify               # Build + tests (lo que corre CI)
./mvnw test                 # Solo unit tests
./mvnw package -Dnative     # Ejecutable nativo (requiere Mandrel/GraalVM)
docker build -t mcp-sessionize .   # Imagen nativa multi-stage

# Un solo test / método
./mvnw test -Dtest=SessionizeToolTest
./mvnw test -Dtest=SessionizeToolTest#findSpeaker_returnsMatch

Usar siempre el wrapper ./mvnw. CI (.github/workflows/ci.yml) ejecuta ./mvnw verify con Java 25 (temurin) y, en push a main, publica la imagen a ghcr.io.

⚠️ JAVA_HOME local: mvnw prioriza JAVA_HOME sobre el java del PATH. El proyecto requiere Java 25 (maven.compiler.release=25, module imports + el flag --sun-misc-unsafe-memory-access de .mvn/jvm.config, que solo existe desde Java 23). Si JAVA_HOME apunta a Java ≤21 el build falla con Unrecognized option. Forzar el JDK correcto, p.ej.:

JAVA_HOME="$HOME/.sdkman/candidates/java/current" ./mvnw verify   # con sdkman 25-graalce

Arquitectura

Tres capas, todas en el paquete canónico io.mcp.sessionize:

• client/SessionizeClient — interfaz REST Client de MicroProfile (@RegisterRestClient(configKey = "sessionize")) contra https://sessionize.com/api/v2/{eventId}/view/{Speakers|Sessions|GridSmart}. Fuerza headers no-cache.
• model/SessionizeModel — clase sellada con records inmutables anidados (Speaker, Session, SessionGroup, GridDay, etc.) que mapean el JSON de la API.
• tool/SessionizeTool — herramientas MCP (@Tool). Los métodos Java son getSpeakers, findSpeaker, getSessionsBySpeaker, getSessions, findSession, getSchedule, pero el nombre MCP registrado lleva prefijo de servicio vía @Tool(name = "sessionize_…") (evita colisiones con otros servers). Todas llevan @Tool.Annotations(readOnlyHint=true, idempotentHint=true, openWorldHint=true) — son de solo-lectura contra una API externa; mantener prefijo + hints al añadir tools. Las tools de listado (get_speakers, find_speaker, get_sessions, find_session) aceptan limit/offset y devuelven metadata de paginación vía el helper paginate.
• prompt/SessionizePrompt — plantillas MCP (@Prompt): event_overview, find_speaker_info, sessions_by_topic, conference_schedule, speaker_sessions, recommend_sessions.