[{"data":1,"prerenderedAt":1395},["ShallowReactive",2],{"series-\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context":3,"series-context-\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers":1201},{"id":4,"title":5,"body":6,"contentId":1186,"date":1187,"description":1188,"extension":1189,"github":1190,"meetTheInstructor":1192,"meta":1193,"navigation":410,"part":79,"path":1194,"rawbody":1195,"robots":1192,"schemaOrg":1192,"seo":1196,"seriesSlug":1197,"sitemap":1198,"stem":1199,"subtitle":1192,"topics":1192,"__hash__":1200},"series\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context.md","Chercher dans OpenAPI sans saturer la fenêtre de contexte",{"type":7,"value":8,"toc":1179},"minimark",[9,13,16,21,32,40,260,267,270,290,293,296,299,303,306,309,320,328,331,342,345,349,352,355,358,367,370,576,579,582,585,589,592,846,849,852,858,861,864,1111,1114,1121,1124,1130,1133,1150,1153,1156,1160,1163,1175],[10,11,12],"p",{},"Dans l'article précédent, nous avons découvert le Code Mode et l'intérêt de laisser le modèle écrire le code d'orchestration au lieu d'appeler directement les outils.",[10,14,15],{},"Dans cette troisième partie, nous allons voir comment utiliser le Code Mode lorsque la fenêtre de contexte est limitée ou lorsqu'un document, ici une spécification OpenAPI, dépasse la taille de cette fenêtre.",[17,18,20],"h2",{"id":19},"le-problème-de-la-fenêtre-de-contexte","Le problème de la fenêtre de contexte",[10,22,23,24,31],{},"Lorsque nous développons un service ou une application, nous construisons souvent une API pour permettre à d'autres services d'interagir avec notre système. Les développeurs apprennent traditionnellement à utiliser cette API grâce à des sites de documentation, comme la ",[25,26,30],"a",{"href":27,"rel":28},"https:\u002F\u002Fdevelopers.cloudflare.com\u002Fapi\u002F",[29],"nofollow","référence de l'API Cloudflare",".",[10,33,34,35,31],{},"Pour faciliter la création et la maintenance de ces sites, tout en les gardant synchronisés avec l'API réelle, le secteur a créé un format de spécification : ",[25,36,39],{"href":37,"rel":38},"https:\u002F\u002Fswagger.io\u002Fspecification\u002F",[29],"OpenAPI",[41,42,48],"pre",{"className":43,"code":44,"filename":45,"language":46,"meta":47,"style":47},"language-yaml shiki shiki-themes github-light github-light github-dark","openapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0\npaths:\n  \u002Fusers:\n    get:\n      summary: Get all users\n      responses:\n        '200':\n          description: A list of users\n          content:\n            application\u002Fjson:\n              schema:\n                type: array\n                items:\n                  type: object\n                  properties:\n                    id:\n                      type: string\n                    name:\n                      type: string\n","Exemple","yaml","",[49,50,51,68,77,89,100,108,116,124,135,143,151,162,170,178,186,197,205,216,224,232,243,251],"code",{"__ignoreMap":47},[52,53,56,60,64],"span",{"class":54,"line":55},"line",1,[52,57,59],{"class":58},"sovSZ","openapi",[52,61,63],{"class":62},"sxrX7",": ",[52,65,67],{"class":66},"sBjJW","3.0.0\n",[52,69,71,74],{"class":54,"line":70},2,[52,72,73],{"class":58},"info",[52,75,76],{"class":62},":\n",[52,78,80,83,85],{"class":54,"line":79},3,[52,81,82],{"class":58},"  title",[52,84,63],{"class":62},[52,86,88],{"class":87},"sIIMD","Sample API\n",[52,90,92,95,97],{"class":54,"line":91},4,[52,93,94],{"class":58},"  version",[52,96,63],{"class":62},[52,98,99],{"class":66},"1.0.0\n",[52,101,103,106],{"class":54,"line":102},5,[52,104,105],{"class":58},"paths",[52,107,76],{"class":62},[52,109,111,114],{"class":54,"line":110},6,[52,112,113],{"class":58},"  \u002Fusers",[52,115,76],{"class":62},[52,117,119,122],{"class":54,"line":118},7,[52,120,121],{"class":58},"    get",[52,123,76],{"class":62},[52,125,127,130,132],{"class":54,"line":126},8,[52,128,129],{"class":58},"      summary",[52,131,63],{"class":62},[52,133,134],{"class":87},"Get all users\n",[52,136,138,141],{"class":54,"line":137},9,[52,139,140],{"class":58},"      responses",[52,142,76],{"class":62},[52,144,146,149],{"class":54,"line":145},10,[52,147,148],{"class":87},"        '200'",[52,150,76],{"class":62},[52,152,154,157,159],{"class":54,"line":153},11,[52,155,156],{"class":58},"          description",[52,158,63],{"class":62},[52,160,161],{"class":87},"A list of users\n",[52,163,165,168],{"class":54,"line":164},12,[52,166,167],{"class":58},"          content",[52,169,76],{"class":62},[52,171,173,176],{"class":54,"line":172},13,[52,174,175],{"class":58},"            application\u002Fjson",[52,177,76],{"class":62},[52,179,181,184],{"class":54,"line":180},14,[52,182,183],{"class":58},"              schema",[52,185,76],{"class":62},[52,187,189,192,194],{"class":54,"line":188},15,[52,190,191],{"class":58},"                type",[52,193,63],{"class":62},[52,195,196],{"class":87},"array\n",[52,198,200,203],{"class":54,"line":199},16,[52,201,202],{"class":58},"                items",[52,204,76],{"class":62},[52,206,208,211,213],{"class":54,"line":207},17,[52,209,210],{"class":58},"                  type",[52,212,63],{"class":62},[52,214,215],{"class":87},"object\n",[52,217,219,222],{"class":54,"line":218},18,[52,220,221],{"class":58},"                  properties",[52,223,76],{"class":62},[52,225,227,230],{"class":54,"line":226},19,[52,228,229],{"class":58},"                    id",[52,231,76],{"class":62},[52,233,235,238,240],{"class":54,"line":234},20,[52,236,237],{"class":58},"                      type",[52,239,63],{"class":62},[52,241,242],{"class":87},"string\n",[52,244,246,249],{"class":54,"line":245},21,[52,247,248],{"class":58},"                    name",[52,250,76],{"class":62},[52,252,254,256,258],{"class":54,"line":253},22,[52,255,237],{"class":58},[52,257,63],{"class":62},[52,259,242],{"class":87},[10,261,262,263,266],{},"Cet exemple présente une spécification OpenAPI simple pour une API qui possède un seul endpoint, ",[49,264,265],{},"\u002Fusers",", et renvoie une liste d'utilisateurs. La spécification décrit l'endpoint, la méthode HTTP, la réponse attendue et le format des données.",[10,268,269],{},"Ce format est très utile pour les traitements automatisés et peut générer une documentation pratique pour les humains. Une spécification brute volumineuse reste toutefois difficile à parcourir manuellement et peut dépasser la fenêtre de contexte d'un modèle. Dans ce cas, nous ne pouvons pas simplement transmettre le document complet au modèle et espérer qu'il l'utilise correctement.",[271,272,273,282],"ul",{},[274,275,276,281],"li",{},[25,277,280],{"href":278,"rel":279},"https:\u002F\u002Fgithub.com\u002Fgithub\u002Frest-api-description\u002Fblob\u002Fmain\u002Fdescriptions\u002Fghes-3.21\u002Fghes-3.21.json",[29],"La spécification OpenAPI de GitHub GHES 3.21"," pèse 11,1 Mo.",[274,283,284,289],{},[25,285,288],{"href":286,"rel":287},"https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fapi-schemas\u002Fblob\u002Fmain\u002Fopenapi.json",[29],"La spécification OpenAPI de Cloudflare"," pèse 22,7 Mo.",[10,291,292],{},"Ces fichiers évoluent, leurs tailles exactes changeront donc avec le temps. Le point important est que les descriptions d'API réelles peuvent être bien plus volumineuses que les informations nécessaires à une tâche donnée.",[10,294,295],{},"L'instantané Cloudflare utilisé dans cette série contient 23 792 523 caractères. L'approximation courante de quatre caractères par jeton donne environ 6 millions de jetons, même si la tokenisation varie selon le modèle et le contenu. Dans tous les cas, ce volume dépasse largement de nombreuses fenêtres de contexte disponibles.",[10,297,298],{},"Nous ne pouvons pas transmettre toute la spécification au modèle.",[17,300,302],{"id":301},"les-spécifications-openapi-sadressent-aux-humains-et-aux-machines","Les spécifications OpenAPI s'adressent aux humains et aux machines",[10,304,305],{},"OpenAPI permet aux humains comme aux logiciels de comprendre une API. Un générateur de documentation peut transformer la spécification en site web, tandis qu'un générateur de client peut la convertir en code. Pour un modèle, renvoyer toute la spécification dans le contexte reste généralement une mauvaise interface. Le modèle a besoin des endpoints et des schémas utiles à sa tâche, pas de toutes les opérations de l'API.",[10,307,308],{},"Rien ne nous empêche cependant de construire un outil capable de rechercher dans la spécification OpenAPI et de ne renvoyer que les informations pertinentes. Imaginez que vous intégrez une plateforme de vente en ligne et que vous cherchez comment créer un retour.",[10,310,311,312,315,316,319],{},"Au lieu d'utiliser ",[49,313,314],{},"Ctrl+F"," ou ",[49,317,318],{},"Cmd+F"," dans la spécification OpenAPI, pourquoi ne pas appliquer l'algorithme suivant ?",[41,321,326],{"className":322,"code":324,"filename":45,"language":325,"meta":47},[323],"language-text","searchTerm = \"return\"\nresults = []\n\nfor each URL path and path item in spec.paths:\n    for each HTTP method and operation in the path item:\n        if the entry is not an HTTP operation:\n            continue\n\n        searchableText = combine:\n            - the URL path\n            - the operation ID\n            - the summary\n            - the description\n            - the operation tags\n\n        if searchableText does not contain searchTerm:\n            continue\n\n        endpoint = {\n            method: the HTTP method in uppercase,\n            path: the URL path,\n            operationId: the operation ID,\n            summary: the operation summary,\n            parameters: [\n                for each parameter:\n                    keep its name, location, and required flag\n            ],\n            requestBody: keep only its content types and required flag,\n            responses: [\n                for each response:\n                    keep its status code and description\n            ]\n        }\n\n        add endpoint to results\n\nreturn results\n","text",[49,327,324],{"__ignoreMap":47},[10,329,330],{},"Nous n'extrayons ainsi que les informations pertinentes. Mais nous pouvons aller plus loin.",[10,332,333,334,337,338,341],{},"Même avec un tel algorithme, nous devons encore exécuter le code manuellement et rien ne garantit qu'il couvrira tous les cas. Pour créer un retour, nous pourrions par exemple ne conserver que les endpoints qui utilisent la méthode ",[49,335,336],{},"POST",". Un filtrage par tags serait peut-être plus efficace que de deviner les bons mots à rechercher dans le résumé et la description. Nous pourrions aussi ne conserver que les endpoints qui possèdent un code de réponse ",[49,339,340],{},"200",". Les possibilités de filtrage varient selon le client, les données nécessaires et la tâche à accomplir. Écrire un algorithme générique devient donc bien trop complexe.",[10,343,344],{},"Il faudrait écrire un algorithme personnalisé pour chaque cas d'usage.",[17,346,348],{"id":347},"les-llm-connaissent-le-code-et-les-algorithmes","Les LLM connaissent le code et les algorithmes",[10,350,351],{},"Ou nous pouvons déléguer cette tâche à un LLM.",[10,353,354],{},"Les LLM savent notamment générer du code. Ils peuvent transformer une demande précise en petit programme de recherche que les développeurs peuvent relire et exécuter.",[10,356,357],{},"Au lieu d'écrire un algorithme générique, ou des milliers pour tenter de couvrir tous les cas, nous pourrions simplement demander au LLM d'écrire celui dont nous avons besoin. Il ne resterait ensuite qu'à l'exécuter. Le LLM recevrait exactement les informations utiles, sans que la fenêtre de contexte devienne un problème.",[10,359,360,361,366],{},"J'ai découvert cette idée dans un article de Cloudflare intitulé ",[25,362,365],{"href":363,"rel":364},"https:\u002F\u002Fblog.cloudflare.com\u002Fcode-mode\u002F",[29],"Code Mode",", et ma première réaction a été « quoi ? ». J'ai dû le lire plus de deux fois pour vraiment comprendre le concept. Prenons un exemple.",[10,368,369],{},"Imaginez que vous souhaitiez créer un retour sur une plateforme de vente en ligne. Au lieu de fournir toute la spécification OpenAPI au modèle, vous pourriez écrire la méthode suivante :",[41,371,375],{"className":372,"code":373,"filename":45,"language":374,"meta":47,"style":47},"language-js shiki shiki-themes github-light github-light github-dark","async () => {\n  const results = []\n\n  for (const [path, methods] of Object.entries(spec.paths)) {\n    const operation = methods.post\n\n    if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {\n      results.push({\n        method: 'POST',\n        path,\n        summary: operation.summary,\n        requestBody: operation.requestBody\n      })\n    }\n  }\n\n  return results\n}\n","js",[49,376,377,392,406,412,451,464,468,507,518,529,534,539,544,549,554,559,563,571],{"__ignoreMap":47},[52,378,379,383,386,389],{"class":54,"line":55},[52,380,382],{"class":381},"s8jYJ","async",[52,384,385],{"class":62}," () ",[52,387,388],{"class":381},"=>",[52,390,391],{"class":62}," {\n",[52,393,394,397,400,403],{"class":54,"line":70},[52,395,396],{"class":381},"  const",[52,398,399],{"class":66}," results",[52,401,402],{"class":381}," =",[52,404,405],{"class":62}," []\n",[52,407,408],{"class":54,"line":79},[52,409,411],{"emptyLinePlaceholder":410},true,"\n",[52,413,414,417,420,423,426,429,432,435,438,441,444,448],{"class":54,"line":91},[52,415,416],{"class":381},"  for",[52,418,419],{"class":62}," (",[52,421,422],{"class":381},"const",[52,424,425],{"class":62}," [",[52,427,428],{"class":66},"path",[52,430,431],{"class":62},", ",[52,433,434],{"class":66},"methods",[52,436,437],{"class":62},"] ",[52,439,440],{"class":381},"of",[52,442,443],{"class":62}," Object.",[52,445,447],{"class":446},"snPdu","entries",[52,449,450],{"class":62},"(spec.paths)) {\n",[52,452,453,456,459,461],{"class":54,"line":102},[52,454,455],{"class":381},"    const",[52,457,458],{"class":66}," operation",[52,460,402],{"class":381},[52,462,463],{"class":62}," methods.post\n",[52,465,466],{"class":54,"line":110},[52,467,411],{"emptyLinePlaceholder":410},[52,469,470,473,476,479,482,486,489,492,495,498,501,504],{"class":54,"line":118},[52,471,472],{"class":381},"    if",[52,474,475],{"class":62}," (operation?.tags?.",[52,477,478],{"class":446},"some",[52,480,481],{"class":62},"(",[52,483,485],{"class":484},"sP4rz","tag",[52,487,488],{"class":381}," =>",[52,490,491],{"class":62}," tag.",[52,493,494],{"class":446},"toLowerCase",[52,496,497],{"class":62},"() ",[52,499,500],{"class":381},"===",[52,502,503],{"class":87}," 'returns'",[52,505,506],{"class":62},")) {\n",[52,508,509,512,515],{"class":54,"line":126},[52,510,511],{"class":62},"      results.",[52,513,514],{"class":446},"push",[52,516,517],{"class":62},"({\n",[52,519,520,523,526],{"class":54,"line":137},[52,521,522],{"class":62},"        method: ",[52,524,525],{"class":87},"'POST'",[52,527,528],{"class":62},",\n",[52,530,531],{"class":54,"line":145},[52,532,533],{"class":62},"        path,\n",[52,535,536],{"class":54,"line":153},[52,537,538],{"class":62},"        summary: operation.summary,\n",[52,540,541],{"class":54,"line":164},[52,542,543],{"class":62},"        requestBody: operation.requestBody\n",[52,545,546],{"class":54,"line":172},[52,547,548],{"class":62},"      })\n",[52,550,551],{"class":54,"line":180},[52,552,553],{"class":62},"    }\n",[52,555,556],{"class":54,"line":188},[52,557,558],{"class":62},"  }\n",[52,560,561],{"class":54,"line":199},[52,562,411],{"emptyLinePlaceholder":410},[52,564,565,568],{"class":54,"line":207},[52,566,567],{"class":381},"  return",[52,569,570],{"class":62}," results\n",[52,572,573],{"class":54,"line":218},[52,574,575],{"class":62},"}\n",[10,577,578],{},"Ce code permet de rechercher rapidement dans la spécification OpenAPI et de ne renvoyer que les informations pertinentes.",[10,580,581],{},"Mais qui veut écrire ce code ? Personne.",[10,583,584],{},"Heureusement, les LLM peuvent le générer à notre place. Donnez-leur accès à la spécification OpenAPI et quelques exemples, et ils pourront parcourir toute la spécification pour trouver uniquement ce qui compte.",[17,586,588],{"id":587},"outil-description-et-langage","Outil, description et langage",[10,590,591],{},"Dans notre MCP, l'outil de recherche ressemblerait à ceci :",[41,593,598],{"className":594,"code":595,"filename":596,"language":597,"meta":47,"style":47},"language-typescript shiki shiki-themes github-light github-light github-dark","server.registerTool(\n  'search',\n  {\n    title: 'Search OpenAPI Specification',\n    description: '...',\n    inputSchema: z.object({\n      code: z\n        .string()\n        .max(MAX_CODE_LENGTH)\n        .describe('An async arrow function that searches the OpenAPI spec')\n    }),\n  },\n  async ({ code }) => {\n    try {\n      const result = await evaluateSearchCode(code)\n      return { content: [{ type: 'text', text: formatSearchResult(result) }] }\n    }\n    catch (error) {\n      return {\n        content: [{ type: 'text', text: `Search failed: ${errorMessage(error)}` }],\n        isError: true\n      }\n    }\n  }\n)\n","search.ts","typescript",[49,599,600,611,618,623,633,643,653,658,669,684,698,703,708,725,732,751,771,775,783,789,818,826,831,836,841],{"__ignoreMap":47},[52,601,602,605,608],{"class":54,"line":55},[52,603,604],{"class":62},"server.",[52,606,607],{"class":446},"registerTool",[52,609,610],{"class":62},"(\n",[52,612,613,616],{"class":54,"line":70},[52,614,615],{"class":87},"  'search'",[52,617,528],{"class":62},[52,619,620],{"class":54,"line":79},[52,621,622],{"class":62},"  {\n",[52,624,625,628,631],{"class":54,"line":91},[52,626,627],{"class":62},"    title: ",[52,629,630],{"class":87},"'Search OpenAPI Specification'",[52,632,528],{"class":62},[52,634,635,638,641],{"class":54,"line":102},[52,636,637],{"class":62},"    description: ",[52,639,640],{"class":87},"'...'",[52,642,528],{"class":62},[52,644,645,648,651],{"class":54,"line":110},[52,646,647],{"class":62},"    inputSchema: z.",[52,649,650],{"class":446},"object",[52,652,517],{"class":62},[52,654,655],{"class":54,"line":118},[52,656,657],{"class":62},"      code: z\n",[52,659,660,663,666],{"class":54,"line":126},[52,661,662],{"class":62},"        .",[52,664,665],{"class":446},"string",[52,667,668],{"class":62},"()\n",[52,670,671,673,676,678,681],{"class":54,"line":137},[52,672,662],{"class":62},[52,674,675],{"class":446},"max",[52,677,481],{"class":62},[52,679,680],{"class":66},"MAX_CODE_LENGTH",[52,682,683],{"class":62},")\n",[52,685,686,688,691,693,696],{"class":54,"line":145},[52,687,662],{"class":62},[52,689,690],{"class":446},"describe",[52,692,481],{"class":62},[52,694,695],{"class":87},"'An async arrow function that searches the OpenAPI spec'",[52,697,683],{"class":62},[52,699,700],{"class":54,"line":153},[52,701,702],{"class":62},"    }),\n",[52,704,705],{"class":54,"line":164},[52,706,707],{"class":62},"  },\n",[52,709,710,713,716,718,721,723],{"class":54,"line":172},[52,711,712],{"class":381},"  async",[52,714,715],{"class":62}," ({ ",[52,717,49],{"class":484},[52,719,720],{"class":62}," }) ",[52,722,388],{"class":381},[52,724,391],{"class":62},[52,726,727,730],{"class":54,"line":180},[52,728,729],{"class":381},"    try",[52,731,391],{"class":62},[52,733,734,737,740,742,745,748],{"class":54,"line":188},[52,735,736],{"class":381},"      const",[52,738,739],{"class":66}," result",[52,741,402],{"class":381},[52,743,744],{"class":381}," await",[52,746,747],{"class":446}," evaluateSearchCode",[52,749,750],{"class":62},"(code)\n",[52,752,753,756,759,762,765,768],{"class":54,"line":199},[52,754,755],{"class":381},"      return",[52,757,758],{"class":62}," { content: [{ type: ",[52,760,761],{"class":87},"'text'",[52,763,764],{"class":62},", text: ",[52,766,767],{"class":446},"formatSearchResult",[52,769,770],{"class":62},"(result) }] }\n",[52,772,773],{"class":54,"line":207},[52,774,553],{"class":62},[52,776,777,780],{"class":54,"line":218},[52,778,779],{"class":381},"    catch",[52,781,782],{"class":62}," (error) {\n",[52,784,785,787],{"class":54,"line":226},[52,786,755],{"class":381},[52,788,391],{"class":62},[52,790,791,794,796,798,801,804,806,809,812,815],{"class":54,"line":234},[52,792,793],{"class":62},"        content: [{ type: ",[52,795,761],{"class":87},[52,797,764],{"class":62},[52,799,800],{"class":87},"`Search failed: ${",[52,802,803],{"class":446},"errorMessage",[52,805,481],{"class":87},[52,807,808],{"class":62},"error",[52,810,811],{"class":87},")",[52,813,814],{"class":87},"}`",[52,816,817],{"class":62}," }],\n",[52,819,820,823],{"class":54,"line":245},[52,821,822],{"class":62},"        isError: ",[52,824,825],{"class":66},"true\n",[52,827,828],{"class":54,"line":253},[52,829,830],{"class":62},"      }\n",[52,832,834],{"class":54,"line":833},23,[52,835,553],{"class":62},[52,837,839],{"class":54,"line":838},24,[52,840,558],{"class":62},[52,842,844],{"class":54,"line":843},25,[52,845,683],{"class":62},[10,847,848],{},"À première vue, rien ne change par rapport à l'article précédent. Les détails se trouvent dans la description et la fonction d'évaluation.",[10,850,851],{},"La description commence comme celle de n'importe quel outil. Elle explique son rôle et ce que le modèle peut en faire.",[41,853,856],{"className":854,"code":855,"filename":45,"language":325,"meta":47},[323],"Search the MarketHub OpenAPI specification with JavaScript.\n\nThe specification stays inside the server. Your code must be an async arrow function and should return only the small result needed for the next decision. All local $refs are resolved before the code runs.\n",[49,857,855],{"__ignoreMap":47},[10,859,860],{},"C'est ensuite que les choses deviennent intéressantes.",[10,862,863],{},"Nous pouvons fournir des interfaces TypeScript pour offrir au modèle une façade typée sur laquelle écrire son code. Ce contrat compact augmente ses chances de produire un programme fonctionnel dès la première tentative.",[41,865,867],{"className":594,"code":866,"filename":45,"language":597,"meta":47,"style":47},"interface OperationInfo {\n  operationId?: string\n  summary?: string\n  description?: string\n  tags?: string[]\n  parameters?: Array\u003C{\n    name?: string\n    in?: string\n    required?: boolean\n    description?: string\n    schema?: unknown\n  }>\n  requestBody?: unknown\n  responses?: Record\u003Cstring, unknown>\n}\n\ndeclare const spec: {\n  paths: Record\u003Cstring, {\n    get?: OperationInfo\n    post?: OperationInfo\n    put?: OperationInfo\n    patch?: OperationInfo\n    delete?: OperationInfo\n  }>\n}\n",[49,868,869,879,890,899,908,921,934,943,952,962,971,981,986,995,1018,1022,1026,1042,1058,1067,1076,1085,1094,1103,1107],{"__ignoreMap":47},[52,870,871,874,877],{"class":54,"line":55},[52,872,873],{"class":381},"interface",[52,875,876],{"class":446}," OperationInfo",[52,878,391],{"class":62},[52,880,881,884,887],{"class":54,"line":70},[52,882,883],{"class":484},"  operationId",[52,885,886],{"class":381},"?:",[52,888,889],{"class":66}," string\n",[52,891,892,895,897],{"class":54,"line":79},[52,893,894],{"class":484},"  summary",[52,896,886],{"class":381},[52,898,889],{"class":66},[52,900,901,904,906],{"class":54,"line":91},[52,902,903],{"class":484},"  description",[52,905,886],{"class":381},[52,907,889],{"class":66},[52,909,910,913,915,918],{"class":54,"line":102},[52,911,912],{"class":484},"  tags",[52,914,886],{"class":381},[52,916,917],{"class":66}," string",[52,919,920],{"class":62},"[]\n",[52,922,923,926,928,931],{"class":54,"line":110},[52,924,925],{"class":484},"  parameters",[52,927,886],{"class":381},[52,929,930],{"class":446}," Array",[52,932,933],{"class":62},"\u003C{\n",[52,935,936,939,941],{"class":54,"line":118},[52,937,938],{"class":484},"    name",[52,940,886],{"class":381},[52,942,889],{"class":66},[52,944,945,948,950],{"class":54,"line":126},[52,946,947],{"class":484},"    in",[52,949,886],{"class":381},[52,951,889],{"class":66},[52,953,954,957,959],{"class":54,"line":137},[52,955,956],{"class":484},"    required",[52,958,886],{"class":381},[52,960,961],{"class":66}," boolean\n",[52,963,964,967,969],{"class":54,"line":145},[52,965,966],{"class":484},"    description",[52,968,886],{"class":381},[52,970,889],{"class":66},[52,972,973,976,978],{"class":54,"line":153},[52,974,975],{"class":484},"    schema",[52,977,886],{"class":381},[52,979,980],{"class":66}," unknown\n",[52,982,983],{"class":54,"line":164},[52,984,985],{"class":62},"  }>\n",[52,987,988,991,993],{"class":54,"line":172},[52,989,990],{"class":484},"  requestBody",[52,992,886],{"class":381},[52,994,980],{"class":66},[52,996,997,1000,1002,1005,1008,1010,1012,1015],{"class":54,"line":180},[52,998,999],{"class":484},"  responses",[52,1001,886],{"class":381},[52,1003,1004],{"class":446}," Record",[52,1006,1007],{"class":62},"\u003C",[52,1009,665],{"class":66},[52,1011,431],{"class":62},[52,1013,1014],{"class":66},"unknown",[52,1016,1017],{"class":62},">\n",[52,1019,1020],{"class":54,"line":188},[52,1021,575],{"class":62},[52,1023,1024],{"class":54,"line":199},[52,1025,411],{"emptyLinePlaceholder":410},[52,1027,1028,1031,1034,1037,1040],{"class":54,"line":207},[52,1029,1030],{"class":381},"declare",[52,1032,1033],{"class":381}," const",[52,1035,1036],{"class":66}," spec",[52,1038,1039],{"class":381},":",[52,1041,391],{"class":62},[52,1043,1044,1047,1049,1051,1053,1055],{"class":54,"line":218},[52,1045,1046],{"class":484},"  paths",[52,1048,1039],{"class":381},[52,1050,1004],{"class":446},[52,1052,1007],{"class":62},[52,1054,665],{"class":66},[52,1056,1057],{"class":62},", {\n",[52,1059,1060,1062,1064],{"class":54,"line":226},[52,1061,121],{"class":484},[52,1063,886],{"class":381},[52,1065,1066],{"class":446}," OperationInfo\n",[52,1068,1069,1072,1074],{"class":54,"line":234},[52,1070,1071],{"class":484},"    post",[52,1073,886],{"class":381},[52,1075,1066],{"class":446},[52,1077,1078,1081,1083],{"class":54,"line":245},[52,1079,1080],{"class":484},"    put",[52,1082,886],{"class":381},[52,1084,1066],{"class":446},[52,1086,1087,1090,1092],{"class":54,"line":253},[52,1088,1089],{"class":484},"    patch",[52,1091,886],{"class":381},[52,1093,1066],{"class":446},[52,1095,1096,1099,1101],{"class":54,"line":833},[52,1097,1098],{"class":484},"    delete",[52,1100,886],{"class":381},[52,1102,1066],{"class":446},[52,1104,1105],{"class":54,"line":838},[52,1106,985],{"class":62},[52,1108,1109],{"class":54,"line":843},[52,1110,575],{"class":62},[10,1112,1113],{},"La spécification OpenAPI complète reste sur le serveur. Le programme généré peut l'inspecter par l'intermédiaire de cette façade, tandis que le modèle ne reçoit que l'interface compacte et le résultat final de la recherche.",[1115,1116,1118],"callout",{"color":73,"icon":1117},"i-ph-info-duotone",[10,1119,1120],{},"La spécification OpenAPI est simplifiée dans le MCP pour la rendre plus facile à utiliser par l'IA.",[10,1122,1123],{},"Enfin, voici quelques exemples qui montrent au modèle comment utiliser l'outil et quel résultat renvoyer.",[41,1125,1128],{"className":1126,"code":1127,"filename":45,"language":325,"meta":47},[323],"\u002F\u002F Inspect one operation's request body\nasync () => spec.paths['\u002Fproducts']?.post?.requestBody\n\n\u002F\u002F Inspect endpoint parameters\nasync () => spec.paths['\u002Fproducts']?.get?.parameters\n",[49,1129,1127],{"__ignoreMap":47},[10,1131,1132],{},"Le modèle peut désormais rechercher dans la spécification OpenAPI sans recevoir le document complet dans son contexte.",[1134,1135,1136,1137,1136,1146],"figure",{},"\n  ",[1138,1139,1140,1141,1136],"video",{"autoPlay":410,"loop":410,"muted":410,"playsInline":410},"\n    ",[1142,1143],"source",{"src":1144,"type":1145},"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context\u002Fsearch-openapi-specification.mp4","video\u002Fmp4",[1147,1148,1149],"figcaption",{},"Recherche dans la spécification OpenAPI sans renvoyer le document complet.",[10,1151,1152],{},"Mais pourquoi demander au LLM d'écrire du JavaScript plutôt qu'un autre langage ?",[10,1154,1155],{},"Nous choisissons JavaScript parce qu'il est très répandu, familier aux modèles et simple à exécuter dans l'environnement ciblé. L'interface TypeScript ci-dessus sert de documentation au modèle. Elle fournit les types statiques de la façade, mais elle n'est pas exécutée.",[17,1157,1159],{"id":1158},"la-découverte-nest-pas-lexécution","La découverte n'est pas l'exécution",[10,1161,1162],{},"Savoir quels endpoints appeler constitue un bon début, mais cela ne suffit pas. À partir des données recueillies, le LLM pourrait générer le code qui appelle l'endpoint. La boucle serait ainsi complète. Sans connaissance préalable, le LLM pourrait à la fois découvrir l'API et interagir avec elle.",[10,1164,1165,1166,1170,1171,1174],{},"Dans la ",[25,1167,1169],{"href":1168},"\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters","partie 4",", nous ajouterons une capacité d'exécution distincte. Elle permettra au code généré d'appeler une fonction ",[49,1172,1173],{},"api.request()"," ciblée et contrôlée par l'hôte, puis de renvoyer uniquement la partie de la réponse dont le modèle aura besoin.",[1176,1177,1178],"style",{},"html pre.shiki code .sovSZ, html code.shiki .sovSZ{--shiki-light:#22863A;--shiki-default:#22863A;--shiki-dark:#85E89D}html pre.shiki code .sxrX7, html code.shiki .sxrX7{--shiki-light:#24292E;--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sBjJW, html code.shiki .sBjJW{--shiki-light:#005CC5;--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sIIMD, html code.shiki .sIIMD{--shiki-light:#032F62;--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .s8jYJ, html code.shiki .s8jYJ{--shiki-light:#D73A49;--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .snPdu, html code.shiki .snPdu{--shiki-light:#6F42C1;--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sP4rz, html code.shiki .sP4rz{--shiki-light:#E36209;--shiki-default:#E36209;--shiki-dark:#FFAB70}",{"title":47,"searchDepth":70,"depth":70,"links":1180},[1181,1182,1183,1184,1185],{"id":19,"depth":70,"text":20},{"id":301,"depth":70,"text":302},{"id":347,"depth":70,"text":348},{"id":587,"depth":70,"text":588},{"id":1158,"depth":70,"text":1159},"c32e838b-fc65-4cf8-a541-db7017ff7c0e","2026-07-12","Conservez la spécification OpenAPI côté serveur et recherchez dans une façade typée compacte sans renvoyer le document complet.","md",{"branch":1191},"part-3-search",null,{},"\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context","---\ncontentId: c32e838b-fc65-4cf8-a541-db7017ff7c0e\npart: 3\ntitle: Chercher dans OpenAPI sans saturer la fenêtre de contexte\ndescription: Conservez la spécification OpenAPI côté serveur et recherchez dans une façade typée compacte sans renvoyer le document complet.\ngithub:\n  branch: part-3-search\ndate: 2026-07-12\nseriesSlug: building-code-mode-for-apis-with-mcp-and-isolated-workers\n---\n\nDans l'article précédent, nous avons découvert le Code Mode et l'intérêt de laisser le modèle écrire le code d'orchestration au lieu d'appeler directement les outils.\n\nDans cette troisième partie, nous allons voir comment utiliser le Code Mode lorsque la fenêtre de contexte est limitée ou lorsqu'un document, ici une spécification OpenAPI, dépasse la taille de cette fenêtre.\n\n## Le problème de la fenêtre de contexte\n\nLorsque nous développons un service ou une application, nous construisons souvent une API pour permettre à d'autres services d'interagir avec notre système. Les développeurs apprennent traditionnellement à utiliser cette API grâce à des sites de documentation, comme la [référence de l'API Cloudflare](https:\u002F\u002Fdevelopers.cloudflare.com\u002Fapi\u002F).\n\nPour faciliter la création et la maintenance de ces sites, tout en les gardant synchronisés avec l'API réelle, le secteur a créé un format de spécification : [OpenAPI](https:\u002F\u002Fswagger.io\u002Fspecification\u002F).\n\n```yaml [Exemple]\nopenapi: 3.0.0\ninfo:\n  title: Sample API\n  version: 1.0.0\npaths:\n  \u002Fusers:\n    get:\n      summary: Get all users\n      responses:\n        '200':\n          description: A list of users\n          content:\n            application\u002Fjson:\n              schema:\n                type: array\n                items:\n                  type: object\n                  properties:\n                    id:\n                      type: string\n                    name:\n                      type: string\n```\n\nCet exemple présente une spécification OpenAPI simple pour une API qui possède un seul endpoint, `\u002Fusers`, et renvoie une liste d'utilisateurs. La spécification décrit l'endpoint, la méthode HTTP, la réponse attendue et le format des données.\n\nCe format est très utile pour les traitements automatisés et peut générer une documentation pratique pour les humains. Une spécification brute volumineuse reste toutefois difficile à parcourir manuellement et peut dépasser la fenêtre de contexte d'un modèle. Dans ce cas, nous ne pouvons pas simplement transmettre le document complet au modèle et espérer qu'il l'utilise correctement.\n\n- [La spécification OpenAPI de GitHub GHES 3.21](https:\u002F\u002Fgithub.com\u002Fgithub\u002Frest-api-description\u002Fblob\u002Fmain\u002Fdescriptions\u002Fghes-3.21\u002Fghes-3.21.json) pèse 11,1 Mo.\n- [La spécification OpenAPI de Cloudflare](https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fapi-schemas\u002Fblob\u002Fmain\u002Fopenapi.json) pèse 22,7 Mo.\n\nCes fichiers évoluent, leurs tailles exactes changeront donc avec le temps. Le point important est que les descriptions d'API réelles peuvent être bien plus volumineuses que les informations nécessaires à une tâche donnée.\n\nL'instantané Cloudflare utilisé dans cette série contient 23 792 523 caractères. L'approximation courante de quatre caractères par jeton donne environ 6 millions de jetons, même si la tokenisation varie selon le modèle et le contenu. Dans tous les cas, ce volume dépasse largement de nombreuses fenêtres de contexte disponibles.\n\nNous ne pouvons pas transmettre toute la spécification au modèle.\n\n## Les spécifications OpenAPI s'adressent aux humains et aux machines\n\nOpenAPI permet aux humains comme aux logiciels de comprendre une API. Un générateur de documentation peut transformer la spécification en site web, tandis qu'un générateur de client peut la convertir en code. Pour un modèle, renvoyer toute la spécification dans le contexte reste généralement une mauvaise interface. Le modèle a besoin des endpoints et des schémas utiles à sa tâche, pas de toutes les opérations de l'API.\n\nRien ne nous empêche cependant de construire un outil capable de rechercher dans la spécification OpenAPI et de ne renvoyer que les informations pertinentes. Imaginez que vous intégrez une plateforme de vente en ligne et que vous cherchez comment créer un retour.\n\nAu lieu d'utiliser `Ctrl+F` ou `Cmd+F` dans la spécification OpenAPI, pourquoi ne pas appliquer l'algorithme suivant ?\n\n```text [Exemple]\nsearchTerm = \"return\"\nresults = []\n\nfor each URL path and path item in spec.paths:\n    for each HTTP method and operation in the path item:\n        if the entry is not an HTTP operation:\n            continue\n\n        searchableText = combine:\n            - the URL path\n            - the operation ID\n            - the summary\n            - the description\n            - the operation tags\n\n        if searchableText does not contain searchTerm:\n            continue\n\n        endpoint = {\n            method: the HTTP method in uppercase,\n            path: the URL path,\n            operationId: the operation ID,\n            summary: the operation summary,\n            parameters: [\n                for each parameter:\n                    keep its name, location, and required flag\n            ],\n            requestBody: keep only its content types and required flag,\n            responses: [\n                for each response:\n                    keep its status code and description\n            ]\n        }\n\n        add endpoint to results\n\nreturn results\n```\n\nNous n'extrayons ainsi que les informations pertinentes. Mais nous pouvons aller plus loin.\n\nMême avec un tel algorithme, nous devons encore exécuter le code manuellement et rien ne garantit qu'il couvrira tous les cas. Pour créer un retour, nous pourrions par exemple ne conserver que les endpoints qui utilisent la méthode `POST`. Un filtrage par tags serait peut-être plus efficace que de deviner les bons mots à rechercher dans le résumé et la description. Nous pourrions aussi ne conserver que les endpoints qui possèdent un code de réponse `200`. Les possibilités de filtrage varient selon le client, les données nécessaires et la tâche à accomplir. Écrire un algorithme générique devient donc bien trop complexe.\n\nIl faudrait écrire un algorithme personnalisé pour chaque cas d'usage.\n\n## Les LLM connaissent le code et les algorithmes\n\nOu nous pouvons déléguer cette tâche à un LLM.\n\nLes LLM savent notamment générer du code. Ils peuvent transformer une demande précise en petit programme de recherche que les développeurs peuvent relire et exécuter.\n\nAu lieu d'écrire un algorithme générique, ou des milliers pour tenter de couvrir tous les cas, nous pourrions simplement demander au LLM d'écrire celui dont nous avons besoin. Il ne resterait ensuite qu'à l'exécuter. Le LLM recevrait exactement les informations utiles, sans que la fenêtre de contexte devienne un problème.\n\nJ'ai découvert cette idée dans un article de Cloudflare intitulé [Code Mode](https:\u002F\u002Fblog.cloudflare.com\u002Fcode-mode\u002F), et ma première réaction a été « quoi ? ». J'ai dû le lire plus de deux fois pour vraiment comprendre le concept. Prenons un exemple.\n\nImaginez que vous souhaitiez créer un retour sur une plateforme de vente en ligne. Au lieu de fournir toute la spécification OpenAPI au modèle, vous pourriez écrire la méthode suivante :\n\n```js [Exemple]\nasync () => {\n  const results = []\n\n  for (const [path, methods] of Object.entries(spec.paths)) {\n    const operation = methods.post\n\n    if (operation?.tags?.some(tag => tag.toLowerCase() === 'returns')) {\n      results.push({\n        method: 'POST',\n        path,\n        summary: operation.summary,\n        requestBody: operation.requestBody\n      })\n    }\n  }\n\n  return results\n}\n```\n\nCe code permet de rechercher rapidement dans la spécification OpenAPI et de ne renvoyer que les informations pertinentes.\n\nMais qui veut écrire ce code ? Personne.\n\nHeureusement, les LLM peuvent le générer à notre place. Donnez-leur accès à la spécification OpenAPI et quelques exemples, et ils pourront parcourir toute la spécification pour trouver uniquement ce qui compte.\n\n## Outil, description et langage\n\nDans notre MCP, l'outil de recherche ressemblerait à ceci :\n\n```typescript [search.ts]\nserver.registerTool(\n  'search',\n  {\n    title: 'Search OpenAPI Specification',\n    description: '...',\n    inputSchema: z.object({\n      code: z\n        .string()\n        .max(MAX_CODE_LENGTH)\n        .describe('An async arrow function that searches the OpenAPI spec')\n    }),\n  },\n  async ({ code }) => {\n    try {\n      const result = await evaluateSearchCode(code)\n      return { content: [{ type: 'text', text: formatSearchResult(result) }] }\n    }\n    catch (error) {\n      return {\n        content: [{ type: 'text', text: `Search failed: ${errorMessage(error)}` }],\n        isError: true\n      }\n    }\n  }\n)\n```\n\nÀ première vue, rien ne change par rapport à l'article précédent. Les détails se trouvent dans la description et la fonction d'évaluation.\n\nLa description commence comme celle de n'importe quel outil. Elle explique son rôle et ce que le modèle peut en faire.\n\n```text [Exemple]\nSearch the MarketHub OpenAPI specification with JavaScript.\n\nThe specification stays inside the server. Your code must be an async arrow function and should return only the small result needed for the next decision. All local $refs are resolved before the code runs.\n```\n\nC'est ensuite que les choses deviennent intéressantes.\n\nNous pouvons fournir des interfaces TypeScript pour offrir au modèle une façade typée sur laquelle écrire son code. Ce contrat compact augmente ses chances de produire un programme fonctionnel dès la première tentative.\n\n```typescript [Exemple]\ninterface OperationInfo {\n  operationId?: string\n  summary?: string\n  description?: string\n  tags?: string[]\n  parameters?: Array\u003C{\n    name?: string\n    in?: string\n    required?: boolean\n    description?: string\n    schema?: unknown\n  }>\n  requestBody?: unknown\n  responses?: Record\u003Cstring, unknown>\n}\n\ndeclare const spec: {\n  paths: Record\u003Cstring, {\n    get?: OperationInfo\n    post?: OperationInfo\n    put?: OperationInfo\n    patch?: OperationInfo\n    delete?: OperationInfo\n  }>\n}\n```\n\nLa spécification OpenAPI complète reste sur le serveur. Le programme généré peut l'inspecter par l'intermédiaire de cette façade, tandis que le modèle ne reçoit que l'interface compacte et le résultat final de la recherche.\n\n::callout{icon=\"i-ph-info-duotone\" color=\"info\"}\nLa spécification OpenAPI est simplifiée dans le MCP pour la rendre plus facile à utiliser par l'IA.\n::\n\nEnfin, voici quelques exemples qui montrent au modèle comment utiliser l'outil et quel résultat renvoyer.\n\n```text [Exemple]\n\u002F\u002F Inspect one operation's request body\nasync () => spec.paths['\u002Fproducts']?.post?.requestBody\n\n\u002F\u002F Inspect endpoint parameters\nasync () => spec.paths['\u002Fproducts']?.get?.parameters\n```\n\nLe modèle peut désormais rechercher dans la spécification OpenAPI sans recevoir le document complet dans son contexte.\n\n\u003Cfigure>\n  \u003Cvideo autoplay loop muted playsinline>\n    \u003Csource src=\"https:\u002F\u002Fimages.soubiran.dev\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context\u002Fsearch-openapi-specification.mp4\" type=\"video\u002Fmp4\">\n  \u003C\u002Fvideo>\n  \u003Cfigcaption>Recherche dans la spécification OpenAPI sans renvoyer le document complet.\u003C\u002Ffigcaption>\n\u003C\u002Ffigure>\n\nMais pourquoi demander au LLM d'écrire du JavaScript plutôt qu'un autre langage ?\n\nNous choisissons JavaScript parce qu'il est très répandu, familier aux modèles et simple à exécuter dans l'environnement ciblé. L'interface TypeScript ci-dessus sert de documentation au modèle. Elle fournit les types statiques de la façade, mais elle n'est pas exécutée.\n\n## La découverte n'est pas l'exécution\n\nSavoir quels endpoints appeler constitue un bon début, mais cela ne suffit pas. À partir des données recueillies, le LLM pourrait générer le code qui appelle l'endpoint. La boucle serait ainsi complète. Sans connaissance préalable, le LLM pourrait à la fois découvrir l'API et interagir avec elle.\n\nDans la [partie 4](\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fcalling-apis-with-code-mode-and-returning-only-what-matters), nous ajouterons une capacité d'exécution distincte. Elle permettra au code généré d'appeler une fonction `api.request()` ciblée et contrôlée par l'hôte, puis de renvoyer uniquement la partie de la réponse dont le modèle aura besoin.\n",{"title":5,"description":1188},"building-code-mode-for-apis-with-mcp-and-isolated-workers",{"loc":1194},"fr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fsearching-openapi-specification-without-filling-the-context","yNUsT1CisYFN2LLlhMFKZusStnGGLEL-4hYGROjIXlw",{"overview":1202,"chapters":1366},{"id":1203,"title":1204,"body":1205,"contentId":1348,"date":1187,"description":1349,"extension":1189,"github":1350,"meetTheInstructor":1351,"meta":1352,"navigation":410,"part":1192,"path":1353,"rawbody":1354,"robots":1192,"schemaOrg":1192,"seo":1355,"seriesSlug":1197,"sitemap":1356,"stem":1357,"subtitle":1358,"topics":1359,"__hash__":1365},"series\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers.md","Construire le Code Mode pour les API avec MCP et Workers",{"type":7,"value":1206,"toc":1345},[1207,1210,1218,1225,1237,1253,1256,1259,1262,1319,1327,1335,1339],[10,1208,1209],{},"Bonjour et bienvenue ! 👋",[10,1211,1212,1213,1217],{},"Cette série prolonge de manière concrète l'article ",[25,1214,1216],{"href":1215},"\u002Ffr\u002Fposts\u002Fcode-mode-two-tools-and-an-mcp-can-save-your-llm-context","Code Mode, deux outils et un MCP peuvent préserver le contexte de votre LLM",". Celui-ci présentait l'idée suivante : au lieu de demander à un modèle d'orchestrer chaque appel d'outil dépendant, laissons-le écrire cette orchestration sous forme de code et renvoyer uniquement le résultat nécessaire à sa prochaine décision.",[10,1219,1220,1221,1224],{},"Ici, nous allons construire cette approche étape par étape. Nous commencerons par une petite transformation de fichier en local, puis nous passerons à une API décrite avec OpenAPI avant de remplacer l'évaluateur local de confiance basé sur le constructeur ",[49,1222,1223],{},"Function"," par un environnement d'exécution isolé. Nous obtiendrons un serveur MCP exécutable en local, capable de rechercher dans la spécification d'une API et d'exécuter une requête ciblée vers cette API.",[10,1226,1227,1228,1232,1233,31],{},"Les principes fondamentaux de MCP sortent du cadre de cette série. Si vous avez besoin d'une introduction au protocole ou à la relation entre un Agent IA et un serveur MCP, commencez par ",[25,1229,1231],{"href":1230},"\u002Ffr\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web","Agents IA et serveur MCP au service du web agentique",", en particulier ",[25,1234,1236],{"href":1235},"\u002Ffr\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web\u002Fmcp-to-provide-additional-capabilities-to-the-ai-agent","son article sur le serveur MCP",[10,1238,1239,1240,1244,1245,1248,1249,1252],{},"Tout au long de la série, le ",[1241,1242,1243],"strong",{},"modèle"," génère des appels d'outils ou du code, le ",[1241,1246,1247],{},"client MCP"," ou Agent exécute la boucle du modèle et le ",[1241,1250,1251],{},"serveur MCP"," fournit les capacités. Il faut bien distinguer ces rôles : l'hôte, et non le code généré, définit les capacités disponibles.",[10,1254,1255],{},"L'idée centrale est simple. Avec des outils MCP directs, le modèle doit appeler un outil, recevoir l'intégralité du résultat intermédiaire, puis utiliser ce résultat pour décider comment appeler l'outil suivant. Avec le Code Mode, le modèle écrit l'orchestration sous forme de code. Ce code accède aux capacités dont il a besoin dans l'environnement d'exécution, et le modèle reçoit uniquement le résultat final souhaité pour poursuivre son travail.",[10,1257,1258],{},"Le Code Mode n'est pas toujours le bon choix. Les outils MCP directs restent plus simples pour les actions courtes et évidentes. L'environnement d'exécution supplémentaire devient utile lorsqu'une tâche comporte des appels dépendants, nécessite un traitement local des données ou doit parcourir une API vaste et évolutive. C'est par exemple le cas d'une spécification OpenAPI qui peut dépasser la fenêtre de contexte du modèle.",[10,1260,1261],{},"Au fil de cette série, nous allons :",[1263,1264,1265,1275,1290,1300,1313],"ol",{},[274,1266,1267,1270,1271,1274],{},[1241,1268,1269],{},"Au-delà d'un appel d'outil à la fois : découvrir le Code Mode"," : construire deux outils ",[49,1272,1273],{},"Drive"," directs autour d'un fichier Markdown de test et observer comment l'intégralité de son contenu traverse le contexte du modèle avant l'appel d'outil suivant.",[274,1276,1277,1280,1281,1283,1284,1286,1287,1289],{},[1241,1278,1279],{},"Laisser le modèle orchestrer les outils dans un environnement local"," : remplacer les deux outils directs par un outil ",[49,1282,49],{}," générique, exposer une façade ",[49,1285,1273],{}," typée et introduire l'interface de l'exécuteur que les parties suivantes remplaceront. L'évaluateur local basé sur le constructeur ",[49,1288,1223],{}," est volontairement un raccourci réservé au développement de confiance, et non un bac à sable de production.",[274,1291,1292,1295,1296,1299],{},[1241,1293,1294],{},"Rechercher dans une spécification OpenAPI sans remplir le contexte"," : conserver le document OpenAPI dans le serveur, résoudre ses références ",[49,1297,1298],{},"$ref"," locales et laisser le code généré effectuer ses recherches dans une façade de types compacte au lieu de renvoyer toute la spécification au modèle.",[274,1301,1302,1305,1306,1309,1310,1312],{},[1241,1303,1304],{},"Appeler des API avec le Code Mode et ne renvoyer que l'essentiel"," : ajouter un outil ",[49,1307,1308],{},"execute"," distinct avec une fonction ",[49,1311,1173],{}," contrôlée par l'hôte. Nous validerons les options de la requête, appellerons l'API MarketHub locale utilisée pour les tests et renverrons une projection ciblée plutôt que la réponse complète de l'API.",[274,1314,1315,1318],{},[1241,1316,1317],{},"Remplacer l'évaluateur par des Workers Cloudflare isolés"," : remplacer uniquement l'exécuteur par de nouveaux Workers dynamiques. La recherche s'exécutera sans accès sortant, tandis que les appels passeront par une passerelle avec une liste d'autorisations. Les identifiants resteront hors du code généré. Nous aborderons également les limites des résultats, les limites de ressources et les délais imposés par l'hôte.",[10,1320,1321,1322,1326],{},"Le dépôt associé, ",[1323,1324],"git-hub-link",{"repo":1325},"barbapapazes\u002Fcode-mode",", est un manuel exécutable pour cette série. Chaque article dispose d'une branche qui représente un état complet, d'une petite évaluation et d'un diff ciblé par rapport à l'étape précédente. Je vous recommande d'extraire une branche et d'étudier l'implémentation pour mieux comprendre les concepts, car les articles ne couvriront pas chaque détail.",[1115,1328,1329],{"color":73,"icon":1117},[10,1330,1331,1332,1334],{},"Cette série suppose que vous connaissez TypeScript, les promesses JavaScript, les API HTTP et les concepts de base de MCP. Les étapes locales ne contiennent aucun identifiant. Les parties 2 à 4 utilisent un évaluateur local de confiance basé sur le constructeur ",[49,1333,1223],{}," pour le développement. La partie 5 fournit une base de déploiement Cloudflare et une évaluation structurelle de la sécurité.",[17,1336,1338],{"id":1337},"chapitres","Chapitres",[1340,1341],"series-chapters-list",{"className":1342},[1343,1344],"mx-auto","max-w-5xl",{"title":47,"searchDepth":70,"depth":70,"links":1346},[1347],{"id":1337,"depth":70,"text":1338},"4fc50be1-a524-474e-8426-392581f8b0e8","Construisez un serveur MCP pour une API décrite par OpenAPI, puis remplacez l'évaluateur local par des Workers Cloudflare isolés.",{"name":365,"repository":1325},"J'ai créé cette série pour transformer l'idée du Code Mode en une implémentation concrète. Nous commencerons avec deux outils MCP ordinaires, puis nous confierons l'orchestration au code généré avant de remplacer un évaluateur local de confiance basé sur le constructeur Function par des Workers Cloudflare dynamiques et isolés.",{},"\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers","---\ncontentId: 4fc50be1-a524-474e-8426-392581f8b0e8\ntitle: Construire le Code Mode pour les API avec MCP et Workers\nsubtitle: Créez un serveur MCP économe en contexte pour les API décrites avec OpenAPI\ndescription: Construisez un serveur MCP pour une API décrite par OpenAPI, puis remplacez l'évaluateur local par des Workers Cloudflare isolés.\ndate: 2026-07-12\ntopics:\n  - ai\n  - ai-agents\n  - mcp\n  - code-mode\n  - openapi\n  - cloudflare\n  - typescript\ngithub:\n  name: Code Mode\n  repository: barbapapazes\u002Fcode-mode\nmeetTheInstructor: J'ai créé cette série pour transformer l'idée du Code Mode en une implémentation concrète. Nous commencerons avec deux outils MCP ordinaires, puis nous confierons l'orchestration au code généré avant de remplacer un évaluateur local de confiance basé sur le constructeur Function par des Workers Cloudflare dynamiques et isolés.\nseriesSlug: building-code-mode-for-apis-with-mcp-and-isolated-workers\n---\n\nBonjour et bienvenue ! 👋\n\nCette série prolonge de manière concrète l'article [Code Mode, deux outils et un MCP peuvent préserver le contexte de votre LLM](\u002Ffr\u002Fposts\u002Fcode-mode-two-tools-and-an-mcp-can-save-your-llm-context). Celui-ci présentait l'idée suivante : au lieu de demander à un modèle d'orchestrer chaque appel d'outil dépendant, laissons-le écrire cette orchestration sous forme de code et renvoyer uniquement le résultat nécessaire à sa prochaine décision.\n\nIci, nous allons construire cette approche étape par étape. Nous commencerons par une petite transformation de fichier en local, puis nous passerons à une API décrite avec OpenAPI avant de remplacer l'évaluateur local de confiance basé sur le constructeur `Function` par un environnement d'exécution isolé. Nous obtiendrons un serveur MCP exécutable en local, capable de rechercher dans la spécification d'une API et d'exécuter une requête ciblée vers cette API.\n\nLes principes fondamentaux de MCP sortent du cadre de cette série. Si vous avez besoin d'une introduction au protocole ou à la relation entre un Agent IA et un serveur MCP, commencez par [Agents IA et serveur MCP au service du web agentique](\u002Ffr\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web), en particulier [son article sur le serveur MCP](\u002Ffr\u002Fseries\u002Fai-agents-and-mcp-server-teaming-up-for-the-agentic-web\u002Fmcp-to-provide-additional-capabilities-to-the-ai-agent).\n\nTout au long de la série, le **modèle** génère des appels d'outils ou du code, le **client MCP** ou Agent exécute la boucle du modèle et le **serveur MCP** fournit les capacités. Il faut bien distinguer ces rôles : l'hôte, et non le code généré, définit les capacités disponibles.\n\nL'idée centrale est simple. Avec des outils MCP directs, le modèle doit appeler un outil, recevoir l'intégralité du résultat intermédiaire, puis utiliser ce résultat pour décider comment appeler l'outil suivant. Avec le Code Mode, le modèle écrit l'orchestration sous forme de code. Ce code accède aux capacités dont il a besoin dans l'environnement d'exécution, et le modèle reçoit uniquement le résultat final souhaité pour poursuivre son travail.\n\nLe Code Mode n'est pas toujours le bon choix. Les outils MCP directs restent plus simples pour les actions courtes et évidentes. L'environnement d'exécution supplémentaire devient utile lorsqu'une tâche comporte des appels dépendants, nécessite un traitement local des données ou doit parcourir une API vaste et évolutive. C'est par exemple le cas d'une spécification OpenAPI qui peut dépasser la fenêtre de contexte du modèle.\n\nAu fil de cette série, nous allons :\n\n1. **Au-delà d'un appel d'outil à la fois : découvrir le Code Mode** : construire deux outils `Drive` directs autour d'un fichier Markdown de test et observer comment l'intégralité de son contenu traverse le contexte du modèle avant l'appel d'outil suivant.\n2. **Laisser le modèle orchestrer les outils dans un environnement local** : remplacer les deux outils directs par un outil `code` générique, exposer une façade `Drive` typée et introduire l'interface de l'exécuteur que les parties suivantes remplaceront. L'évaluateur local basé sur le constructeur `Function` est volontairement un raccourci réservé au développement de confiance, et non un bac à sable de production.\n3. **Rechercher dans une spécification OpenAPI sans remplir le contexte** : conserver le document OpenAPI dans le serveur, résoudre ses références `$ref` locales et laisser le code généré effectuer ses recherches dans une façade de types compacte au lieu de renvoyer toute la spécification au modèle.\n4. **Appeler des API avec le Code Mode et ne renvoyer que l'essentiel** : ajouter un outil `execute` distinct avec une fonction `api.request()` contrôlée par l'hôte. Nous validerons les options de la requête, appellerons l'API MarketHub locale utilisée pour les tests et renverrons une projection ciblée plutôt que la réponse complète de l'API.\n5. **Remplacer l'évaluateur par des Workers Cloudflare isolés** : remplacer uniquement l'exécuteur par de nouveaux Workers dynamiques. La recherche s'exécutera sans accès sortant, tandis que les appels passeront par une passerelle avec une liste d'autorisations. Les identifiants resteront hors du code généré. Nous aborderons également les limites des résultats, les limites de ressources et les délais imposés par l'hôte.\n\nLe dépôt associé, \u003CGitHubLink repo=\"barbapapazes\u002Fcode-mode\" \u002F>, est un manuel exécutable pour cette série. Chaque article dispose d'une branche qui représente un état complet, d'une petite évaluation et d'un diff ciblé par rapport à l'étape précédente. Je vous recommande d'extraire une branche et d'étudier l'implémentation pour mieux comprendre les concepts, car les articles ne couvriront pas chaque détail.\n\n::callout{icon=\"i-ph-info-duotone\" color=\"info\"}\nCette série suppose que vous connaissez TypeScript, les promesses JavaScript, les API HTTP et les concepts de base de MCP. Les étapes locales ne contiennent aucun identifiant. Les parties 2 à 4 utilisent un évaluateur local de confiance basé sur le constructeur `Function` pour le développement. La partie 5 fournit une base de déploiement Cloudflare et une évaluation structurelle de la sécurité.\n::\n\n## Chapitres\n\n::series-chapters-list\n---\nclass: mx-auto max-w-5xl\n---\n::\n",{"title":1204,"description":1349},{"loc":1353},"fr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers","Créez un serveur MCP économe en contexte pour les API décrites avec OpenAPI",[1360,1361,1362,1363,59,1364,597],"ai","ai-agents","mcp","code-mode","cloudflare","HqoFmkgNETmMSWXeXg8BeVY4Vjz1w13UtWu2_6vvVaE",[1367,1374,1381,1383,1389],{"contentId":1368,"title":1369,"description":1370,"path":1371,"part":55,"github":1372,"topics":1192},"02726224-2677-4d4b-9390-cf6543caba80","Au-delà d'un appel d'outil : découvrir le Code Mode","Découvrez pourquoi les appels d'outils MCP dépendants remplissent le contexte du modèle et comment le Code Mode déplace leur orchestration dans le code.","\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Fbeyond-one-tool-call-at-a-time-introducing-code-mode",{"branch":1373},"part-1-direct-tools",{"contentId":1375,"title":1376,"description":1377,"path":1378,"part":70,"github":1379,"topics":1192},"2eaa3055-6247-4237-aad6-cde698eedb82","Laisser le modèle orchestrer les outils avec du code local","Créez un environnement Code Mode local minimal et fiable avec une façade Drive typée, ainsi qu'un exécuteur prêt à être isolé.","\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Flet-the-model-orchestrate-tools-with-a-local-code-runtime",{"branch":1380},"part-2-generic-code-mode",{"contentId":1186,"title":5,"description":1188,"path":1194,"part":79,"github":1382,"topics":1192},{"branch":1191},{"contentId":1384,"title":1385,"description":1386,"path":1168,"part":91,"github":1387,"topics":1192},"5097481f-e94c-409c-865b-78f9bbf83a68","Appeler des API avec le Code Mode et garder l'essentiel","Utilisez une fonction de requête contrôlée par l'hôte pour valider et exécuter un appel API ciblé, puis ne renvoyer que le résultat utile.",{"branch":1388},"part-4-local-execute",{"contentId":1390,"title":1317,"description":1391,"path":1392,"part":102,"github":1393,"topics":1192},"334230f9-e74b-4174-b2f1-05bf1ec0d1fd","Remplacez l'évaluateur local basé sur Function par des Workers Cloudflare isolés, avec des sorties bornées et un accès réseau contrôlé.","\u002Ffr\u002Fseries\u002Fbuilding-code-mode-for-apis-with-mcp-and-isolated-workers\u002Freplacing-local-eval-with-isolated-cloudflare-workers",{"branch":1394},"part-5-dynamic-workers",1795016702268]