Премини към основното съдържание
Български— Изберете език
Меню

Вашият първи плъгин

Урок 4 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Два етапа
  2. Етап 1: Личен плъгин за пет минути
  3. Етап 2: Вашият собствен сървър
  4. Презареждане след всяка промяна
  5. Ключови изводи

Урокът е пренаписан на 3 ноември 2026 г. въз основа на страниците Quickstart, MCP server and UI quickstart и Connect and test your plugin от документацията на OpenAI за плъгини. Предишният пример „приложение за времето за 30 минути“ разчиташе на несъществуващ SDK. Проверихме версиите на npm пакетите на 3 ноември 2026 г.: @modelcontextprotocol/ext-apps 2.x се гради върху MCP SDK v2, докато примерите на OpenAI използват v1. Източници: Quickstart · MCP server and UI quickstart · Connect and test.

Два етапа

Първо ще свържете съществуващ MCP сървър, за да видите пълния работен процес на ChatGPT, без да пишете нито ред код. След това ще напишете собствен сървър, ще го тествате локално и ще го свържете по същия начин.

Етап 1: Личен плъгин за пет минути

OpenAI предоставя публичен, неавтентикиран примерен MCP сървър, който излага един инструмент само за четене: roll_dice.

  1. Отидете на ChatGPT Plugins, изберете бутона +, след което изберете Add custom MCP server.
  2. Въведете име и задайте Server URL на https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Изберете No authentication.
  3. Прочетете предупреждението за риска, изберете I understand and want to continue, след което кликнете върху Create as a plugin.
  4. Плъгинът се появява във вашия списък с лични плъгини: отворете го и го инсталирайте, като използвате бутона +.
  5. Върнете се на началния екран на ChatGPT, превключете от раздела Chat на Work, започнете нов разговор, въведете @ и изберете вашия плъгин.
  6. Помолете го да хвърли двадесетостенно зарче: то трябва да извика roll_dice точно веднъж с sides, зададено на 20, и да върне стойност между 1 и 20.

Не спирайте до идеалния сценарий. Опитайте различни размери на зарчето, невалидни стойности и заявки, които не трябва да задействат никакъв инструмент. Този рефлекс движи остатъка от курса: когато моделът избере грешен инструмент или варира аргументите си, трябва да усъвършенствате описанието и схемата на инструмента. Също така имайте предвид, че добавянето на персонализирани MCP сървъри се регулира от правилата на вашия акаунт или работно пространство: в една организация тази опция може да бъде ограничена.

Етап 2: Вашият собствен сървър

Инсталиране на официалните SDK

Съществуват официални SDK за протокола за TypeScript (@modelcontextprotocol/sdk) и Python (mcp). Този курс следва примерите на OpenAI, написани на TypeScript, използвайки SDK v1. Фиксирайте вашите версии: към септември 2026 г. @modelcontextprotocol/ext-apps 2.x — пакетът за интерфейс, който ще добавите в Урок 6 — разчита на новите пакети на SDK v2 (@modelcontextprotocol/server…), които са несъвместими с импортирането на 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 добавя "type": "module" към package.json, което е задължително за инструкциите import на сървъра.

Написване на сървъра

Този сървър се събира в един единствен файл, server.js. Той съхранява бележките в паметта и излага два инструмента: един за четене и един за запис, разделени както се препоръчва в Урок 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 = []; // примерни данни в паметта: заменете със собственото си хранилище
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;
  }

  // Режим без състояние: нов сървър и транспорт за всяка заявка
  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`));

Три детайла са от значение. Всеки инструмент декларира заглавие, описание на намерението, схеми и точни анотации: това е неговият „профил“ за модела. Всеки резултат комбинира structuredContent, което може да бъде повторно използвано от модела, и content, кратко текстово съобщение. Накрая, всеки адрес, различен от /mcp, връща 404: примерът на OpenAI прави това за маршрути за откриване на OAuth, които все още не използвате, предотвратявайки показването на грешки 502 от ChatGPT по време на вашите неавтентикирани тестове. Същият този пример добавя отговор за предварителната CORS заявка (OPTIONS) и GET / за здравни проверки; включете ги, ако вашият хостинг ги очаква.

Локално тестване с MCP Inspector

node server.js
npx @modelcontextprotocol/inspector@latest

В Inspector изберете Streamable HTTP, въведете http://localhost:8787/mcp и се свържете. Уверете се, че инициализацията е успешна, че и двата инструмента се появяват със своите схеми и анотации, след което ги извикайте с валидни и невалидни входни данни — празен текстов низ трябва да бъде отхвърлен от схемата.

Излагане на сървъра и свързването му

ChatGPT трябва да може да достигне вашия сървър от интернет. По време на разработка е достатъчен тунел — документацията цитира ngrok:

ngrok http 8787

Получавате публичен HTTPS адрес. Свържете го, както в Етап 1, включително пътя /mcp (например https://<subdomain>.ngrok.app/mcp), инсталирайте получения плъгин, след което го извикайте с @: „Запази бележка: обади се на доставчика в понеделник.“ ChatGPT показва данните, обменени с инструмента, което ви позволява да проверите входовете и изходите.

Разработческият тунел работи само за пробни периоди: публикуването изисква стабилна, публична HTTPS крайна точка (Урок 5).

Презареждане след всяка промяна

ChatGPT кешира метаданните на вашия сървър. След всяка промяна на името, описанието, схемата, анотацията, автентикацията или ресурса на интерфейса: преинсталирайте или рестартирайте сървъра, отворете връзката на chatgpt.com/plugins, изберете Refresh, проверете дали рекламираните метаданни са се променили, след което отворете нов разговор, за да стартирате тестовете си отново. Пропускането на тази стъпка означава тестване на старата версия, без да осъзнавате това.

Ключови изводи

  • Създайте личен плъгин чрез Add custom MCP server, след което го извикайте с @ в ChatGPT
  • Официални SDK: @modelcontextprotocol/sdk (TypeScript) и mcp (Python); фиксирайте v1 с ext-apps 1.x, за да следвате примерите на OpenAI
  • Минимален сървър: McpServer, registerTool, streamable HTTP транспорт на /mcp
  • Използвайте MCP Inspector за локално тестване, тунел за пробни периоди в ChatGPT
  • След всяка промяна на метаданните: Refresh, след което започнете нов разговор