spring-openproject-mcp-server

Servidor MCP para gestionar paquetes de trabajo de OpenProject implementado en Java.

GitHub
3

Documentación

spring-openproject-mcp-server

Servidor MCP para gestionar paquetes de trabajo de OpenProject implementado en Java. El servidor actúa como un proxy hacia tu API de OpenProject. El token de API de OpenProject del usuario se utiliza para la autenticación (¡no se almacena en el contenedor!).

Compatibilidad con OpenProject

Probado contra OpenProject 14, 15, 16.6, 17.7

Comenzar (usando LM Studio)

  1. Inicia el contenedor Docker
    docker run -d -p 0.0.0.0:8080:8080 -e OPENPROJECT_URL=https://${yourOpenProjectUrl} --tmpfs /tmp docker.io/tmskln/spring-openproject-mcp-server:latest
    o si compilaste la imagen localmente
    docker run -d -p 0.0.0.0:8080:8080 -e OPENPROJECT_URL=https://${yourOpenProjectUrl} --tmpfs /tmp spring-openproject-mcp-server:dev
  2. Ejecuta LM Studio y elige un modelo apropiado para el dominio de tu proyecto. qwen/qwen3-coder-30b funciona bien para crear épicas técnicas e historias de usuario. Para traducciones simples y refinamientos de texto, un modelo más pequeño es suficiente.
  3. Configura el archivo mcp.json de LM Studio debajo de "mcpServers":{...} y establece el token de API para el proyecto a usar (ver más abajo)
  4. Si ves "mcp/openproject-mcp" en el lado derecho, debajo de Integraciones, comienza a escribir indicaciones.
  5. Ejemplos:
    1. Indicación: "Lista todos los proyectos en OpenProject usando mcp/openproject-mcp."
    2. Indicación: "Usa mcp/openproject-mcp para obtener paquetes de trabajo del proyecto id=10 y analiza el proyecto."
    3. Indicación: "Usa mcp/openproject-mcp y traduce todas las épicas del proyecto 'MyApp' al alemán."
    4. Indicación: "Eres un asistente Ágil preciso. Ayuda con la especificación del proyecto. Usa mcp/openproject-mcp y el proyecto id=10. Añade criterios INVEST. Añade criterios de aceptación Gherkin. Añade Definición de Hecho (lista de verificación). Añade Riesgos y Mitigaciones. Metas y KPIs/OKRs medibles (SMART, incl. valores objetivo)"
    5. Indicación: "Crea 10 Épicas para una nueva WebApp que haga lo siguiente: ... Usa mcp/openproject-mcp y el proyecto 'NewWebApp'."

Docker

Encuentra la imagen más reciente en https://hub.docker.com/r/tmskln/spring-openproject-mcp-server

compilar

# convert java SBOM to optimized OCI format
docker run --rm \
  -v "./target/classes/META-INF/sbom:/work"  --platform linux/amd64 \
  cyclonedx/cyclonedx-cli \
  convert \
  --input-file /work/application.cdx.json \
  --output-file /work/application.spdx.json \
  --output-format spdxjson
  
PKG_VERSION="dev" && docker build \
 -f docker/Dockerfile \
 -t spring-openproject-mcp-server:${PKG_VERSION} \
 --attest type=sbom,generator=docker/scout-sbom-indexer:latest \
 --label org.opencontainers.image.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
 --label org.opencontainers.image.revision=$(git rev-parse HEAD) \
 --label org.opencontainers.image.version=${PKG_VERSION} \
 --platform linux/amd64,linux/arm64 \
 .

ejecutar

docker run -d -p 0.0.0.0:8080:8080 -e OPENPROJECT_URL=https://${yourOpenProjectUrl} --tmpfs /tmp spring-openproject-mcp-server:dev

{
  "mcpServers": {
    "openproject-mcp": {
      "url": "http://127.0.0.1:8080/sse",
      "headers": {
        "Authorization": "Bearer {yourOpenProjectApiToken}"
      }
    }
  }
}

Si deseas controlar el servidor OpenProject desde el cliente MCP o ejecutar contra múltiples servidores OpenProject, inicia el contenedor con -e OPENPROJECT_ALLOW_HEADER_BASE_URL=true y establece la URL del servidor en la configuración MCP:

...
      "headers": {
        "Authorization": "Bearer {yourOpenProjectApiToken}"
        "X-OpenProject-Base-Url": "https://{yourOpenProjectUrl}"
      }
...

Pruebas de Integración

mvn test -Dopenproject.container.tag=17.5.1 -Dopenproject.container.port=18080

Recuerda eliminar los volúmenes entre pruebas

TODO

  • MCP OpenProject con OTEL
  • usar resultados después de parchear JSON para evitar solicitudes GET innecesarias

SSE vs. Streamable

spring.ai.mcp.server.protocol=SSE spring.ai.mcp.server.protocol=STREAMABLE

Spring crea un bean de servidor MCP con un transporte:

  • Protocolo SSE → expone:
    • GET /sse para transmisión de servidor → cliente
    • POST /mcp/message para comunicación de cliente → servidor
  • Protocolo STREAMABLE → expone un único endpoint bidireccional (por defecto /mcp) basado en la nueva especificación HTTP streamable de MCP.

Debido a que el transporte define el cableado, los endpoints y el enrutamiento de mensajes, Spring no puede vincular dos protocolos simultáneamente.

Preguntas Frecuentes

  • ¿Por qué no se usó un cliente OpenAPI generado, sino mapeo de valores JSONNode con MapStruct?
    • El primer enfoque fue usar un cliente OpenAPI generado, pero hubo muchos problemas:
      • la generación de código con org.openapitools:openapi-generator-maven-plugin no fue totalmente limpia y requirió muchas correcciones manuales.
      • el cliente es muy estricto y fallaría ante cambios mínimos en la especificación
      • La especificación carece de valores, por ejemplo 'storyPoints' y mejorar manualmente el código generado no es aplicable
      • la compatibilidad con un rango más amplio de versiones se puede lograr mejor con mapeo directo de valores y pruebas de integración contra múltiples versiones de OpenProject

Licencia

Este proyecto está licenciado bajo la Licencia MIT – consulta el archivo LICENSE para más detalles.