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

flowchart LR
  subgraph Host ["🖥️ Host (application LLM)"]
    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(Streamable HTTP — distant)"]
    T3["Tool: search_docs"]
    R1["Resource: docs://index"]
    P1["Prompt: summarize"]
  end

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

sequenceDiagram
  actor User
  participant Host
  participant LLM
  participant Client
  participant Server

  User->>Host: "Cherche les documents ouverts"
  Host->>LLM: user message + liste des tools disponibles
  LLM-->>Host: tool_use { name: "search_docs", input: { status: "open" } }
  Host->>Client: invoke tool
  Client->>Server: tools/call (JSON-RPC)
  Server-->>Client: { content: [...documents] }
  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: "docs-mcp",       // ✓ identifiant du server
  version: "1.0.0",
});

server.tool(
  "search_docs",
  "Recherche dans un index documentaire et retourne les extraits pertinents",
  {
    query: z.string().describe("Termes de recherche en langage naturel"),
    limit: z.number().int().min(1).max(20).optional().describe("Nombre max de résultats"),
  },
  async ({ query, limit = 5 }) => {
    const results = await searchIndex(query, limit); // ⚠️ appel async réel
    return {
      content: [{ type: "text", text: JSON.stringify(results) }],
    };
  }
);

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

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

@Configuration
public class McpToolsConfig {

  @Bean
  public ToolCallbackProvider docTools(DocumentService documentService) {
    return MethodToolCallbackProvider.builder()
        .toolObjects(documentService)   // ✓ expose les @Tool de DocumentService
        .build();
  }
}

@Service
public class DocumentService {

  @Tool(description = "Recherche dans un index documentaire")
  public SearchResult searchDocs(
      @ToolParam(description = "Termes de recherche") String query,
      @ToolParam(description = "Nombre max de résultats") Integer limit) {
    // ...
  }
}

spring:
  ai:
    mcp:
      server:
        name: docs-mcp
        version: 1.0.0
        protocol: STATELESS       # STDIO | STREAMABLE | STATELESS
        streamable-http:
          mcp-endpoint: /mcp

// Resource — données stables exposées sans tool call
server.resource(
  "config://index-settings",
  "Paramètres de l'index documentaire",
  async (uri) => ({
    contents: [{ uri: uri.href, text: JSON.stringify(indexSettings) }],
  })
);

// Prompt — template réutilisable pour tâches répétitives
server.prompt(
  "summarize-document",
  "Résume un document et en extrait les points d'action",
  { document: z.string() },
  ({ document }) => ({
    messages: [{
      role: "user",
      content: { type: "text", text: `Résume le document suivant et liste les actions:\n${document}` }
    }]
  })
);