Model Context Protocol (MCP) — architecture et implémentation

flowchart LR
  subgraph Host ["🖥️ Host (ex: Claude Desktop)"]
    LLM["🤖 LLM"]
    C1["Client 1"]
    C2["Client 2"]
    LLM <--> C1
    LLM <--> C2
  end

  subgraph S1 ["MCP Server A\n(stdio — local)"]
    T1["Tool: read_file"]
    T2["Tool: write_file"]
  end

  subgraph S2 ["MCP Server B\n(HTTP Streamable — distant)"]
    T3["Tool: search_jira"]
    R1["Resource: jira://tickets"]
    P1["Prompt: bug-report"]
  end

  C1 -- "stdin/stdout" --> S1
  C2 -- "HTTP + SSE" --> S2

sequenceDiagram
  actor User
  participant Host
  participant LLM
  participant Client
  participant Server

  User->>Host: "Cherche les tickets Jira ouverts"
  Host->>LLM: user message + liste des tools disponibles
  LLM-->>Host: tool_use { name: "search_jira", input: { status: "open" } }
  Host->>Client: invoke tool
  Client->>Server: tools/call (JSON-RPC)
  Server-->>Client: { content: [...tickets] }
  Client-->>Host: tool result
  Host->>LLM: tool result → continue
  LLM-->>Host: réponse finale en langage naturel
  Host-->>User: affichage

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "scdp-mcp",       // ✓ identifiant du server
  version: "1.0.0",
});

server.tool(
  "get_stock_level",
  "Retourne le niveau de stock d'un article en zone SSB/COB/GTAB",
  {
    sku: z.string().describe("Code article"),
    zone: z.enum(["SSB", "COB", "GTAB"]).optional(),
  },
  async ({ sku, zone }) => {
    const stock = await fetchStockFromBigQuery(sku, zone); // ⚠️ appel async réel
    return {
      content: [{ type: "text", text: JSON.stringify(stock) }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
app.post("/mcp", (req, res) => transport.handleRequest(req, res));
app.get("/mcp", (req, res) => transport.handleRequest(req, res)); // ✓ SSE endpoint

await server.connect(transport);
app.listen(3000);

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>

@Configuration
public class McpToolsConfig {

  @Bean
  public ToolCallbackProvider stockTools(StockService stockService) {
    return MethodToolCallbackProvider.builder()
        .toolObjects(stockService)   // ✓ expose les @Tool de StockService
        .build();
  }
}

@Service
public class StockService {

  @Tool(description = "Retourne le niveau de stock d'un article")
  public StockResult getStockLevel(
      @ToolParam(description = "Code article") String sku,
      @ToolParam(description = "Zone SSB/COB/GTAB") String zone) {
    // ...
  }
}

spring:
  ai:
    mcp:
      server:
        name: scdp-mcp
        version: 1.0.0
        transport: STDIO          # ou HTTP
        sse-message-endpoint: /mcp/messages  # si HTTP

// Resource — données stables exposées sans tool call
server.resource(
  "config://warehouse-zones",
  "Liste des zones et leurs capacités",
  async (uri) => ({
    contents: [{ uri: uri.href, text: JSON.stringify(warehouseConfig) }],
  })
);

// Prompt — template réutilisable pour tâches répétitives
server.prompt(
  "analyze-receiving-document",
  "Analyse un bon de réception et extrait les lignes articles",
  { document: z.string() },
  ({ document }) => ({
    messages: [{
      role: "user",
      content: { type: "text", text: `Extrais les lignes du document suivant:\n${document}` }
    }]
  })
);