Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Tvoj prvi vtičnik

Lekcija 4 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Dva koraka
  2. 1. korak: Osebni vtičnik v petih minutah
  3. 2. korak: Tvoj lastni strežnik
  4. Ponovno naloži po vsaki spremembi
  5. Ključne ugotovitve

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-apps 2.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.

  1. Odpri ChatGPT Plugins, klikni gumb + in izberi Add custom MCP server.
  2. Vnesi ime in nastavi Server URL na https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Izberi No authentication.
  3. Preberi opozorilo o tveganju, izberi I understand and want to continue in klikni Create as a plugin.
  4. Vtičnik se prikaže na tvojem seznamu osebnih vtičnikov: odpri ga in namesti z gumbom +.
  5. Vrni se na domači zaslon ChatGPT, preklopi z zavihka Chat na Work, začni nov pogovor, vtipkaj @ in izberi svoj vtičnik.
  6. Prosi ga, naj vrže dvajsetstrano kocko: klicati mora roll_dice natanko enkrat z nastavitvijo sides na 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) in mcp (Python); pripni v1 z ext-apps 1.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