diff --git a/MyIA.AI.Notebooks/GenAI/SemanticKernel/08-SemanticKernel-MCP.ipynb b/MyIA.AI.Notebooks/GenAI/SemanticKernel/08-SemanticKernel-MCP.ipynb index a74e9a7d5f..eeb0668ce7 100644 --- a/MyIA.AI.Notebooks/GenAI/SemanticKernel/08-SemanticKernel-MCP.ipynb +++ b/MyIA.AI.Notebooks/GenAI/SemanticKernel/08-SemanticKernel-MCP.ipynb @@ -2,8 +2,15 @@ "cells": [ { "cell_type": "markdown", - "id": "bd9f46f9", + "id": "8e721b42", "metadata": { + "papermill": { + "duration": 0.007589, + "end_time": "2026-10-02T04:10:23.241374+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:23.233785+00:00", + "status": "completed" + }, "tags": [] }, "source": [ @@ -16,20 +23,20 @@ "## Objectifs d'apprentissage\n", "\n", "A la fin de ce notebook, vous saurez :\n", - "1. Comprendre le **Model Context Protocol (MCP)**\n", - "2. Identifier les **serveurs MCP** disponibles\n", - "3. Integrer des **outils MCP** comme plugins SK\n", - "4. Créer un **bridge Agent Framework ↔ MCP**\n", - "5. Concevoir un **serveur MCP personnalise**\n", + "1. Comprendre le **Model Context Protocol (MCP)** et son role d'interoperabilite\n", + "2. Lire un **`inputSchema`** et un **`outputSchema`** generes par la decoration d'un outil\n", + "3. Lancer un **vrai serveur MCP** dans un sous-processus stdio et l'interroger\n", + "4. Connecter **Semantic Kernel** a un serveur MCP via `MCPStdioPlugin`\n", + "5. Distinguer un **vrai echange MCP** (initialize / tools/list / tools/call) d'une simulation\n", "\n", "### Prerequis\n", "\n", "- Python 3.10+\n", "- Notebooks 01-07 completes\n", "- Comprehension des Agents SK (notebook 03)\n", - "- Node.js installe (pour certains serveurs MCP)\n", + "- **Aucun runtime externe requis** (pas de Node.js) — le serveur utilise `FastMCP` en Python\n", "\n", - "### Duree estimee : 45 minutes\n", + "### Duree estimee : 50 minutes\n", "\n", "***\n", "\n", @@ -37,47 +44,28 @@ "\n", "| Section | Contenu | Concepts cles |\n", "|---------|---------|---------------|\n", - "| 1 | Introduction | Qu'est-ce que MCP ? |\n", - "| 2 | Architecture | Tools, Resources, Prompts |\n", - "| 3 | Serveurs existants | Filesystem, GitHub, Database |\n", - "| 4 | SK + MCP | Integration comme plugins |\n", - "| 5 | Agent + MCP | Bridge avec Agent Framework |\n", - "| 6 | Serveur custom | Créer son propre serveur |\n", - "| 7 | Conclusion | Resume, exercices |\n", - "\n", - "> **Model Context Protocol (MCP)** : Standard ouvert initie par Anthropic et adopte par Microsoft pour permettre aux LLMs d'acceder a des outils externes de maniere standardisee. C'est l'evolution des plugins vers l'interoperabilite." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "de07375f", - "metadata": { - "tags": [] - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "MCP SDK installe\n" - ] - } - ], - "source": [ - "# Installation\n", - "\n", - "import os\n", - "from dotenv import load_dotenv\n", - "\n", - "load_dotenv()\n", - "print(\"MCP SDK installe\")" + "| 1 | Introduction | MCP comme standard d'interoperabilite |\n", + "| 2 | Architecture | Tools, Resources, Prompts, JSON-RPC |\n", + "| 3 | Serveur reel | FastMCP + ClientSession + schémas |\n", + "| 4 | SK + MCP | MCPStdioPlugin |\n", + "| 5 | Agent + MCP | bridge `FunctionChoiceBehavior.Auto()` |\n", + "| 6 | Sens inverse | `Kernel.as_mcp_server()` |\n", + "| 7 | Conclusion | recap et exercices re-ancres |\n", + "\n", + "> **Model Context Protocol (MCP)** : standard ouvert initie par Anthropic en novembre 2024, adopte par Microsoft Semantic Kernel et de nombreux autres frameworks, qui definit comment un client (Claude Code, SK, LangChain, AutoGen, etc.) consomme les outils exposes par un serveur. La force du protocole tient dans la **decoration** : la signature de chaque outil, son type de retour et sa docstring produisent automatiquement le `JSON Schema` que le modele lit pour decider quel outil appeler et comment.\n" ] }, { "cell_type": "markdown", - "id": "1b072c98", + "id": "d8fdc959", "metadata": { + "papermill": { + "duration": 0.012227, + "end_time": "2026-10-02T04:10:23.259318+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:23.247091+00:00", + "status": "completed" + }, "tags": [] }, "source": [ @@ -85,157 +73,159 @@ "\n", "### Pourquoi MCP ?\n", "\n", - "Avant MCP, chaque framework avait son propre système de plugins :\n", + "Avant MCP, chaque framework d'agent avait son propre systeme de plugins :\n", "\n", - "| Framework | Système de plugins | Problème |\n", - "|-----------|-------------------|----------|\n", - "| Semantic Kernel | KernelFunction | Non portable |\n", - "| LangChain | Tools | Non portable |\n", - "| AutoGen | Tools | Non portable |\n", - "| OpenAI | Function Calling | Spécifique OpenAI |\n", + "| Framework | Système de plugins | Limitation |\n", + "|-----------|-------------------|------------|\n", + "| Semantic Kernel | `@kernel_function` | Non portable hors SK |\n", + "| LangChain | Tools | Non portable hors LangChain |\n", + "| AutoGen | Tools | Non portable hors AutoGen |\n", + "| OpenAI | Function Calling | Specifique au runtime OpenAI |\n", "\n", - "**MCP resout ce problème** en definissant un standard :\n", - "\n", - "```\n", - "┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐\n", - "│ Semantic Kernel │ │ LangChain │ │ AutoGen │\n", - "│ │ │ │ │ │\n", - "│ MCP Client │ │ MCP Client │ │ MCP Client │\n", - "└────────┬────────┘ └────────┬────────┘ └────────┬────────┘\n", - " │ │ │\n", - " └───────────────────────┼───────────────────────┘\n", - " │\n", - " ↓\n", - " ┌─────────────────────────┐\n", - " │ MCP Servers │\n", - " │ │\n", - " │ - Filesystem │\n", - " │ - GitHub │\n", - " │ - Database │\n", - " │ - Custom... │\n", - " └─────────────────────────┘\n", - "```\n", + "MCP **standardise** ce contrat : un serveur expose une liste d'outils, chaque outil publie son `inputSchema` (JSON Schema), et **n'importe quel client conforme** peut consommer ces outils. C'est l'equivalent, pour les outils d'agents, de ce que USB a ete pour les peripheriques.\n", "\n", "### Acteurs principaux\n", "\n", - "| Acteur | Rôle | Exemple |\n", - "|--------|------|---------|\n", - "| **Client** | Consomme les outils | Claude Code, SK |\n", - "| **Server** | Fournit les outils | mcp-server-filesystem |\n", - "| **Transport** | Communication | stdio, HTTP, SSE |" - ] - }, - { - "cell_type": "markdown", - "id": "mcp5k08c", - "metadata": { - "tags": [] - }, - "source": [ - "Le diagramme ci-dessous rend cette architecture **MCP** sous forme de graphe : plusieurs\n", - "frameworks clients consomment un même ensemble de serveurs d'outils standardises.\n", - "\n", - "```mermaid\n", - "flowchart TD\n", - " SK[\"Semantic Kernel
MCP Client\"] --> SRV\n", - " LC[\"LangChain
MCP Client\"] --> SRV\n", - " AG[\"AutoGen
MCP Client\"] --> SRV\n", - " SRV[\"MCP Servers
Filesystem / GitHub / Database / Custom...\"]\n", - " classDef client fill:#cfe2ff,stroke:#084298,color:#052c65\n", - " classDef server fill:#fff3cd,stroke:#b8860b,color:#5c4400\n", - " class SK,LC,AG client\n", - " class SRV server\n", - "```\n", + "| Acteur | Role | Exemples |\n", + "|--------|------|----------|\n", + "| **Client** | Consomme les outils | Claude Code, Semantic Kernel, LangChain |\n", + "| **Server** | Fournit les outils | `@modelcontextprotocol/server-filesystem`, `mcp-server-git`, FastMCP en Python |\n", + "| **Transport** | Transporte les messages JSON-RPC | `stdio` (sous-processus), `streamable-http` (HTTP+POST), `SSE` (legacy) |\n", + "\n", + "### Ce qui distingue MCP d'une simple liste d'outils\n", "\n", - "> **Lecture.** Le **Model Context Protocol** standardise la facon dont un agent accede a\n", - "> des outils externes : n'importe quel **client** conforme (Semantic Kernel, LangChain,\n", - "> AutoGen...) peut consommer n'importe quel **serveur MCP** (filesystem, GitHub, base de\n", - "> données, serveurs maison) sans integration sur-mesure. C'est l'equivalent, pour les\n", - "> outils d'agents, de ce que USB a ete pour les peripheriques : un connecteur commun qui\n", - "> decouple les clients des fournisseurs de capacites.\n" + "Trois proprietes que les simulations ne reproduisent pas :\n", + "\n", + "1. **Decoration = schema** : la signature Python (`def f(base: float, remise: int = 0) -> Prix`) derive un `inputSchema` (types, `required`, contraintes, descriptions) et un `outputSchema` (a partir du modele Pydantic du retour).\n", + "2. **Validation cote serveur** : le serveur refuse un appel dont les arguments violent l'`inputSchema` *avant* d'executer la fonction. Le client recoit `isError=True` avec un message structure.\n", + "3. **Double canal de reponse** : un `tools/call` renvoie du texte lisible **et** un `structuredContent` typé, exploitable par le modele pour enchaîner.\n" ] }, { "cell_type": "markdown", - "id": "63080987", + "id": "f913c08b", "metadata": { + "papermill": { + "duration": 0.008944, + "end_time": "2026-10-02T04:10:23.277676+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:23.268732+00:00", + "status": "completed" + }, "tags": [] }, "source": [ "## 2. Architecture MCP\n", "\n", - "MCP définit trois types de primitives :\n", + "MCP definit trois types de **primitives** cote serveur :\n", "\n", - "### 2.1 Tools (Outils)\n", + "| Primitive | Role | Exemple |\n", + "|-----------|------|---------|\n", + "| **Tools** | Fonctions executables que le LLM peut appeler | `read_file`, `query_database`, `calculate_price` |\n", + "| **Resources** | Donnees adressables par URI que le client peut lire | `file:///path/to/doc.md`, `db://users/42` |\n", + "| **Prompts** | Templates reutilisables avec arguments | `summarize(text: str, max_words: int)` |\n", "\n", - "Fonctions executables par le LLM :\n", + "Le transport est **JSON-RPC 2.0** sur `stdio` (le serveur est un sous-processus du client) ou sur `streamable-http` (le client envoie des requetes HTTP POST au serveur).\n", "\n", - "```json\n", - "{\n", - " \"name\": \"read_file\",\n", - " \"description\": \"Read the contents of a file\",\n", - " \"inputSchema\": {\n", - " \"type\": \"object\",\n", - " \"properties\": {\n", - " \"path\": { \"type\": \"string\" }\n", - " },\n", - " \"required\": [\"path\"]\n", - " }\n", - "}\n", + "```\n", + " ┌──────────────┐ ┌──────────────┐\n", + " │ MCP Client │ JSON-RPC over stdio │ MCP Server │\n", + " │ │ ───────────────────────> │ │\n", + " │ SK / Claude │ initialize │ FastMCP / │\n", + " │ Code / etc. │ tools/list │ Node SDK │\n", + " │ │ tools/call │ │\n", + " │ │ <─────────────────────── │ │\n", + " └──────────────┘ └──────────────┘\n", "```\n", "\n", - "### 2.2 Resources (Ressources)\n", + "Trois methodes JSON-RPC essentielles :\n", "\n", - "Données accessibles en lecture :\n", + "| Methode | Sens | Ce qu'elle retourne |\n", + "|---------|------|---------------------|\n", + "| `initialize` | client → serveur | Capacites du serveur (nom, version, fonctionnalites) |\n", + "| `tools/list` | client → serveur | Liste des outils avec `name`, `description`, `inputSchema` |\n", + "| `tools/call` | client → serveur | Resultat : `content` textuel + `structuredContent` typé, ou `isError` |\n", "\n", - "```json\n", - "{\n", - " \"uri\": \"file:///path/to/doc.md\",\n", - " \"name\": \"Documentation\",\n", - " \"mimeType\": \"text/markdown\"\n", - "}\n", - "```\n", + "### 2.1 Le schema d'entree (`inputSchema`)\n", "\n", - "### 2.3 Prompts\n", + "C'est un **JSON Schema** classique. Pour un outil defini en Python avec `@mcp.tool()`, la decoration derive le schema a partir des annotations de type et des `Field(...)` Pydantic :\n", "\n", - "Templates de prompts reutilisables :\n", + "```python\n", + "@mcp.tool()\n", + "def prix(base: Annotated[float, Field(description=\"prix HT\", gt=0)], remise: int = 0) -> Prix:\n", + " ...\n", + "```\n", + "\n", + "donne :\n", "\n", "```json\n", "{\n", - " \"name\": \"summarize\",\n", - " \"description\": \"Summarize a document\",\n", - " \"arguments\": [\n", - " { \"name\": \"content\", \"required\": true }\n", - " ]\n", + " \"type\": \"object\",\n", + " \"properties\": {\n", + " \"base\": {\"type\": \"number\", \"description\": \"prix HT\", \"exclusiveMinimum\": 0},\n", + " \"remise\": {\"type\": \"integer\", \"default\": 0}\n", + " },\n", + " \"required\": [\"base\"]\n", "}\n", "```\n", "\n", - "### Tableau comparatif\n", + "### 2.2 Le schema de sortie (`outputSchema`)\n", + "\n", + "Quand le type de retour est un modele Pydantic, FastMCP derive un `outputSchema` automatiquement. Le client peut alors valider un `structuredContent` recu avant d'enchaîner.\n", "\n", - "| Primitive | Action | Equivalent SK |\n", - "|-----------|--------|---------------|\n", - "| **Tool** | Execute une fonction | KernelFunction |\n", - "| **Resource** | Lit des données | Pas d'equivalent direct |\n", - "| **Prompt** | Fournit un template | PromptTemplate |" + "> **Lecture.** Le contrat d'un outil MCP tient en trois champs que le modele lit avant d'appeler : `name`, `description`, `inputSchema`. Le decorateur Python les produit sans qu'aucun schema ne soit ecrit a la main — c'est l'interet du protocole par rapport aux definitions JSON manuelles.\n" ] }, { "cell_type": "markdown", - "id": "9c33e97c", + "id": "ba81773f", "metadata": { + "papermill": { + "duration": 0.009138, + "end_time": "2026-10-02T04:10:23.294841+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:23.285703+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "## 3. Serveurs MCP existants\n", + "## 3. Serveur MCP reel : FastMCP + ClientSession\n", + "\n", + "### Installation des SDK\n", + "\n", + "Les SDK MCP pour Python sont installables via `pip` :\n", + "\n", + "```bash\n", + "pip install \"mcp[cli]\"\n", + "```\n", "\n", - "De nombreux serveurs MCP sont disponibles :" + "Ce notebook a ete execute avec :\n", + "- `mcp` 1.30.0 (cote serveur et client)\n", + "- `pydantic` 2.13.5 (modeles de validation et `outputSchema`)\n", + "- `semantic-kernel` 1.44.1 (avec `semantic_kernel.connectors.mcp.MCPStdioPlugin`)\n", + "\n", + "Tous ces paquets etaient deja disponibles dans l'environnement : **verdict SOTA = RECOVERABLE-LOCAL** (rien a installer), ce qui tranche avec la cellule `de07375f` du carnet d'origine qui se contentait de charger `.env` et d'imprimer *« MCP SDK installe »* sans installer ni importer quoi que ce soit.\n" ] }, { "cell_type": "code", - "execution_count": 2, - "id": "90023b20", + "execution_count": 1, + "id": "a5778054", "metadata": { + "execution": { + "iopub.execute_input": "2026-10-02T04:10:23.313767Z", + "iopub.status.busy": "2026-10-02T04:10:23.313298Z", + "iopub.status.idle": "2026-10-02T04:10:26.720602Z", + "shell.execute_reply": "2026-10-02T04:10:26.718684Z" + }, + "papermill": { + "duration": 3.420669, + "end_time": "2026-10-02T04:10:26.721531+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:23.300862+00:00", + "status": "completed" + }, "tags": [] }, "outputs": [ @@ -243,99 +233,75 @@ "name": "stdout", "output_type": "stream", "text": [ - "Serveurs MCP populaires:\n", - "============================================================\n", - "\n", - "FILESYSTEM\n", - " Package: @anthropic/mcp-server-filesystem\n", - " Description: Lecture/ecriture de fichiers\n", - " Tools: read_file, write_file, list_directory\n", - "\n", - "GITHUB\n", - " Package: @anthropic/mcp-server-github\n", - " Description: Operations GitHub (repos, issues, PRs)\n", - " Tools: search_repos, get_issue, create_pr\n", - "\n", - "POSTGRES\n", - " Package: @anthropic/mcp-server-postgres\n", - " Description: Requetes SQL PostgreSQL\n", - " Tools: query, execute, describe_table\n", - "\n", - "JUPYTER\n", - " Package: mcp-jupyter\n", - " Description: Execution de notebooks Jupyter\n", - " Tools: execute_notebook, read_cells, manage_kernel\n", - "\n", - "PUPPETEER\n", - " Package: @anthropic/mcp-server-puppeteer\n", - " Description: Automatisation web (scraping, screenshots)\n", - " Tools: navigate, screenshot, click\n" + "mcp: 1.30.0\n", + "semantic-kernel: 1.44.1\n", + "pydantic: 2.13.5\n" + ] + }, + { + "name": "stdout", + "output_type": "stream", + "text": [ + "FastMCP, ClientSession, stdio_client, MCPStdioPlugin : OK\n" ] } ], "source": [ - "# Liste des serveurs MCP populaires\n", - "mcp_servers = [\n", - " {\n", - " \"name\": \"filesystem\",\n", - " \"package\": \"@anthropic/mcp-server-filesystem\",\n", - " \"description\": \"Lecture/ecriture de fichiers\",\n", - " \"tools\": [\"read_file\", \"write_file\", \"list_directory\"]\n", - " },\n", - " {\n", - " \"name\": \"github\",\n", - " \"package\": \"@anthropic/mcp-server-github\",\n", - " \"description\": \"Operations GitHub (repos, issues, PRs)\",\n", - " \"tools\": [\"search_repos\", \"get_issue\", \"create_pr\"]\n", - " },\n", - " {\n", - " \"name\": \"postgres\",\n", - " \"package\": \"@anthropic/mcp-server-postgres\",\n", - " \"description\": \"Requetes SQL PostgreSQL\",\n", - " \"tools\": [\"query\", \"execute\", \"describe_table\"]\n", - " },\n", - " {\n", - " \"name\": \"jupyter\",\n", - " \"package\": \"mcp-jupyter\",\n", - " \"description\": \"Execution de notebooks Jupyter\",\n", - " \"tools\": [\"execute_notebook\", \"read_cells\", \"manage_kernel\"]\n", - " },\n", - " {\n", - " \"name\": \"puppeteer\",\n", - " \"package\": \"@anthropic/mcp-server-puppeteer\",\n", - " \"description\": \"Automatisation web (scraping, screenshots)\",\n", - " \"tools\": [\"navigate\", \"screenshot\", \"click\"]\n", - " }\n", - "]\n", + "# Verification rapide : les SDK sont-ils importables ?\n", + "import importlib.metadata as md\n", + "print(\"mcp:\", md.version(\"mcp\"))\n", + "print(\"semantic-kernel:\", md.version(\"semantic-kernel\"))\n", + "print(\"pydantic:\", md.version(\"pydantic\"))\n", + "\n", + "from mcp.server.fastmcp import FastMCP\n", + "from mcp import ClientSession, StdioServerParameters\n", + "from mcp.client.stdio import stdio_client\n", + "from semantic_kernel.connectors.mcp import MCPStdioPlugin\n", + "from pydantic import BaseModel, Field\n", + "from typing import Annotated\n", "\n", - "print(\"Serveurs MCP populaires:\")\n", - "print(\"=\" * 60)\n", - "for server in mcp_servers:\n", - " print(f\"\\n{server['name'].upper()}\")\n", - " print(f\" Package: {server['package']}\")\n", - " print(f\" Description: {server['description']}\")\n", - " print(f\" Tools: {', '.join(server['tools'])}\")" + "print(\"FastMCP, ClientSession, stdio_client, MCPStdioPlugin : OK\")\n" ] }, { "cell_type": "markdown", - "id": "9accb0c5", + "id": "6befa05e", "metadata": { + "papermill": { + "duration": 0.005438, + "end_time": "2026-10-02T04:10:26.730830+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:26.725392+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "### Exemple guidé 1 : Analyseur de capacites MCP\n", + "### 3.1 Le serveur : FastMCP en Python\n", "\n", - "*Contribution étudiante de Gabriel COMBE (@GabrielC-star) et Rémi LESANNE, PR #18553, intégrée comme exemple guidé.*\n", + "Nous ecrivons un serveur FastMCP qui expose **cinq outils** : prix TTC avec remise, detail de TVA, TVA inverse, validation de chemin et analyse de chaine. Chaque outil est decore par `@mcp.tool()`, avec des annotations `Annotated[...]` et un type de retour Pydantic — c'est la decoration qui produit `inputSchema` et `outputSchema`.\n", "\n", - "Cet exemple classe les cinq serveurs MCP listés plus haut par domaine d'expertise (`storage`, `devops`, `web`, `data`). La fonction `categorize_mcp_servers()` parcourt la liste, reconnaît le domaine de chaque serveur grâce aux mots-clés de sa description, compte ses outils et repère le serveur le mieux pourvu. Elle retourne un dict avec les catégories, le total d'outils et le nom du serveur en ayant le plus." + "> Le serveur sera ecrit dans un fichier temporaire et lance en sous-processus stdio, exactement comme le ferait un client reel (Claude Code, par exemple). C'est ce sous-processus qui parle JSON-RPC sur son entree/sortie standard." ] }, { "cell_type": "code", - "execution_count": 3, - "id": "44789c95", + "execution_count": 2, + "id": "eef1e7c5", "metadata": { + "execution": { + "iopub.execute_input": "2026-10-02T04:10:26.751873Z", + "iopub.status.busy": "2026-10-02T04:10:26.751253Z", + "iopub.status.idle": "2026-10-02T04:10:26.771567Z", + "shell.execute_reply": "2026-10-02T04:10:26.769626Z" + }, + "papermill": { + "duration": 0.029591, + "end_time": "2026-10-02T04:10:26.772837+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:26.743246+00:00", + "status": "completed" + }, "tags": [] }, "outputs": [ @@ -343,122 +309,72 @@ "name": "stdout", "output_type": "stream", "text": [ - "storage: ['filesystem']\n", - "devops: ['github']\n", - "web: ['puppeteer']\n", - "data: ['postgres']\n", - "Total outils: 15\n" + "Serveur ecrit : serveur_demo.py\n" ] } ], "source": [ - "# Exemple guide 1 : Analyseur de capacites MCP\n", - "# Contribution etudiante de Gabriel COMBE et Remi LESANNE (PR #18553)\n", - "def categorize_mcp_servers(servers: list) -> dict:\n", - " \"\"\"\n", - " Classifier les serveurs MCP par domaine d'expertise.\n", - " \n", - " Args:\n", - " servers: Liste de dicts avec les cles: name, description, tools\n", - " \n", - " Returns:\n", - " dict avec les cles: categories (dict domaine -> list serveurs),\n", - " total_tools (int), server_with_most_tools (str)\n", - " \"\"\"\n", - " categories = {\n", - " \"storage\": [],\n", - " \"devops\": [],\n", - " \"web\": [],\n", - " \"data\": []\n", - " }\n", - "\n", - " total_tools = 0\n", - " server_with_most_tools = None\n", - " max_tools = 0\n", - "\n", - " for server in servers:\n", - " name = server[\"name\"]\n", - " description = server[\"description\"].lower()\n", - " tools = server[\"tools\"]\n", - "\n", - " nb_tools = len(tools)\n", - " total_tools += nb_tools\n", - "\n", - " if nb_tools > max_tools:\n", - " max_tools = nb_tools\n", - " server_with_most_tools = name\n", - " \n", - " if \"fichier\" in description:\n", - " categories[\"storage\"].append(server)\n", - "\n", - " elif \"github\" in description:\n", - " categories[\"devops\"].append(server)\n", - "\n", - " elif \"scraping\" in description:\n", - " categories[\"web\"].append(server)\n", - "\n", - " elif \"sql\" in description:\n", - " categories[\"data\"].append(server)\n", - "\n", - "\n", - " return {\n", - " \"categories\": categories,\n", - " \"total_tools\": total_tools,\n", - " \"server_with_most_tools\": server_with_most_tools\n", - " }\n", - " \n", - " \n", - "# Test :\n", - "result = categorize_mcp_servers(mcp_servers)\n", - "for category, srvs in result['categories'].items():\n", - " print(f\"{category}: {[s['name'] for s in srvs]}\")\n", - "print(f\"Total outils: {result['total_tools']}\")" - ] - }, - { - "cell_type": "markdown", - "id": "mcp-eg1-lecture", - "metadata": {}, - "source": [ - "### Lecture du résultat — exemple guidé 1 (capacités MCP)\n", - "\n", - "- Les quatre domaines attendus sont remplis : `storage: ['filesystem']`, `devops: ['github']`, `web: ['puppeteer']`, `data: ['postgres']`.\n", - "- `mcp_servers` compte 5 serveurs, mais un seul manque à l'appel : `jupyter` n'apparaît dans aucune catégorie. Sa description (« Execution de notebooks Jupyter ») ne contient aucun des mots-clés testés (`fichier`, `github`, `scraping`, `sql`) — le classement par mots-clés l'ignore **silencieusement**, sans erreur ni avertissement.\n", - "- `Total outils: 15` compte pourtant les 5 serveurs (3 outils chacun), `jupyter` compris : le total et les catégories ne décrivent pas le même périmètre.\n", - "- `server_with_most_tools` est calculé — la paire gagnante serait `filesystem`, premier ex æquo à 3 outils — mais jamais imprimé : la valeur retourne dans le dict sans apparaître dans la sortie." + "# Ecriture du serveur dans un fichier temporaire\n", + "import tempfile\n", + "from pathlib import Path\n", + "\n", + "server_source = 'from typing import Annotated\\nfrom pathlib import Path\\nfrom pydantic import BaseModel, Field\\nfrom mcp.server.fastmcp import FastMCP\\n\\nmcp = FastMCP(\"demo-prix-tva\")\\n\\nclass PrixTTC(BaseModel):\\n ht: float = Field(description=\"prix hors taxe\")\\n ttc: float = Field(description=\"prix TTC\")\\n\\nclass TVA(BaseModel):\\n ht: float = Field(description=\"prix hors taxe\")\\n tva: float = Field(description=\"montant TVA\")\\n ttc: float = Field(description=\"prix TTC\")\\n\\nclass TVAInverse(BaseModel):\\n ttc: float = Field(description=\"prix TTC de depart\")\\n taux_tva: float = Field(description=\"taux de TVA applique (ex: 0.196)\")\\n ht: float = Field(description=\"prix hors taxe retrouve\")\\n\\nclass Chemin(BaseModel):\\n chemin: str\\n zone_autorisee: str\\n dans_zone: bool\\n\\nclass AnalyseChaine(BaseModel):\\n nb_caracteres: int\\n nb_mots: int\\n premier_mot: str\\n\\n@mcp.tool()\\ndef prix_ttc(\\n base: Annotated[float, Field(description=\"prix HT en euros\", gt=0)],\\n remise_pct: Annotated[int, Field(description=\"remise en pourcent\", ge=0, le=100)] = 0,\\n) -> PrixTTC:\\n \"Calcule le prix TTC apres remise.\"\\n ht_apres_remise = base * (1 - remise_pct / 100.0)\\n ttc = ht_apres_remise * 1.2 # TVA 20%\\n return PrixTTC(ht=round(ht_apres_remise, 2), ttc=round(ttc, 2))\\n\\n@mcp.tool()\\ndef calcule_tva(montant_ht: Annotated[float, Field(description=\"montant HT\", gt=0)]) -> TVA:\\n \"Detail du montant de TVA pour un HT donne (taux 20%).\"\\n tva = montant_ht * 0.2\\n return TVA(ht=montant_ht, tva=round(tva, 2), ttc=round(montant_ht + tva, 2))\\n\\n@mcp.tool()\\ndef tva_inverse(\\n montant_ttc: Annotated[float, Field(description=\"prix TTC connu\", gt=0)],\\n taux_tva: Annotated[float, Field(description=\"taux de TVA (ex: 0.196)\", gt=0, lt=1)],\\n) -> TVAInverse:\\n \"Retrouve le HT a partir du TTC et du taux de TVA. Utile pour les tickets de caisse.\"\\n ht = montant_ttc / (1 + taux_tva)\\n return TVAInverse(ttc=montant_ttc, taux_tva=taux_tva, ht=round(ht, 4))\\n\\n@mcp.tool()\\ndef verifie_chemin(chemin: str, zone_autorisee: str) -> Chemin:\\n \"Valide qu\\'un chemin est dans une zone autorisee. Retourne dans_zone=True/False.\"\\n try:\\n c = Path(chemin).resolve()\\n z = Path(zone_autorisee).resolve()\\n dans_zone = c.is_relative_to(z) if hasattr(c, \"is_relative_to\") else str(c).startswith(str(z))\\n except (OSError, ValueError):\\n dans_zone = False\\n return Chemin(chemin=chemin, zone_autorisee=zone_autorisee, dans_zone=dans_zone)\\n\\n@mcp.tool()\\ndef analyse_chaine(texte: str) -> AnalyseChaine:\\n \"Statistiques lexicales sur un texte: nombre de caracteres, mots, premier mot.\"\\n mots = texte.split()\\n return AnalyseChaine(\\n nb_caracteres=len(texte),\\n nb_mots=len(mots),\\n premier_mot=mots[0] if mots else \"\",\\n )\\n\\nif __name__ == \"__main__\":\\n mcp.run()\\n'\n", + "\n", + "tmpdir = Path(tempfile.mkdtemp(prefix=\"sk08-mcp-\"))\n", + "server_path = tmpdir / \"serveur_demo.py\"\n", + "server_path.write_text(server_source, encoding=\"utf-8\")\n", + "# Note : on imprime le `basename` du chemin, pas le chemin absolu -- un\n", + "# tempfile Windows contient le HOME de l'utilisateur, et le ratchet CI\n", + "# `Output-failure ratchet (base vs PR)` rougit dès qu'un chemin machine\n", + "# local apparait dans une sortie (cf. c.1107 / MEMORY §5). Le chemin\n", + "# complet reste disponible via `str(server_path)` si l'etudiant veut le\n", + "# copier ; la sortie du carnet reste anonyme.\n", + "print(f\"Serveur ecrit : {server_path.name}\")\n" ] }, { "cell_type": "markdown", - "id": "mcp-ex1-routage-md", + "id": "0f014458", "metadata": { + "papermill": { + "duration": 0.007373, + "end_time": "2026-10-02T04:10:26.789690+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:26.782317+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "### Exercice 1 : Router une tache vers le bon serveur et son outil\n", - "\n", - "L'exemple guidé 1 classe les serveurs par domaine, mais il ne dit pas *quel outil* appeler pour une tâche donnée, et surtout il **ignore silencieusement** tout serveur que ses mots-clés ne reconnaissent pas. Un vrai routeur doit savoir répondre « aucun serveur ne sait faire ça ».\n", + "### 3.2 Le client : `ClientSession` + `stdio_client`\n", "\n", - "**Objectif** : écrire `choisir_outil(tache, servers)` qui, pour une tâche en langage naturel, note chaque paire (serveur, outil) selon les mots de la tâche, et retourne la meilleure paire — ou `None` quand aucun score n'est positif.\n", + "Le client `MCP` s'ouvre en trois etapes :\n", "\n", - "**Étapes** :\n", - "1. `# Étape 1` : découper la tâche en mots (minuscules), en ajoutant au besoin des synonymes (par exemple « capture d'ecran » → `screenshot`)\n", - "2. `# Étape 2` : pour chaque serveur de `mcp_servers` et chacun de ses outils, calculer un score : +1 si un mot de la tâche correspond au nom du serveur, à sa description ou au nom de l'outil\n", - "3. `# Étape 3` : retourner la paire `(serveur, outil)` au meilleur score si ce score est strictement positif, sinon `None`\n", + "1. **Lancer** le sous-processus serveur via `stdio_client(StdioServerParameters(...))`.\n", + "2. **Initialiser** la session via `await session.initialize()` — c'est l'echange `initialize` du protocole.\n", + "3. **Interroger** : `list_tools()` pour les schemas, `call_tool(name, arguments)` pour executer.\n", "\n", - "**Indices** :\n", - "- `# Indice` : « ouvrir une issue pour signaler un bug » contient le mot *issue* — un outil de `github` s'appelle `get_issue`\n", - "- `# Indice` : « lister les tables de la base » parle de tables — `describe_table` est un outil de `postgres`\n", - "- `# Indice` : « envoyer un SMS » ne correspond à aucun serveur — la fonction doit retourner `None`, sans lever d'erreur\n", - "\n", - "**Critère de réussite** : les quatre tests affichent `('github', 'get_issue')`, `('puppeteer', 'screenshot')`, `('postgres', 'describe_table')` puis `None`." + "Le `async with` garantit que le sous-processus est termine proprement quand on quitte le contexte (meme en cas d'exception)." ] }, { "cell_type": "code", - "execution_count": 4, - "id": "mcp-ex1-routage-code", + "execution_count": 3, + "id": "c0e8f9d0", "metadata": { + "execution": { + "iopub.execute_input": "2026-10-02T04:10:26.813208Z", + "iopub.status.busy": "2026-10-02T04:10:26.812782Z", + "iopub.status.idle": "2026-10-02T04:10:27.996172Z", + "shell.execute_reply": "2026-10-02T04:10:27.994373Z" + }, + "papermill": { + "duration": 1.1961, + "end_time": "2026-10-02T04:10:27.998729+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:26.802629+00:00", + "status": "completed" + }, "tags": [] }, "outputs": [ @@ -466,139 +382,404 @@ "name": "stdout", "output_type": "stream", "text": [ - "Exercice a completer\n" + "[init] serveur=demo-prix-tva v1.30.0\n", + " protocole=2025-11-25\n", + "\n", + "[tools/list] 5 outil(s) :\n", + " - prix_ttc: Calcule le prix TTC apres remise.\n", + " inputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"base\": {\n", + " \"description\": \"prix HT en euros\",\n", + " \"exclusiveMinimum\": 0,\n", + " \"title\": \"Base\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"remise_pct\": {\n", + " \"default\": 0,\n", + " \"description\": \"remise en pourcent\",\n", + " \"maximum\": 100,\n", + " \"minimum\": 0,\n", + " \"title\": \"Remise Pct\",\n", + " \"type\": \"integer\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"base\"\n", + " ],\n", + " \"title\": \"prix_ttcArguments\",\n", + " \"type\": \"object\"\n", + " }\n", + " outputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"ht\": {\n", + " \"description\": \"prix hors taxe\",\n", + " \"title\": \"Ht\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"ttc\": {\n", + " \"description\": \"prix TTC\",\n", + " \"title\": \"Ttc\",\n", + " \"type\": \"number\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"ht\",\n", + " \"ttc\"\n", + " ],\n", + " \"title\": \"PrixTTC\",\n", + " \"type\": \"object\"\n", + " }\n", + " - calcule_tva: Detail du montant de TVA pour un HT donne (taux 20%).\n", + " inputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"montant_ht\": {\n", + " \"description\": \"montant HT\",\n", + " \"exclusiveMinimum\": 0,\n", + " \"title\": \"Montant Ht\",\n", + " \"type\": \"number\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"montant_ht\"\n", + " ],\n", + " \"title\": \"calcule_tvaArguments\",\n", + " \"type\": \"object\"\n", + " }\n", + " outputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"ht\": {\n", + " \"description\": \"prix hors taxe\",\n", + " \"title\": \"Ht\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"tva\": {\n", + " \"description\": \"montant TVA\",\n", + " \"title\": \"Tva\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"ttc\": {\n", + " \"description\": \"prix TTC\",\n", + " \"title\": \"Ttc\",\n", + " \"type\": \"number\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"ht\",\n", + " \"tva\",\n", + " \"ttc\"\n", + " ],\n", + " \"title\": \"TVA\",\n", + " \"type\": \"object\"\n", + " }\n", + " - tva_inverse: Retrouve le HT a partir du TTC et du taux de TVA. Utile pour les tickets de caisse.\n", + " inputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"montant_ttc\": {\n", + " \"description\": \"prix TTC connu\",\n", + " \"exclusiveMinimum\": 0,\n", + " \"title\": \"Montant Ttc\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"taux_tva\": {\n", + " \"description\": \"taux de TVA (ex: 0.196)\",\n", + " \"exclusiveMaximum\": 1,\n", + " \"exclusiveMinimum\": 0,\n", + " \"title\": \"Taux Tva\",\n", + " \"type\": \"number\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"montant_ttc\",\n", + " \"taux_tva\"\n", + " ],\n", + " \"title\": \"tva_inverseArguments\",\n", + " \"type\": \"object\"\n", + " }\n", + " outputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"ttc\": {\n", + " \"description\": \"prix TTC de depart\",\n", + " \"title\": \"Ttc\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"taux_tva\": {\n", + " \"description\": \"taux de TVA applique (ex: 0.196)\",\n", + " \"title\": \"Taux Tva\",\n", + " \"type\": \"number\"\n", + " },\n", + " \"ht\": {\n", + " \"description\": \"prix hors taxe retrouve\",\n", + " \"title\": \"Ht\",\n", + " \"type\": \"number\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"ttc\",\n", + " \"taux_tva\",\n", + " \"ht\"\n", + " ],\n", + " \"title\": \"TVAInverse\",\n", + " \"type\": \"object\"\n", + " }\n", + " - verifie_chemin: Valide qu'un chemin est dans une zone autorisee. Retourne dans_zone=True/False.\n", + " inputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"chemin\": {\n", + " \"title\": \"Chemin\",\n", + " \"type\": \"string\"\n", + " },\n", + " \"zone_autorisee\": {\n", + " \"title\": \"Zone Autorisee\",\n", + " \"type\": \"string\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"chemin\",\n", + " \"zone_autorisee\"\n", + " ],\n", + " \"title\": \"verifie_cheminArguments\",\n", + " \"type\": \"object\"\n", + " }\n", + " outputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"chemin\": {\n", + " \"title\": \"Chemin\",\n", + " \"type\": \"string\"\n", + " },\n", + " \"zone_autorisee\": {\n", + " \"title\": \"Zone Autorisee\",\n", + " \"type\": \"string\"\n", + " },\n", + " \"dans_zone\": {\n", + " \"title\": \"Dans Zone\",\n", + " \"type\": \"boolean\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"chemin\",\n", + " \"zone_autorisee\",\n", + " \"dans_zone\"\n", + " ],\n", + " \"title\": \"Chemin\",\n", + " \"type\": \"object\"\n", + " }\n", + " - analyse_chaine: Statistiques lexicales sur un texte: nombre de caracteres, mots, premier mot.\n", + " inputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"texte\": {\n", + " \"title\": \"Texte\",\n", + " \"type\": \"string\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"texte\"\n", + " ],\n", + " \"title\": \"analyse_chaineArguments\",\n", + " \"type\": \"object\"\n", + " }\n", + " outputSchema:\n", + " {\n", + " \"properties\": {\n", + " \"nb_caracteres\": {\n", + " \"title\": \"Nb Caracteres\",\n", + " \"type\": \"integer\"\n", + " },\n", + " \"nb_mots\": {\n", + " \"title\": \"Nb Mots\",\n", + " \"type\": \"integer\"\n", + " },\n", + " \"premier_mot\": {\n", + " \"title\": \"Premier Mot\",\n", + " \"type\": \"string\"\n", + " }\n", + " },\n", + " \"required\": [\n", + " \"nb_caracteres\",\n", + " \"nb_mots\",\n", + " \"premier_mot\"\n", + " ],\n", + " \"title\": \"AnalyseChaine\",\n", + " \"type\": \"object\"\n", + " }\n", + "\n", + "[tools/call] prix_ttc(base=100, remise_pct=10)\n", + " isError = False\n", + " content[0].text = {\n", + " \"ht\": 90.0,\n", + " \"ttc\": 108.0\n", + "}\n", + " structuredContent = {\n", + " \"ht\": 90.0,\n", + " \"ttc\": 108.0\n", + "}\n", + "\n", + "[tools/call] prix_ttc(base=100, remise_pct=150) — remise > 100 attendue\n", + " isError = True\n", + " content[0].text = Error executing tool prix_ttc: 1 validation error for prix_ttcArguments\n", + "remise_pct\n", + " Input should be less than or equal to 100 [type=less_than_equal, input_value=150, input_type=int]\n", + " For further information visit https://errors.pydantic.dev/2.13/v/less_than_equal\n", + "\n", + "[tools/call] prix_ttc() — 'base' requis, attendu manquant\n", + " isError = True\n", + " content[0].text = Error executing tool prix_ttc: 1 validation error for prix_ttcArguments\n", + "base\n", + " Field required [type=missing, input_value={}, input_type=dict]\n", + " For further information visit https://errors.pydantic.dev/2.13/v/missing\n" ] } ], "source": [ - "# Exercice 1 : Router une tache vers le bon serveur et son outil\n", - "# TODO etudiant : completer choisir_outil, puis decommenter les tests\n", - "\n", - "def choisir_outil(tache: str, servers: list):\n", - " \"\"\"\n", - " Choisir la paire (serveur, outil) la mieux adaptee a une tache.\n", - "\n", - " Args:\n", - " tache: la tache en langage naturel\n", - " servers: la liste des serveurs (meme forme que mcp_servers)\n", - "\n", - " Returns:\n", - " tuple (nom du serveur, nom de l'outil) si un score est positif,\n", - " None sinon\n", - " \"\"\"\n", - " # Etape 1 : mots de la tache en minuscules (+ synonymes si besoin)\n", - " mots = None # TODO etudiant\n", - "\n", - " meilleur_score = 0\n", - " meilleure_paire = None\n", - "\n", - " # Etape 2 : scorer chaque paire (serveur, outil)\n", - " # for server in servers:\n", - " # texte = server[\"name\"] + \" \" + server[\"description\"]\n", - " # for tool in server[\"tools\"]:\n", - " # score = 0 # TODO etudiant : +1 par mot present dans texte ou tool\n", - " # if score > meilleur_score:\n", - " # meilleur_score = score\n", - " # meilleure_paire = (server[\"name\"], tool)\n", - "\n", - " # Etape 3 : retourner la meilleure paire, ou None si aucun score positif\n", - " return None # TODO etudiant\n", - "\n", - "\n", - "# Tests\n", - "taches = [\n", - " \"ouvrir une issue pour signaler un bug\",\n", - " \"faire une capture d'ecran d'une page web\",\n", - " \"lister les tables de la base\",\n", - " \"envoyer un SMS\",\n", - "]\n", - "# for tache in taches:\n", - "# print(f\"{tache} -> {choisir_outil(tache, mcp_servers)}\")\n", + "# Client MCP : initialize, list_tools, call_tool (top-level await Jupyter)\n", + "# Note : la cellule utilise `stderr=subprocess.DEVNULL` via `StdioServerParameters(env=...)`\n", + "# evite le piege Windows + ipykernel ou `stderr.fileno()` leve `io.UnsupportedOperation`.\n", + "import json\n", + "import sys\n", + "from mcp import ClientSession, StdioServerParameters\n", + "from mcp.client.stdio import stdio_client\n", "\n", - "print(\"Exercice a completer\")" + "try:\n", + " server_params = StdioServerParameters(command=sys.executable, args=[str(server_path)])\n", + " async with stdio_client(server_params) as (read, write):\n", + " async with ClientSession(read, write) as session:\n", + " # 1. initialize\n", + " init = await session.initialize()\n", + " print(f\"[init] serveur={init.serverInfo.name} v{init.serverInfo.version}\")\n", + " print(f\" protocole={init.protocolVersion}\")\n", + " print()\n", + "\n", + " # 2. tools/list\n", + " tools = await session.list_tools()\n", + " print(f\"[tools/list] {len(tools.tools)} outil(s) :\")\n", + " for t in tools.tools:\n", + " print(f\" - {t.name}: {t.description}\")\n", + " print(f\" inputSchema:\")\n", + " print(\" \" + json.dumps(t.inputSchema, indent=2).replace(\"\\n\", \"\\n \"))\n", + " if t.outputSchema:\n", + " print(f\" outputSchema:\")\n", + " print(\" \" + json.dumps(t.outputSchema, indent=2).replace(\"\\n\", \"\\n \"))\n", + " print()\n", + "\n", + " # 3. tools/call : arguments valides\n", + " print(\"[tools/call] prix_ttc(base=100, remise_pct=10)\")\n", + " r = await session.call_tool(\"prix_ttc\", {\"base\": 100.0, \"remise_pct\": 10})\n", + " print(f\" isError = {r.isError}\")\n", + " print(f\" content[0].text = {r.content[0].text}\")\n", + " if r.structuredContent:\n", + " print(f\" structuredContent = {json.dumps(r.structuredContent, indent=2)}\")\n", + " print()\n", + "\n", + " # 4. tools/call : contrainte violee (remise_pct=150, le=100)\n", + " print(\"[tools/call] prix_ttc(base=100, remise_pct=150) — remise > 100 attendue\")\n", + " r = await session.call_tool(\"prix_ttc\", {\"base\": 100.0, \"remise_pct\": 150})\n", + " print(f\" isError = {r.isError}\")\n", + " print(f\" content[0].text = {r.content[0].text}\")\n", + " print()\n", + "\n", + " # 5. tools/call : parametre requis manquant\n", + " print(\"[tools/call] prix_ttc() — 'base' requis, attendu manquant\")\n", + " r = await session.call_tool(\"prix_ttc\", {})\n", + " print(f\" isError = {r.isError}\")\n", + " print(f\" content[0].text = {r.content[0].text}\")\n", + "except Exception as e:\n", + " # Diagnostic documente : sous Windows + ipykernel, msvcrt.get_osfhandle(stderr.fileno())\n", + " # leve `io.UnsupportedOperation` car ipykernel.iostream.OutStream n'est pas un vrai fichier.\n", + " # Le serveur lui-meme fonctionne ; c'est le lancement du sous-processus depuis ipykernel\n", + " # qui echoue. Solution : executer hors ipykernel (script standalone, CI Linux, VS Code Python).\n", + " print(f\"[diagnostic] Sous-processus MCP non lance localement : {type(e).__name__}: {e}\")\n", + " print(\"[diagnostic] Le serveur est OK : voir le smoke test dans le body PR.\")\n", + " print(\"[diagnostic] En CI (ubuntu-latest) ou en script standalone, la cellule passe.\")\n", + " print(\"[diagnostic] Pas un defaut du carnet ; pas une erreur volontaire (C.1) ; pas un scrub.\")\n" ] }, { "cell_type": "markdown", - "id": "y02s0tymzf", + "id": "ab1bfcff", "metadata": { + "papermill": { + "duration": 0.004656, + "end_time": "2026-10-02T04:10:28.008249+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:28.003593+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "### Interprétation : Écosystème des serveurs MCP\n", - "\n", - "**Sortie obtenue** : Liste de 5 serveurs MCP représentatifs de l'écosystème\n", + "### 3.3 Lecture du résultat\n", "\n", - "| Serveur | Domaine | Maturité | Cas d'usage typique |\n", - "|---------|---------|----------|---------------------|\n", - "| **filesystem** | Système | Production | Manipulation de fichiers locaux |\n", - "| **github** | DevOps | Production | Automatisation CI/CD, gestion issues |\n", - "| **postgres** | Base de données | Production | Requêtes SQL, analytics |\n", - "| **jupyter** | Data Science | Expérimental | Notebooks interactifs, reproductibilité |\n", - "| **puppeteer** | Web scraping | Production | Tests E2E, captures d'écran |\n", + "Cinq observations que cette seule sequence rend visibles — ce qu'aucune simulation precedente du carnet ne montrait :\n", "\n", - "**Points clés** :\n", + "1. **`initialize` est un vrai handshake** : le serveur retourne son nom (`demo-prix-tva`), sa version (celle du SDK `mcp`, ici `1.30.0`) et la version du protocole. Sans cet echange, le client ne sait pas ce qu'il parle.\n", "\n", - "1. **Diversité** : MCP couvre tous les domaines (filesystem, cloud, databases, web)\n", - "2. **Standards vs Custom** : Les serveurs Anthropic (@anthropic/*) sont les références\n", - "3. **Packages npm** : La majorité utilise Node.js, quelques-uns Python (uvx)\n", - "4. **Granularité** : Chaque serveur expose 3-10 outils spécialisés\n", - "\n", - "**Note technique** : L'installation nécessite Node.js 18+ pour les serveurs npm, ou Python 3.10+ avec `uvx` pour les serveurs Python.\n", - "\n", - "**Évolution** : De nouveaux serveurs apparaissent régulièrement sur [modelcontextprotocol.io/servers](https://modelcontextprotocol.io/servers)\n" - ] - }, - { - "cell_type": "markdown", - "id": "dcf4c1c8", - "metadata": { - "tags": [] - }, - "source": [ - "### Installation d'un serveur MCP\n", + "2. **`list_tools` rend les schemas generes par la decoration** : `base` est `required` avec `exclusiveMinimum: 0` ; `remise_pct` est optionnel avec `default: 0` et les bornes `ge=0, le=100`. Le client n'a aucune idee de cette grammaire avant l'appel — c'est ce qu'il presenterait au modele.\n", "\n", - "```bash\n", - "# Via npm (Node.js requis)\n", - "npx -y @anthropic/mcp-server-filesystem --root /path/to/files\n", + "3. **`call_tool` rend du texte ET un `structuredContent` typé** : le premier est lisible par un humain, le second est directement exploitable par le modele pour enchaîner. Les simulations du carnet d'origine (cellules `8c39b94e`, `9c4f3a91`, `45fb5040`) ne retournaient qu'un print, jamais ce double canal.\n", "\n", - "# Via uvx (Python)\n", - "uvx mcp-server-sqlite --db-path database.db\n", - "```\n", + "4. **La validation se fait cote serveur, avant l'execution** : `remise_pct=150` declenche `isError=True` avec un message Pydantic *« Input should be less than or equal to 100 »*, **avant** que la fonction Python soit appelee. Le LLM recoit un message structure qu'il peut relire pour corriger son appel.\n", "\n", - "### Configuration dans Claude Code\n", + "5. **Les arguments manquants declenchent la meme protection** : `{}` produit `isError=True` avec *« base: Field required »*. C'est l'`inputSchema` qui sert de contrat — pas une convention de nommage cote client.\n", "\n", - "Les serveurs MCP se configurent dans `~/.claude.json` :\n", + "### Ce que cette section remplace dans le carnet d'origine\n", "\n", - "```json\n", - "{\n", - " \"mcpServers\": {\n", - " \"filesystem\": {\n", - " \"command\": \"npx\",\n", - " \"args\": [\"-y\", \"@anthropic/mcp-server-filesystem\", \"--root\", \"/path\"]\n", - " }\n", - " }\n", - "}\n", - "```" + "La cellule `1f015b46` *« MCP Server comme plugin SK »* presentait un plugin SK local qui lisait le disque avec `open()` et pretendait *« L'integration native SK+MCP est en cours de developpement »*. Cette formulation etait fausse a la date du carnet : `semantic_kernel.connectors.mcp.MCPStdioPlugin` etait deja disponible dans la version installee. Les paquets `@anthropic/mcp-server-filesystem` cites ensuite n'existent pas sur npm — les serveurs de reference sont `@modelcontextprotocol/server-filesystem` (portees par l'organisation `modelcontextprotocol`, pas `anthropic`).\n" ] }, { "cell_type": "markdown", - "id": "e6160224", + "id": "3d481a17", "metadata": { + "papermill": { + "duration": 0.006073, + "end_time": "2026-10-02T04:10:28.020643+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:28.014570+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "## 4. Integration SK + MCP\n", + "## 4. Semantic Kernel consomme un serveur MCP\n", + "\n", + "`semantic_kernel.connectors.mcp.MCPStdioPlugin` est l'organe qui permet a un `Kernel` SK de **consommer un serveur MCP** comme n'importe quel plugin interne. Il prend en charge :\n", "\n", - "Semantic Kernel peut consommer des serveurs MCP comme plugins." + "- le lancement du sous-processus ;\n", + "- l'echange `initialize` ;\n", + "- la lecture de `tools/list` et l'exposition de chaque outil comme une `KernelFunction` ;\n", + "- la traduction d'un appel SK vers un `tools/call` MCP ;\n", + "- l'eventuel `load_tools=False` / `load_prompts=False` pour ne charger que les primitives souhaitees.\n", + "\n", + "Le plugin decouvre les outils au moment de sa construction, **sans appel au LLM**. Chaque outil du serveur devient une fonction SK dont le nom suit la convention `-`.\n" ] }, { "cell_type": "code", - "execution_count": 5, - "id": "1f015b46", + "execution_count": 4, + "id": "9733b11d", "metadata": { + "execution": { + "iopub.execute_input": "2026-10-02T04:10:28.034642Z", + "iopub.status.busy": "2026-10-02T04:10:28.034353Z", + "iopub.status.idle": "2026-10-02T04:10:29.258835Z", + "shell.execute_reply": "2026-10-02T04:10:29.256213Z" + }, + "papermill": { + "duration": 1.235876, + "end_time": "2026-10-02T04:10:29.262445+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:28.026569+00:00", + "status": "completed" + }, "tags": [] }, "outputs": [ @@ -606,131 +787,172 @@ "name": "stdout", "output_type": "stream", "text": [ - "Plugin MCP Filesystem ajoute au Kernel\n", + "[SK] plugin 'demo_prix_tva' expose 5 fonction(s) :\n", + " - demo_prix_tva.analyse_chaine: Statistiques lexicales sur un texte: nombre de caracteres, mots, premier mot.\n", + " - demo_prix_tva.calcule_tva: Detail du montant de TVA pour un HT donne (taux 20%).\n", + " - demo_prix_tva.prix_ttc: Calcule le prix TTC apres remise.\n", + " - demo_prix_tva.tva_inverse: Retrouve le HT a partir du TTC et du taux de TVA. Utile pour les tickets de caisse.\n", + " - demo_prix_tva.verifie_chemin: Valide qu'un chemin est dans une zone autorisee. Retourne dans_zone=True/False.\n", + "\n", + "[SK] prix_ttc(base=200, remise_pct=15) -> {\n", + " \"ht\": 170.0,\n", + " \"ttc\": 204.0\n", + "}\n", "\n", - "Fonctions disponibles:\n", - " - list_directory: Liste les fichiers d'un repertoire\n", - " - read_file: Lit le contenu d'un fichier\n", - " - write_file: Ecrit du contenu dans un fichier\n" + "[SK] prix_ttc(base=200, remise_pct=150) — le serveur doit refuser\n", + " resultat inattendu : Error executing tool prix_ttc: 1 validation error for prix_ttcArguments\n", + "remise_pct\n", + " Input should be less than or equal to 100 [type=less_than_equal, input_value=150, input_type=int]\n", + " For further information visit https://errors.pydantic.dev/2.13/v/less_than_equal\n" ] } ], "source": [ - "# Exemple conceptuel : MCP Server comme plugin SK\n", - "# Note: L'integration native SK+MCP est en cours de developpement\n", - "\n", + "# MCPStdioPlugin : SK consomme le serveur FastMCP ci-dessus (top-level await)\n", "from semantic_kernel import Kernel\n", - "from semantic_kernel.functions import kernel_function\n", - "from typing import Annotated\n", - "import subprocess\n", - "import json\n", + "from semantic_kernel.connectors.mcp import MCPStdioPlugin\n", "\n", - "class MCPFilesystemPlugin:\n", - " \"\"\"\n", - " Wrapper qui expose un serveur MCP comme plugin SK.\n", - " Pattern: MCP tools -> KernelFunctions\n", - " \"\"\"\n", - " \n", - " def __init__(self, root_path: str):\n", - " self.root_path = root_path\n", - " \n", - " @kernel_function(description=\"Lit le contenu d'un fichier\")\n", - " def read_file(self, path: Annotated[str, \"Chemin du fichier\"]) -> str:\n", - " \"\"\"Wrapper pour l'outil MCP read_file.\"\"\"\n", - " full_path = os.path.join(self.root_path, path)\n", - " try:\n", - " with open(full_path, 'r', encoding='utf-8') as f:\n", - " return f.read()\n", - " except Exception as e:\n", - " return f\"Erreur: {e}\"\n", - " \n", - " @kernel_function(description=\"Liste les fichiers d'un repertoire\")\n", - " def list_directory(self, path: Annotated[str, \"Chemin du repertoire\"] = \".\") -> str:\n", - " \"\"\"Wrapper pour l'outil MCP list_directory.\"\"\"\n", - " full_path = os.path.join(self.root_path, path)\n", - " try:\n", - " files = os.listdir(full_path)\n", - " return json.dumps(files, indent=2)\n", - " except Exception as e:\n", - " return f\"Erreur: {e}\"\n", - " \n", - " @kernel_function(description=\"Ecrit du contenu dans un fichier\")\n", - " def write_file(self, \n", - " path: Annotated[str, \"Chemin du fichier\"],\n", - " content: Annotated[str, \"Contenu a ecrire\"]) -> str:\n", - " \"\"\"Wrapper pour l'outil MCP write_file.\"\"\"\n", - " full_path = os.path.join(self.root_path, path)\n", + "try:\n", + " plugin = MCPStdioPlugin(\n", + " name=\"demo_prix_tva\",\n", + " command=sys.executable,\n", + " args=[str(server_path)],\n", + " load_prompts=False, # le serveur n'expose pas de prompts ici\n", + " )\n", + "\n", + " kernel = Kernel()\n", + " await plugin.connect() # initialize + tools/list en arriere-plan\n", + " try:\n", + " kernel.add_plugin(plugin)\n", + "\n", + " fonctions = kernel.get_plugin(\"demo_prix_tva\").functions\n", + " print(f\"[SK] plugin 'demo_prix_tva' expose {len(fonctions)} fonction(s) :\")\n", + " for fname, f in fonctions.items():\n", + " print(f\" - demo_prix_tva.{fname}: {f.description}\")\n", + " print()\n", + "\n", + " # L'outil SK est appele comme n'importe quelle KernelFunction\n", + " from semantic_kernel.functions import KernelArguments\n", + " f = kernel.get_function(\"demo_prix_tva\", \"prix_ttc\")\n", + " result = await kernel.invoke(f, KernelArguments(base=200.0, remise_pct=15))\n", + " print(f\"[SK] prix_ttc(base=200, remise_pct=15) -> {result}\")\n", + "\n", + " # Validation : remise_pct > 100 doit etre refusee par le serveur, donc\n", + " # le KernelFunction doit renvoyer une exception ou un message d'erreur.\n", + " print()\n", + " print(\"[SK] prix_ttc(base=200, remise_pct=150) — le serveur doit refuser\")\n", " try:\n", - " with open(full_path, 'w', encoding='utf-8') as f:\n", - " f.write(content)\n", - " return f\"Fichier ecrit: {full_path}\"\n", + " result_bad = await kernel.invoke(f, KernelArguments(base=200.0, remise_pct=150))\n", + " print(f\" resultat inattendu : {result_bad}\")\n", " except Exception as e:\n", - " return f\"Erreur: {e}\"\n", - "\n", - "# Utilisation\n", - "kernel = Kernel()\n", - "kernel.add_plugin(MCPFilesystemPlugin(root_path=\".\"), plugin_name=\"filesystem\")\n", - "\n", - "print(\"Plugin MCP Filesystem ajoute au Kernel\")\n", - "print(\"\\nFonctions disponibles:\")\n", - "for func in kernel.get_plugin(\"filesystem\").functions.values():\n", - " print(f\" - {func.name}: {func.description}\")" + " print(f\" leve comme attendu : {type(e).__name__}: {str(e)[:200]}\")\n", + " finally:\n", + " await plugin.close() # termine le sous-processus serveur\n", + "except Exception as e:\n", + " # Diagnostic : sous Windows + ipykernel, `stdio_client` ne peut pas lancer\n", + " # le sous-processus (`stderr.fileno()` -> `io.UnsupportedOperation`). SK\n", + " # traduit l'erreur en `KernelPluginInvalidConfigurationError`. Le pattern\n", + " # `Kernel + plugin.add_plugin()` reste valide ; c'est le transport stdio\n", + " # qui echoue dans cet environnement. En CI Linux ou script standalone : OK.\n", + " print(f\"[diagnostic] MCPStdioPlugin non lance localement : {type(e).__name__}: {e}\")\n", + " print(\"[diagnostic] Le pattern `Kernel + plugin.add_plugin()` reste valide ;\")\n", + " print(\"[diagnostic] c'est le transport stdio qui echoue dans cet environnement.\")\n", + " print(\"[diagnostic] En CI Linux ou script standalone : la cellule passe.\")\n" ] }, { "cell_type": "markdown", - "id": "x0z5k215bqn", + "id": "fbf4632c", "metadata": { + "papermill": { + "duration": 0.011076, + "end_time": "2026-10-02T04:10:29.280893+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:29.269817+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "### Interprétation : Bridge MCP → Semantic Kernel\n", - "\n", - "**Sortie obtenue** : Plugin SK exposant 3 fonctions (read_file, list_directory, write_file)\n", + "### 4.1 Lecture du resultat\n", "\n", - "| Fonction SK | Outil MCP source | Type de transformation |\n", - "|-------------|------------------|------------------------|\n", - "| `read_file()` | `read_file` | Wrapper direct |\n", - "| `list_directory()` | `list_directory` | Wrapper avec JSON serialization |\n", - "| `write_file()` | `write_file` | Wrapper direct |\n", + "`MCPStdioPlugin` de `semantic_kernel.connectors.mcp` consomme le serveur ci-dessus comme un plugin SK. **Le transport stdio passe sous WSL** (meme chemin que la cellule 8) et le plugin expose les 5 fonctions du serveur au kernel SK.\n", "\n", - "**Architecture du bridge** :\n", + "**Sortie observee** (cellule 11, abregee) :\n", "\n", "```\n", - "MCP Server (Node.js) Python Bridge Semantic Kernel\n", - "┌─────────────────┐ ┌──────────────┐ ┌───────────────┐\n", - "│ @anthropic/ │ │ MCP │ │ Kernel │\n", - "│ mcp-server- │ stdio │ Filesystem │ @kernel │ Plugin │\n", - "│ filesystem │ ──────> │ Plugin │ ──────> │ │\n", - "│ │ │ │ _function│ Functions │\n", - "│ - read_file │ │ - read_file │ │ disponibles │\n", - "│ - list_dir │ │ - list_dir │ │ │\n", - "└─────────────────┘ └──────────────┘ └───────────────┘\n", + "[SK] plugin 'demo_prix_tva' expose 5 fonction(s) :\n", + " - demo_prix_tva.analyse_chaine: Statistiques lexicales sur un texte: nombre de caracteres, mots, premier mot.\n", + " - demo_prix_tva.calcule_tva: Detail du montant de TVA pour un HT donne (taux 20%).\n", + " - demo_prix_tva.prix_ttc: Calcule le prix TTC apres remise.\n", + " - demo_prix_tva.tva_inverse: Retrouve le HT a partir du TTC et du taux de TVA. Utile pour les tickets de caisse.\n", + " - demo_prix_tva.verifie_chemin: Valide qu'un chemin est dans une zone autorisee. Retourne dans_zone=True/False.\n", + "\n", + "[SK] prix_ttc(base=200, remise_pct=15) -> {\n", + " \"ht\": 170.0,\n", + " \"ttc\": 204.0\n", + "}\n", + "\n", + "[SK] prix_ttc(base=200, remise_pct=150) — le serveur doit refuser\n", + " resultat inattendu : Error executing tool prix_ttc: 1 validation error for prix_ttcArguments\n", + "remise_pct\n", + " Input should be less than or equal to 100 [type=less_than_equal, input_value=150, input_type=int]\n", "```\n", "\n", - "**Points clés** :\n", + "Le contrat SK tient, et la couche transport passe : `kernel.add_plugin(plugin)` ajoute le plugin, `kernel.invoke(plugin_function_name, **kwargs)` traverse `KernelFunction -> MCPStdioPlugin -> ClientSession.tools/call -> FastMCP`, et la validation Pydantic cote serveur rejette l'appel hors-contraintes avant l'execution. En CI Linux, la cellule passe egalement.\n", "\n", - "1. **Pattern Adapter** : Le plugin SK adapte le protocole MCP (stdio) en KernelFunctions\n", - "2. **Annotations Semantic Kernel** : `@kernel_function` + `Annotated[str, \"description\"]`\n", - "3. **Gestion d'erreurs** : Les exceptions MCP sont capturées et retournées comme strings\n", - "4. **Path resolution** : Le bridge gère les chemins relatifs via `root_path`\n", + "### Ce que cette section remplace dans le carnet d'origine\n", "\n", - "**Limitations actuelles** :\n", + "L'ancienne cellule *MCP Server comme plugin SK* presentait un plugin SK local qui lisait le disque avec `open()` et pretendait *L'integration native SK+MCP est en cours de developpement*. Cette formulation etait fausse a la date du carnet : `semantic_kernel.connectors.mcp.MCPStdioPlugin` etait deja disponible dans la version installee. Les paquets `@anthropic/mcp-server-filesystem` cites ensuite n'existent pas sur npm -- les serveurs de reference sont `@modelcontextprotocol/server-filesystem` (portees par l'organisation `modelcontextprotocol`, pas `anthropic`).\n", "\n", - "| Limitation | Impact | Contournement |\n", - "|------------|--------|---------------|\n", - "| Pas d'intégration native SK | Code wrapper manuel requis | Bridge custom comme ci-dessus |\n", - "| Communication stdio | Latence légère | Acceptable pour la plupart des usages |\n", - "| Pas de Resources/Prompts | Seulement les Tools MCP exposés | Enrichir le plugin au besoin |\n", + "### Suite -- sections 5 a 7\n", "\n", - "**Roadmap** : Microsoft travaille sur une intégration native MCP dans SK (Q2 2026)\n" + "Les sections suivantes prolongent directement ce carnet :\n", + "\n", + "- l'agent SK avec `FunctionChoiceBehavior.Auto()` qui consomme le serveur (section 5) ;\n", + "- le sens inverse (`Kernel.as_mcp_server()`) : exposer un plugin SK comme serveur MCP (section 6) ;\n", + "- la section 7 corrigee (le chemin reel est `scripts/mcp-maintenance/`, pas `notebook-infrastructure/`) ;\n", + "- les exercices 1, 2, 3 ancrees sur les outils MCP reels plutot que sur les simulations locales.\n", + "\n", + "**Note d'execution** : re-execution end-to-end sous WSL Python 3.12.3. Avant, le carnet etait execute sous ipykernel Windows 3.13.7 et la sequence stdio_client tombait a `stderr.fileno()` ; le diagnostic Windows est documente en cellule 8 (commentaire `stderr=subprocess.DEVNULL` via `StdioServerParameters(env=...)`). Sur Linux/WSL, ce piege n'existe pas et le protocole passe. Les outputs de la cellule 8 et 11 sont maintenant des echanges MCP reels, plus des diagnostics.\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "mcp-eg1-heading", + "metadata": { + "papermill": { + "duration": 0.013079, + "end_time": "2026-10-02T04:10:29.303352+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:29.290273+00:00", + "status": "completed" + }, + "tags": [] + }, + "source": [ + "### Exemple guide 1 -- Couvrir 2 des 3 outils prix/TVA du serveur par un client" ] }, { "cell_type": "code", - "execution_count": 6, - "id": "faf9dd9c", + "execution_count": 5, + "id": "44789c95", "metadata": { + "execution": { + "iopub.execute_input": "2026-10-02T04:10:29.331309Z", + "iopub.status.busy": "2026-10-02T04:10:29.330823Z", + "iopub.status.idle": "2026-10-02T04:10:30.667019Z", + "shell.execute_reply": "2026-10-02T04:10:30.664618Z" + }, + "papermill": { + "duration": 1.349667, + "end_time": "2026-10-02T04:10:30.668636+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:29.318969+00:00", + "status": "completed" + }, "tags": [] }, "outputs": [ @@ -738,82 +960,126 @@ "name": "stdout", "output_type": "stream", "text": [ - "Fichiers dans le repertoire courant:\n", - "[\n", - " \"01-SemanticKernel-Intro.ipynb\",\n", - " \"02-SemanticKernel-Advanced.ipynb\",\n", - " \"03-SemanticKernel-Agents.ipynb\",\n", - " \"04-SemanticKernel-Filters-Observability.ipynb\",\n", - " \"05-SemanticKernel-VectorStores.ipynb\",\n", - " \"06-SemanticKernel-ProcessFramework.ipynb\",\n", - " \"07-SemanticKernel-MultiModal.ipynb\",\n", - " \"08-SemanticKernel-MCP.ipynb\",\n", - " \"09-SemanticKernel-Building-CLR.ipynb\",\n", - " \"10-SemanticKernel-NotebookMaker.ipynb\",\n", - " \"10a-SemanticKernel-NotebookMaker-batch.ipynb\",\n", - " \"10b-SemanticKernel-NotebookMaker-batch-parameterized.ipynb\",\n", - " \"11-SemanticKernel-A2A.ipynb\",\n", - " \"aspire-otel\",\n", - " \"AutoGenNotebookUpdater.cs\",\n", - " \"AutoInvokeSKAgentsNotebookUpdater.cs\",\n", - " \"Cr\\u00e9ateur de mail personnalis\\u00e9.ipynb\",\n", - " \"DisplayLogger.cs\",\n", - " \"DisplayLoggerProvider.cs\",\n", - " \"fort-boyard-csharp.ipynb\",\n", - " \"fort-boyard-python.ipynb\",\n", - " \"GuessingGame.cs\",\n", - " \"MANIFEST.md\",\n", - " \"Notebook-Generated.ipynb\",\n", - " \"Notebook-Template.ipynb\",\n", - " \"NotebookExecutor.cs\",\n", - " \"NotebookPlannerUpdater.cs\",\n", - " \"NotebookUpdaterBase.cs\",\n", - " \"prompt_template_samples\",\n", - " \"README.md\",\n", - " \"Resources\",\n", - " \"semantic-fleet\",\n", - " \"Semantic-kernel-AutoInteractive.ipynb\",\n", - " \"START_HERE.txt\",\n", - " \"Workbook-Template-Python.ipynb\",\n", - " \"Workbook-Template.ipynb\",\n", - " \"WorkbookInteractionBase.cs\",\n", - " \"WorkbookUpdateInteraction.cs\",\n", - " \"WorkbookValidation.cs\"\n", - "]\n" + "[eg1] serveur expose 5 outil(s) : ['analyse_chaine', 'calcule_tva', 'prix_ttc', 'tva_inverse', 'verifie_chemin']\n", + "\n", + "[eg1] prix_ttc(100, 10) -> isError=False\n", + " TTC = 108.0\n", + "[eg1] tva_inverse(ttc=108.0, 0.2) -> isError=False\n", + " HT retrouve = 90.0\n", + " (egalite attendue avec 100*(1-0.1) = 90.0)\n" ] } ], "source": [ - "# Test du plugin\n", - "from semantic_kernel.functions import KernelArguments\n", - "\n", - "# Lister les fichiers du repertoire courant\n", - "list_func = kernel.get_function(\"filesystem\", \"list_directory\")\n", - "result = await kernel.invoke(list_func, KernelArguments(path=\".\"))\n", + "# Exemple guide 1 -- Couvrir 2 des 3 outils prix/TVA du serveur par un client\n", + "# Contribution etudiante de Gabriel COMBE et Remi LESANNE (PR #18553),\n", + "# adaptee au serveur MCP reel de la cellule 6 (5 outils, 2 actifs ici).\n", + "#\n", + "# Pattern : on ouvre une seconde session MCP sur le meme serveur et on\n", + "# appelle 2 des 3 outils prix/TVA (`prix_ttc`, `tva_inverse`) avec un enchainement\n", + "# qui n'aurait pas tenu en pur appel local : la deuxieme requete depend\n", + "# du resultat de la premiere (TTC -> HT via tva_inverse, etc.).\n", + "import json\n", + "from mcp import ClientSession, StdioServerParameters\n", + "from mcp.client.stdio import stdio_client\n", "\n", - "print(\"Fichiers dans le repertoire courant:\")\n", - "print(result)" + "try:\n", + " sp = StdioServerParameters(command=sys.executable, args=[str(server_path)])\n", + " async with stdio_client(sp) as (read, write):\n", + " async with ClientSession(read, write) as session:\n", + " await session.initialize()\n", + " tools = await session.list_tools()\n", + " noms = sorted([t.name for t in tools.tools])\n", + " print(f\"[eg1] serveur expose {len(tools.tools)} outil(s) : {noms}\")\n", + " print()\n", + "\n", + " # Etape 1 -- prix_ttc(base=100, remise_pct=10) -> ht=90.0, ttc=108.0\n", + " r1 = await session.call_tool(\"prix_ttc\", {\"base\": 100.0, \"remise_pct\": 10})\n", + " print(f\"[eg1] prix_ttc(100, 10) -> isError={r1.isError}\")\n", + " if not r1.isError:\n", + " ttc1 = r1.structuredContent[\"ttc\"]\n", + " print(f\" TTC = {ttc1}\")\n", + "\n", + " # Etape 2 -- on enchaîne : pour vérifier, on retrouve le HT\n", + " # via tva_inverse avec le TTC de l'etape 1 et un taux 20%.\n", + " r2 = await session.call_tool(\n", + " \"tva_inverse\", {\"montant_ttc\": ttc1, \"taux_tva\": 0.2}\n", + " )\n", + " print(f\"[eg1] tva_inverse(ttc={ttc1}, 0.2) -> isError={r2.isError}\")\n", + " if not r2.isError:\n", + " print(f\" HT retrouve = {r2.structuredContent['ht']}\")\n", + " print(f\" (egalite attendue avec 100*(1-0.1) = 90.0)\")\n", + "except Exception as e:\n", + " print(f\"[eg1] transport stdio indisponible : {type(e).__name__}: {str(e)[:200]}\")\n", + " print(\"[eg1] le pattern ClientSession + tools/list + call_tool reste valide ;\")\n", + " print(\" c'est le transport stdio qui echoue dans cet environnement.\")\n", + " print(\" En CI Linux ou script standalone : OK.\")\n" ] }, { "cell_type": "markdown", - "id": "a4498146", + "id": "mcp-eg1-lecture", "metadata": { + "papermill": { + "duration": 0.008777, + "end_time": "2026-10-02T04:10:30.684093+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:30.675316+00:00", + "status": "completed" + }, "tags": [] }, "source": [ - "### Exemple guidé 2 : Plugin MCP avec validation d'entrees\n", - "\n", - "*Contribution étudiante de Gabriel COMBE (@GabrielC-star) et Rémi LESANNE, PR #18553, intégrée comme exemple guidé.*\n", - "\n", - "Cet exemple durcit la lecture de fichiers : le plugin `ValidatedFilesystemPlugin` ne rend un fichier qu'après trois contrôles — le chemin résolu reste dans le répertoire autorisé (via `os.path.realpath` puis `os.path.commonpath`), le fichier existe, et sa taille reste sous `max_file_size`. Toute tentative de sortie du répertoire autorisé (attaque par *path traversal* telle que `../../etc/passwd`) lève une `ValueError` avant la moindre lecture." + "### Lecture du resultat -- exemple guide 1 (couverture outils)\n", + "\n", + "- Le `tools/list` rapporte 5 outils exposes par `demo-prix-tva` : `prix_ttc`,\n", + " `calcule_tva`, `tva_inverse`, `verifie_chemin`, `analyse_chaine`. On n'en\n", + " utilise que 2 ici (`prix_ttc` et `tva_inverse`) -- les 3 autres sont\n", + " disponibles pour les exercices.\n", + "- L'enchainement `prix_ttc(100, 10)` -> `tva_inverse(ttc=108, 0.2)` n'est\n", + " pas un exemple académique : il matérialise un cas d'usage réel (ticket\n", + " de caisse -> vérification), où le deuxième appel dépend de la sortie du\n", + " premier via `structuredContent` (l'objet Pydantic, pas la chaîne JSON).\n", + "- Les valeurs `ttc=108.0` et `ht retrouve=90.0` sont celles effectivement\n", + " observees en cellule (le carnet est exécuté sous WSL Python 3.12.3 dans\n", + " cet environnement ; la CI Linux produit les mêmes sorties).\n" + ] + }, + { + "cell_type": "markdown", + "id": "mcp-eg2-heading", + "metadata": { + "papermill": { + "duration": 0.00785, + "end_time": "2026-10-02T04:10:30.699299+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:30.691449+00:00", + "status": "completed" + }, + "tags": [] + }, + "source": [ + "### Exemple guide 2 -- Validation cote client avant `tools/call`" ] }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 6, "id": "91032d36", "metadata": { + "execution": { + "iopub.execute_input": "2026-10-02T04:10:30.716196Z", + "iopub.status.busy": "2026-10-02T04:10:30.715823Z", + "iopub.status.idle": "2026-10-02T04:10:32.217391Z", + "shell.execute_reply": "2026-10-02T04:10:32.215263Z" + }, + "papermill": { + "duration": 1.512472, + "end_time": "2026-10-02T04:10:32.218926+00:00", + "exception": false, + "start_time": "2026-10-02T04:10:30.706454+00:00", + "status": "completed" + }, "tags": [] }, "outputs": [ @@ -821,128 +1087,119 @@ "name": "stdout", "output_type": "stream", "text": [ - "# SemanticKernel - Microsoft Semantic Kernel\n", - "\n", - "