Tvoj prvi vtičnik
Na tej strani
Lekcija ponovno napisana 3. novembra 2026 na podlagi strani Quickstart, MCP server and UI quickstart in Connect and test your plugin v dokumentaciji OpenAI Plugins. Prejšnji primer „vremenska aplikacija v 30 minutah” se je zanašal na neobstoječi SDK. 3. novembra 2026 smo preverili različice paketov npm:
@modelcontextprotocol/ext-apps2.x temelji na MCP SDK v2, medtem ko primeri OpenAI uporabljajo v1. Viri: Quickstart · MCP server and UI quickstart · Connect and test.
Dva koraka
Najprej boš povezal obstoječi strežnik MCP, da boš videl celoten potek dela v ChatGPT, ne da bi napisal vrstico kode. Nato boš napisal svoj strežnik, ga preizkusil lokalno in ga povezal na enak način.
1. korak: Osebni vtičnik v petih minutah
OpenAI ponuja javni, neavtenticirani primer strežnika MCP, ki izpostavlja eno orodje samo za branje: roll_dice.
- Odpri ChatGPT Plugins, klikni gumb + in izberi Add custom MCP server.
- Vnesi ime in nastavi Server URL na
https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Izberi No authentication. - Preberi opozorilo o tveganju, izberi I understand and want to continue in klikni Create as a plugin.
- Vtičnik se prikaže na tvojem seznamu osebnih vtičnikov: odpri ga in namesti z gumbom +.
- Vrni se na domači zaslon ChatGPT, preklopi z zavihka Chat na Work, začni nov pogovor, vtipkaj
@in izberi svoj vtičnik. - Prosi ga, naj vrže dvajsetstrano kocko: klicati mora
roll_dicenatanko enkrat z nastavitvijosidesna 20 in vrniti vrednost med 1 in 20.
Ne ustavi se pri srečnem scenariju. Preizkusi različne velikosti kock, neveljavne vrednosti in zahteve, ki ne bi smele sprožiti nobenega orodja. Ta refleks poganja preostanek tečaja: ko model izbere napačno orodje ali spremeni svoje argumente, moraš izpopolniti opis in shemo orodja. Upoštevaj tudi, da dodajanje strežnikov MCP po meri urejajo pravilniki tvojega računa ali delovnega prostora: v organizaciji je ta možnost lahko omejena.
2. korak: Tvoj lastni strežnik
Namesti uradne SDK-je
Uradni SDK-ji za protokol obstajajo za TypeScript (@modelcontextprotocol/sdk) in Python (mcp). Ta tečaj sledi primerom OpenAI, napisanim v TypeScriptu z uporabo SDK v1. Pripni svoje različice: od septembra 2026 @modelcontextprotocol/ext-apps 2.x – vmesniški paket, ki ga boš dodal v 6. lekciji – temelji na novih paketih SDK v2 (@modelcontextprotocol/server…), ki niso združljivi z uvozi 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 doda "type": "module" v package.json, kar je potrebno za stavke import strežnika.
Napiši strežnik
Ta strežnik se prilega v eno samo datoteko, server.js. Beleške hrani v pomnilniku in izpostavlja dve orodji: eno za branje in eno za pisanje, ločeni tako, kot je priporočeno v 3. lekciji.
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 = []; // primer podatkov v pomnilniku: zamenjaj s svojim shrambo
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;
}
// Brezstanjski način: nov strežnik in transport za vsako zahtevo
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`));
Pomembne so tri podrobnosti. Vsako orodje deklarira naslov, opis namena, sheme in točne anotacije: to je njegov „profil” za model. Vsak rezultat združuje structuredContent, ki ga model lahko ponovno uporabi, in content, kratko besedilno sporočilo. Končno, vsak naslov, ki ni /mcp, vrne 404: primer OpenAI to počne za poti odkrivanja OAuth, ki jih še ne uporabljaš, s čimer prepreči, da bi ChatGPT med tvojimi neavtenticiranimi testi prikazoval napake 502. Isti primer doda odgovor za predhodno zahtevo CORS (OPTIONS) in GET / za sonde zdravja; vključi jih, če jih tvoje gostovanje pričakuje.
Lokalno testiranje z MCP Inspector
node server.js
npx @modelcontextprotocol/inspector@latest
V Inspectorju izberi Streamable HTTP, vnesi http://localhost:8787/mcp in se poveži. Preveri, ali je inicializacija uspešna, ali se obe orodji prikažeta s svojimi shemami in anotacijami, nato ju pokliči z veljavnimi in neveljavnimi vnosi – prazno besedilno niz mora shema zavrniti.
Izpostavi strežnik in ga poveži
ChatGPT mora doseči tvoj strežnik prek interneta. Med razvojem je dovolj tunel – dokumentacija navaja ngrok:
ngrok http 8787
Dobiš javni naslov HTTPS. Poveži ga kot v 1. koraku, vključno s potjo /mcp (na primer https://<subdomain>.ngrok.app/mcp), namesti nastali vtičnik in ga nato prikliči z @: „Shrani beležko: pokliči dobavitelja v ponedeljek.” ChatGPT prikaže podatke, izmenjane z orodjem, kar ti omogoča preverjanje vhodov in izhodov.
Razvojni tunel deluje le za poskuse: objava zahteva stabilno, javno končno točko HTTPS (5. lekcija).
Ponovno naloži po vsaki spremembi
ChatGPT predpomni metapodatke tvojega strežnika. Po vsaki spremembi imena, opisa, sheme, anotacije, avtentikacije ali vira vmesnika: znova uvedi ali ponovno zaženi strežnik, odpri povezavo na chatgpt.com/plugins, izberi Refresh, preveri, ali so se oglaševani metapodatki spremenili, nato odpri nov pogovor za ponovni zagon testov. Preskok tega koraka pomeni testiranje stare različice, ne da bi se tega zavedal.
Ključne ugotovitve
- Ustvari osebni vtičnik prek Add custom MCP server, nato ga prikliči z
@v ChatGPT - Uradni SDK-ji:
@modelcontextprotocol/sdk(TypeScript) inmcp(Python); pripni v1 zext-apps1.x, da slediš primerom OpenAI - Minimalni strežnik:
McpServer,registerTool, transport streamable HTTP na/mcp - Za lokalno testiranje uporabi MCP Inspector, za poskuse v ChatGPT tunel
- Po vsaki spremembi metapodatkov: Refresh, nato začni nov pogovor