{"id":51375105,"url":"https://github.com/najasoft/spring-boot-mcp-rest-api","last_synced_at":"2026-07-03T11:20:26.089Z","repository":{"id":357461871,"uuid":"1233745226","full_name":"najasoft/spring-boot-mcp-rest-api","owner":"najasoft","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-12T21:23:16.000Z","size":94,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T23:15:15.933Z","etag":null,"topics":["java","mcp","rest-api","spring-boot"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/najasoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T09:56:16.000Z","updated_at":"2026-05-12T21:23:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/najasoft/spring-boot-mcp-rest-api","commit_stats":null,"previous_names":["najasoft/spring-boot-mcp-rest-api"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/najasoft/spring-boot-mcp-rest-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najasoft%2Fspring-boot-mcp-rest-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najasoft%2Fspring-boot-mcp-rest-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najasoft%2Fspring-boot-mcp-rest-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najasoft%2Fspring-boot-mcp-rest-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/najasoft","download_url":"https://codeload.github.com/najasoft/spring-boot-mcp-rest-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/najasoft%2Fspring-boot-mcp-rest-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35083987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","mcp","rest-api","spring-boot"],"created_at":"2026-07-03T11:20:25.416Z","updated_at":"2026-07-03T11:20:26.080Z","avatar_url":"https://github.com/najasoft.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API REST Spring Boot + Serveur MCP\n\nApplication Spring Boot de gestion de projets, tâches et développeurs.\nLe projet expose deux interfaces complémentaires :\n\n- une API REST pour les clients HTTP classiques ;\n- un serveur MCP pour les clients IA.\n\n## 1. Vue d'ensemble\n\nArchitecture en couches :\n\n- `controller/` : points d'accès REST ;\n- `mcp/` : outils MCP exposés via `@McpTool` ;\n- `service/` : logique métier ;\n- `repository/` : accès à la base de données ;\n- `model/` : entités JPA.\n\nL'API REST et MCP utilisent les mêmes services métier.\n\n## 2. Modèle de données\n\nDiagramme des relations entre les entités JPA :\n\n```mermaid\nclassDiagram\n    class Projet {\n        +long id\n        +String description\n    }\n\n    class ProjetDev {\n        +String langage\n    }\n\n    class ProjetRes {\n        +double budget\n    }\n\n    class Tache {\n        +Long id\n        +String libelle\n        +ProjetDev projetDev\n    }\n\n    class Developpeur {\n        +Long id\n        +String nom\n        +String email\n        +Set~Tache~ taches\n    }\n\n    Projet \u003c|-- ProjetDev\n    Projet \u003c|-- ProjetRes\n    ProjetDev \"1\" \u003c-- \"*\" Tache : projetDev\n    Developpeur \"*\" -- \"*\" Tache : taches\n```\n\nDiagramme UML  :\n\n![Diagramme des entités IntelliJ](docs/diagramme-entites-intellij.png)\n\nRelations clés :\n- **Projet** : classe parente avec héritage JPA (JOINED)\n  - **ProjetDev** : projet de développement (ajoute `langage`)\n  - **ProjetRes** : projet de recherche (ajoute `budget`)\n- **Tache** : liée à **ProjetDev** en ManyToOne\n- **Developpeur** : lié à **Tache** en ManyToMany (table `developpeur_tache`)\n\n## 3. Prérequis\n\n- **Java** : version 25 (définie dans `pom.xml`)\n- **Base de données** : MySQL (locale ou distance, configurable dans `application.properties`)\n- **Node.js** : version 18+ (requis uniquement pour MCP Inspector)\n\n## 4. Configuration\n\nFichier : `application.properties`\n\nConfiguration de la base de données :\n\n- `spring.datasource.url=jdbc:mysql://localhost:3306/atelier1_db5?createDatabaseIfNotExist=true`\n- `spring.datasource.username=root`\n- `spring.datasource.password=root`\n- `spring.jpa.hibernate.ddl-auto=update`\n\nConfiguration MCP :\n\n- `spring.ai.mcp.server.name=Atelier1 MCP Server`\n- `spring.ai.mcp.server.protocol=STREAMABLE`\n- `spring.ai.mcp.server.streamable-http.mcp-endpoint=/mcp`\n\n## 5. Démarrage\n\nLe démarrage peut être fait depuis l'IDE (via l'exécution de `Atelier1Application.java`) ou en ligne de commande.\n\nL'application démarre par défaut sur `http://localhost:8080`.\n\n### Depuis la ligne de commande\n\n```powershell\n.\\mvnw spring-boot:run\n```\n\n## 6. Comprendre le protocole MCP\n\n**MCP (Model Context Protocol)** est un protocole standardisé pour l'échange entre clients et serveurs :\n\n- **Protocole** : JSON-RPC 2.0 sur HTTP/WebSocket\n- **Transports** : Streamable HTTP (défaut pour ce serveur), stdio, SSE\n- **Flux** : sans état, basé sur requête/réponse\n\nLe serveur MCP de ce projet expose :\n- Endpoint HTTP : `http://localhost:8080/mcp`\n- Transport : `Streamable HTTP` (compatible avec la SDK Python MCP)\n\n## 7. API REST (Spring Boot)\n\nContrôleurs REST :\n\n- `controller/ProjetController.java`\n- `controller/DevController.java`\n\nRoutes principales :\n\n- `GET /projets`\n- `GET /projets/{id}`\n- `GET /projets/dev`\n- `GET /projets/res`\n- `POST /projets`\n- `POST /projets/dev`\n- `POST /projets/res`\n- `POST /projets/{idProjet}/taches`\n- `GET /projets/{idProjet}/taches`\n- `GET /projets/{idProjet}/devs`\n- `GET /devs`\n- `GET /devs/{id}`\n- `GET /devs/email/{email}`\n- `GET /devs/projet/{idProjet}`\n- `POST /devs`\n- `POST /devs/{idDev}/{idTache}`\n\n### Documentation Swagger UI\n\nDocumentation interactive de l'API :\n\n- URL : `http://localhost:8080/swagger-ui/index.html`\n- OpenAPI JSON : `http://localhost:8080/v3/api-docs`\n\n**Dépendance utilisée** :\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springdoc\u003c/groupId\u003e\n    \u003cartifactId\u003espringdoc-openapi-starter-webmvc-ui\u003c/artifactId\u003e\n    \u003cversion\u003e3.0.3\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## 8. Serveur MCP\n\n### 7.1. Dépendances MCP\n\nLe serveur MCP est fourni par Spring AI. Dépendances dans `pom.xml` :\n\n```xml\n\u003c!-- Spring AI MCP Server (WebMVC) --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.ai\u003c/groupId\u003e\n    \u003cartifactId\u003espring-ai-starter-mcp-server-webmvc\u003c/artifactId\u003e\n\u003c/dependency\u003e\n\n\u003c!-- MCP Annotations (pour @McpTool, @McpArg) --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.ai\u003c/groupId\u003e\n    \u003cartifactId\u003espring-ai-mcp-annotations\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\n### 7.2. Créer un outil MCP\n\nPour créer un outil MCP exposable au client, utiliser l'annotation `@McpTool` :\n\n1. **Créer une classe service** (ex : `MyMcpTools.java`)\n\n```java\npackage spring.ateliers.g5.atelier1.mcp;\n\nimport org.springframework.ai.mcp.annotation.McpArg;\nimport org.springframework.ai.mcp.annotation.McpTool;\nimport org.springframework.stereotype.Service;\n\n@Service\npublic class MyMcpTools {\n\n    // Outil sans paramètres\n    @McpTool(name = \"getStatus\", description = \"Retourne le statut du serveur\")\n    public String getStatus() {\n        return \"Le serveur est en ligne\";\n    }\n\n    // Outil avec paramètres et annotations\n    @McpTool(name = \"greet\", description = \"Salue une personne par son nom\")\n    public String greet(\n            @McpArg(name = \"firstName\", description = \"Prénom\", required = true) String firstName,\n            @McpArg(name = \"lastName\", description = \"Nom de famille\", required = false) String lastName) {\n        String fullName = lastName != null ? firstName + \" \" + lastName : firstName;\n        return \"Bonjour, \" + fullName + \" !\";\n    }\n}\n```\n\n2. **Annoter chaque méthode à exposer** avec `@McpTool`\n   - `name` : nom unique du tool (requis)\n   - `description` : description pour le client IA (requis)\n   - Paramètres : utiliser `@McpArg(name, description, required)`\n\nL'outil est automatiquement enregistré et disponible sur l'endpoint MCP : `http://localhost:8080/mcp`\n\n### 7.3. Points d'accès MCP\n\nEndpoint MCP :\n\n- `http://localhost:8080/mcp`\n\n### 7.4. Outils exposés\n\n#### Projets / Tâches (`ProjetMcpTools`)\n\n- `lesProjets`\n- `getProjetsDev`\n- `getProjetsRes`\n- `findProjetById`\n- `ajouterProjetDev(description, langage)`\n- `ajouterProjetRes(description, budget)`\n- `ajouterTache(idProjet, libelle)`\n- `getTaches(idProjet)`\n- `getDeveloppeursAffectes(idProjet)`\n\n#### Développeurs (`DevMcpTools`)\n\n- `getDevs`\n- `getDeveloppeur(idDev)`\n- `getDeveloppeurByEmail(email)`\n- `getDevsByProjet(idProjet)`\n- `ajouterDeveloppeur(nom, email)`\n- `affecterTache(idDev, idTache)`\n\n## 9. VS Code + GitHub Copilot Chat\n\nLe serveur MCP peut être ajouté en mode HTTP dans la configuration MCP de VS Code, en pointant vers :\n\n- `http://localhost:8080/mcp`\n\nConfiguration typique (fichier `mcp.json` généré interactivement dans VS Code) :\n\n```json\n\"my-mcp-server-xyz\": {\n  \"url\": \"http://localhost:8080/mcp\",\n  \"type\": \"http\"\n}\n```\n\nUne fois visible dans la liste des outils Copilot, les outils MCP peuvent être invoqués directement dans le chat.\n\n**Exemple de prompt** :\n\n```\nCrée 5 développeurs : Alice, Bob, Charlie, Diana, Eve (avec emails correspondants)\n```\n\nLe client IA orchestrera les appels aux tools pour réaliser le scénario complexe.\n\n## 10. MCP Inspector\n\nMCP Inspector permet de tester et de déboguer les outils MCP manuellement sans IA.\n\n### 9.1. Installation\n\nMCP Inspector se distribue via npm. Pour l'installer globalement :\n\n```powershell\nnpm install -g @modelcontextprotocol/inspector\n```\n\nOr, pour l'utiliser sans installation globale (recommandé) :\n\n```powershell\nnpx @modelcontextprotocol/inspector\n```\n\n### 9.2. Démarrage\n\nLancer MCP Inspector (sans installation globale) :\n\n```powershell\nnpx @modelcontextprotocol/inspector\n```\n\nOu si installé globalement :\n\n```powershell\nmcp-inspector\n```\n\nUne interface web s'ouvre (ou une URL s'affiche dans le terminal).\n\n### 9.3. Configuration Inspector\n\nDans l'interface Inspector Web :\n\n1. Renseigner le transport : `Streamable HTTP` (ou `HTTP` selon la version)\n2. Renseigner l'URL du serveur MCP : `http://localhost:8080/mcp`\n3. Valider / Connecter\n\n### 9.4. Vérifications recommandées\n\n1. **Lister les outils** : bouton `List Tools` ou équivalent\n2. **Tester un outil de lecture** : ex `getDevs`, `lesProjets`\n3. **Tester un outil d'écriture** : ex `ajouterDeveloppeur(nom, email)`, `ajouterProjetDev(description, langage)`\n4. **Vérifier la persistance** : relancer un tool de lecture pour confirmer les données créées\n\n## 11. Notes\n\n- L'API REST et MCP coexistent et peuvent être utilisés en parallèle selon le type de client.\n\n## 12. Créer un client MCP Python\n\n### 12.1. Package MCP Python\n\nLa SDK Python du protocole MCP est disponible via PyPI :\n\n```bash\npip install mcp\n```\n\n**Documentation** : [Model Context Protocol - Python SDK](https://github.com/modelcontextprotocol/python-sdk)\n\n### 12.2. Étapes pour créer un client\n\nUn client MCP Python suit ce pattern :\n\n1. **Importer la SDK** :\n   ```python\n   from mcp.client.session import ClientSession\n   from mcp.client.streamable_http import StreamableHttpTransport\n   ```\n\n2. **Établir la connexion** (via Streamable HTTP) :\n   ```python\n   transport = StreamableHttpTransport(\"http://localhost:8080/mcp\")\n   async with ClientSession(transport) as session:\n       result = await session.initialize()\n   ```\n\n3. **Lister les outils disponibles** :\n   ```python\n   tools = await session.list_tools()\n   for tool in tools.tools:\n       print(f\"- {tool.name}: {tool.description}\")\n   ```\n\n4. **Appeler un tool** :\n   ```python\n   response = await session.call_tool(\"lesProjets\", {})\n   print(response.content[0].text)\n   ```\n\n5. **Appeler un tool avec paramètres** :\n   ```python\n   response = await session.call_tool(\"ajouterDeveloppeur\", {\n       \"nom\": \"Alice\",\n       \"email\": \"alice@example.com\"\n   })\n   ```\n\n### 12.3. Intégration dans votre application\n\nPour intégrer le client MCP à votre application Python :\n\n1. Installer la SDK MCP\n2. Créer une session avec `StreamableHttpTransport`\n3. Utiliser `await session.initialize()` pour établir le protocole\n4. Appeler `await session.call_tool(name, args)` pour invoquer les outils\n\n**Exemple minimal** :\n\n```python\nimport asyncio\nfrom mcp.client.session import ClientSession\nfrom mcp.client.streamable_http import StreamableHttpTransport\n\nasync def main():\n    transport = StreamableHttpTransport(\"http://localhost:8080/mcp\")\n    async with ClientSession(transport) as session:\n        await session.initialize()\n        # Appeler un tool\n        response = await session.call_tool(\"lesProjets\", {})\n        print(response.content[0].text)\n\nasyncio.run(main())\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnajasoft%2Fspring-boot-mcp-rest-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnajasoft%2Fspring-boot-mcp-rest-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnajasoft%2Fspring-boot-mcp-rest-api/lists"}