Primul dumneavoastră plugin
Pe această pagină
Lecție rescrisă la 3 noiembrie 2026 pe baza paginilor Quickstart, MCP server and UI quickstart și Connect and test your plugin din documentația OpenAI Plugins. Exemplul anterior „aplicație meteo în 30 de minute“ se baza pe un SDK inexistent. Am verificat versiunile pachetelor npm la 3 noiembrie 2026:
@modelcontextprotocol/ext-apps2.x se bazează pe MCP SDK v2, în timp ce exemplele OpenAI utilizează v1. Surse: Quickstart · MCP server and UI quickstart · Connect and test.
Doi pași
Mai întâi, veți conecta un server MCP existent pentru a observa fluxul complet de lucru ChatGPT fără a scrie nicio linie de cod. Apoi, veți scrie propriul server, îl veți testa local și îl veți conecta în același mod.
Pasul 1: Un plugin personal în cinci minute
OpenAI pune la dispoziție un server MCP exemplu, public și neautentificat, care expune un singur instrument read-only: roll_dice.
- Accesați ChatGPT Plugins, selectați butonul +, apoi alegeți Add custom MCP server.
- Introduceți un nume și setați Server URL la
https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Selectați No authentication. - Citiți avertismentul privind riscurile, selectați I understand and want to continue, apoi faceți clic pe Create as a plugin.
- Plugin-ul apare în lista dumneavoastră de plugin-uri personale: deschideți-l și instalați-l folosind butonul +.
- Reveniți la ecranul principal ChatGPT, comutați de la fila Chat la Work, începeți o conversație nouă, tastați
@și selectați plugin-ul dumneavoastră. - Cereți-i să arunce un zar cu douăzeci de fețe: acesta ar trebui să apeleze
roll_diceexact o dată cusidessetat la 20 și să returneze o valoare între 1 și 20.
Nu vă opriți la scenariul ideal. Încercați dimensiuni diferite de zaruri, valori invalide și cereri care nu ar trebui să declanșeze niciun instrument. Acest reflex stă la baza restului cursului: atunci când modelul selectează instrumentul greșit sau își variază argumentele, trebuie să rafinați descrierea și schema instrumentului. De asemenea, rețineți că politicile contului sau ale spațiului de lucru guvernează adăugarea serverelor MCP personalizate: într-o organizație, această opțiune poate fi restricționată.
Pasul 2: Propriul dumneavoastră server
Instalarea SDK-urilor oficiale
Există SDK-uri oficiale de protocol pentru TypeScript (@modelcontextprotocol/sdk) și Python (mcp). Acest curs urmează exemplele OpenAI, scrise în TypeScript folosind SDK v1. Fixați versiunile: începând cu septembrie 2026, @modelcontextprotocol/ext-apps 2.x—pachetul de interfață pe care îl veți adăuga în Lecția 6—se bazează pe noile pachete SDK v2 (@modelcontextprotocol/server…), care sunt incompatibile cu importurile v1.
mkdir notes-plugin && cd notes-plugin
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk@^1.29 @modelcontextprotocol/ext-apps@^1.7 zod
npm pkg set type=module adaugă "type": "module" în package.json, necesar pentru instrucțiunile import ale serverului.
Scrierea serverului
Acest server încap într-un singur fișier, server.js. Acesta păstrează notele în memorie și expune două instrumente: unul pentru citire și unul pentru scriere, separate conform recomandărilor din Lecția 3.
import { createServer } from "node:http";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";
const notes = []; // exemplu de date în memorie: înlocuiți cu propria stocare
const schemaNotes = {
notes: z.array(z.object({ id: z.string(), text: z.string() })),
};
function creerServeur() {
const server = new McpServer({ name: "notes-demo", version: "0.1.0" });
server.registerTool(
"list_notes",
{
title: "List notes",
description: "Use when the user wants to review notes saved with this plugin.",
inputSchema: {},
outputSchema: schemaNotes,
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
},
async () => ({
structuredContent: { notes },
content: [{ type: "text", text: `${notes.length} note(s) saved.` }],
})
);
server.registerTool(
"add_note",
{
title: "Add a note",
description: "Use when the user asks to save a short note.",
inputSchema: { text: z.string().min(1).max(500) },
outputSchema: schemaNotes,
annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
},
async ({ text }) => {
notes.push({ id: `note-${notes.length + 1}`, text });
return {
structuredContent: { notes },
content: [{ type: "text", text: "Note saved." }],
};
}
);
return server;
}
const PORT = Number(process.env.PORT ?? 8787);
createServer(async (req, res) => {
const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
if (url.pathname !== "/mcp") {
res.writeHead(404).end("Not Found");
return;
}
// Mod fără stare: server și transport noi per cerere
const server = creerServeur();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true,
});
res.on("close", () => {
transport.close();
server.close();
});
try {
await server.connect(transport);
await transport.handleRequest(req, res);
} catch (error) {
console.error("MCP Error:", error);
if (!res.headersSent) res.writeHead(500).end("Internal server error");
}
}).listen(PORT, () => console.log(`MCP server ready on http://localhost:${PORT}/mcp`));
Trei detalii contează. Fiecare instrument declară un titlu, o descriere a intenției, scheme și adnotări exacte: acesta este „profilul“ său pentru model. Fiecare rezultat combină structuredContent, reutilizabil de către model, și content, un scurt mesaj text. În final, orice altă adresă decât /mcp returnează un 404: exemplul OpenAI face acest lucru pentru rutele de descoperire OAuth pe care nu le utilizați încă, prevenind afișarea erorilor 502 de către ChatGPT în timpul testelor dumneavoastră neautentificate. Același exemplu adaugă un răspuns pentru cererea CORS preliminară (OPTIONS) și un GET / pentru sondele de sănătate; includeți-le dacă gazduirea dumneavoastră le așteaptă.
Testare locală cu MCP Inspector
node server.js
npx @modelcontextprotocol/inspector@latest
În Inspector, alegeți Streamable HTTP, introduceți http://localhost:8787/mcp și conectați-vă. Verificați dacă inițializarea reușește, dacă ambele instrumente apar cu schemele și adnotările lor, apoi apelați-le cu intrări valide și invalide—un șir text gol trebuie respins de schemă.
Expunerea serverului și conectarea acestuia
ChatGPT trebuie să poată accesa serverul dumneavoastră de pe internet. În timpul dezvoltării, un tunel este suficient—documentația citează ngrok:
ngrok http 8787
Obțineți o adresă HTTPS publică. Conectați-o ca la Pasul 1, incluzând calea /mcp (de exemplu https://<subdomain>.ngrok.app/mcp), instalați plugin-ul rezultat, apoi invocați-l cu @: „Salvează o notă: sună furnizorul luni.“ ChatGPT afișează datele schimbate cu instrumentul, permițându-vă să verificați intrările și ieșirile.
Un tunel de dezvoltare funcționează doar pentru încercări: publicarea necesită un punct final HTTPS public și stabil (Lecția 5).
Reîncărcare după fiecare modificare
ChatGPT stochează în cache metadatele serverului dumneavoastră. După orice modificare a numelui, descrierii, schemei, adnotării, autentificării sau resursei de interfață: redistribuiți sau reporniți serverul, deschideți conexiunea la chatgpt.com/plugins, selectați Refresh, verificați dacă metadatele publicitate s-au schimbat, apoi deschideți o conversație nouă pentru a re-rula testele. Omiterea acestui pas înseamnă testarea versiunii vechi fără a vă da seama.
Puncte cheie
- Creați un plugin personal prin Add custom MCP server, apoi invocați-l cu
@în ChatGPT - SDK-uri oficiale:
@modelcontextprotocol/sdk(TypeScript) șimcp(Python); fixați v1 cuext-apps1.x pentru a urma exemplele OpenAI - Server minim:
McpServer,registerTool, transport streamable HTTP pe/mcp - Utilizați MCP Inspector pentru testare locală, un tunel pentru încercările ChatGPT
- După orice modificare de metadate: Refresh, apoi începeți o conversație nouă