MCP : Comprendre le standard pour migrer Spring efficacement

Les agents IA sont désormais intégrés à nos IDE et dans la plupart des équipes de développement. Ils savent analyser du code, expliquer des erreurs, suggérer des refactors. Mais ils hallucinent. Et dans le contexte d’une migration Spring Boot, une hallucination ne se contente pas d’être fausse — elle peut coûter des heures de débogage.

C’est ce constat qui m’a conduit à m’intéresser sérieusement au Model Context Protocol (MCP), et à construire mon propre serveur MCP spécialisé : springdocs-mcp-server.

Le problème : un LLM sans contexte, c’est une boussole sans nord

Copilot, Claude, GPT-4 — tous ont une date de coupure. Spring Boot 3, la migration javax → jakarta, les changements de l’API Spring Batch 5 : ces sujets sont soit absents, soit partiellement représentés dans leurs données d’entraînement.

Le résultat ? Des réponses plausibles mais inexactes :

Une suggestion qui utilise encore une configuration dépréciée de SpringApplication.
Un guide de migration Spring Batch qui oublie la suppression de JobBuilderFactory.
Une recette OpenRewrite qui cible la mauvaise version.

On parle de problèmes que l’on ne détecte parfois qu’à la compilation, voire au runtime.

La cause profonde : le modèle manque de contexte fiable et à jour. Il comble les lacunes avec de la vraisemblance statistique, pas avec de la documentation officielle.

MCP : donner de la mémoire longue aux agents

Le Model Context Protocol est un standard ouvert, proposé par Anthropic, qui définit comment un agent IA peut interagir avec des sources de données et des outils externes de manière structurée.

L’analogie la plus juste : MCP est à l’IA ce que LSP (Language Server Protocol) est aux IDE. Un contrat commun, des implémentations multiples, une interopérabilité réelle.

Les trois primitives MCP

Un serveur MCP expose trois types d’éléments :

Primitive	Rôle	Analogie
Tools	Actions que l’agent peut exécuter	Appels de fonctions
Resources	Données que l’agent peut lire	Fichiers / API READ
Prompts	Templates d’instructions pré-configurés	Playbooks réutilisables

Cette séparation est fondamentale. Elle permet à l’agent de choisir ce dont il a besoin plutôt que de tout recevoir en vrac dans son contexte.

springdocs-mcp-server : le retour d’expérience

Pourquoi ce serveur ?

Je travaille sur des migrations Spring Boot 2.x → 3.x et Spring Batch 4 → 5 au quotidien. J’avais besoin d’un agent capable de répondre à des questions précises en s’appuyant sur la documentation officielle Spring — pas sur ses approximations.

L’idée : construire un serveur MCP en Python avec FastMCP, déployé en local via uv, exposant des outils ciblés sur l’écosystème Spring.

Architecture du serveur

spring-mcp-server/
├── server.py                    ← Cœur FastMCP
├── tools/
│   ├── search.py                ← Recherche dans les docs Spring
│   ├── fetch_page.py            ← Récupération de contenu
│   ├── migration_guide.py       ← Guides Spring Boot / Java
│   ├── batch_migration_guide.py ← Guides Spring Batch
│   └── openrewrite.py           ← Config Maven OpenRewrite
├── resources/
│   ├── spring_registry.py       ← Modules Spring répertoriés
│   ├── migration_registry.py    ← Sources officielles migration
│   ├── breaking_changes.py      ← Breaking changes Spring Boot/Java
│   └── batch_breaking_changes.py
└── prompts/
    ├── spring_prompts.py
    ├── migration_prompts.py
    └── batch_prompts.py

La séparation est intentionnelle et reflète directement les trois primitives MCP. Chaque couche a une responsabilité unique.

Ce que le serveur expose concrètement

Tools : les outils actionnables

Les tools sont les capacités que l’agent peut invoquer à la demande. En voici les principaux :

rechercher_documentation — Recherche full-text dans les modules Spring (Framework, Boot, Data, Security, AI).
guide_migration — Génère un guide étape par étape pour les types spring-boot-2-3, java-11-21, hibernate-spring-data-jdbc, jakarta-javax.
breaking_changes_migration — Filtre les breaking changes par tags (spring-boot-3, jakarta, etc.).
guide_migration_batch — Même chose pour Spring Batch : spring-batch-4-5, spring-batch-5-52, spring-batch-java21.
config_openrewrite — Génère une configuration Maven prête à l’emploi.

Prompts : les playbooks réutilisables

C’est la partie que j’utilise le plus au quotidien. Les prompts pré-configurés permettent à l’agent de recevoir des instructions expertes sans avoir à les reformuler à chaque fois :

prompt_migrer_job_batch — Analyse un Job Spring Batch 4 et produit sa version 5 commentée.
prompt_plan_migration — Planifie une migration complète avec checklist et risques identifiés.
prompt_architecture_hexagonale — Guide la refactorisation vers une architecture hexagonale.
prompt_supprimer_hibernate — Remplace JPA/Hibernate par Spring Data JDBC ou jOOQ.

Installation et intégration avec GitHub Copilot

Le serveur tourne en local via uv avec le transport STDIO, ce qui le rend compatible avec tout client MCP : Claude Desktop, GitHub Copilot dans IntelliJ, ou Cursor.

# Démarrage du serveur
cd spring-mcp-server
uv run spring-mcp-server

Pour l’intégrer dans IntelliJ avec GitHub Copilot, il suffit d’ajouter le serveur dans la configuration MCP de l’IDE :

{
  "mcpServers": {
    "springdocs": {
      "command": "uv",
      "args": ["run", "spring-mcp-server"],
      "cwd": "/chemin/vers/spring-mcp-server"
    }
  }
}

Une fois connecté, Copilot peut invoquer les tools directement depuis le chat ou les agents.

Ce que ça change en pratique

Avant MCP, une question comme “Quels sont les breaking changes de Spring Batch 5 sur JobRepository ?” produisait une réponse approximative, mélange de vérité et d’extrapolation.

Avec le serveur MCP, l’agent :

Appelle breaking_changes_batch avec le tag job-repository.
Reçoit les changements réels, sourcés depuis la documentation officielle.
Formule une réponse ancrée dans des faits vérifiables.

La différence n’est pas anecdotique. Sur une migration Spring Batch 4 → 5, j’ai identifié en quelques minutes des changements que j’aurais mis des heures à trouver manuellement : la suppression de JobBuilderFactory et StepBuilderFactory, le passage de @EnableBatchProcessing en auto-configuration, les changements de JpaItemWriter vers JpaItemWriterBuilder.

Tester avec MCP Inspector

Avant d’intégrer le serveur dans un IDE, MCP Inspector permet de valider les tools exposés de manière interactive :

npx @modelcontextprotocol/inspector uv run spring-mcp-server

L’interface web s’ouvre sur http://localhost:5173. On y voit tous les tools disponibles, on peut les invoquer manuellement et inspecter les réponses — indispensable pour déboguer un serveur en développement.

Limites et prochaines étapes

Ce serveur est un outil local, statique. Les données de migration et les breaking changes sont encodés dans les fichiers resources/. Ce n’est pas un crawler temps réel.

Ce que j’envisage pour la suite :

Intégrer un vrai scraping de docs.spring.io au démarrage pour maintenir les données à jour.
Publier le serveur sur le registre MCP de GitHub pour le rendre installable directement depuis les IDE.
Ajouter des tools jOOQ pour accompagner la migration Hibernate → jOOQ.

Conclusion

MCP est une réponse structurée à un problème réel : les agents IA sont puissants, mais aveugles sans contexte fiable. Construire un serveur MCP spécialisé, c’est transformer l’agent généraliste en expert domaine — capable de répondre avec précision aux questions qui comptent vraiment.

Pour un développeur Java/Spring, les migrations sont des moments à haut risque. Avoir un agent qui connaît réellement les breaking changes de Spring Boot 3, qui génère des configurations OpenRewrite correctes, qui sait expliquer pourquoi JobBuilderFactory a disparu — c’est un vrai gain de fiabilité.

Le code est disponible sur GitHub.