Skip to content

Latest commit

 

History

History
284 lines (205 loc) · 19 KB

README.md

File metadata and controls

284 lines (205 loc) · 19 KB

Първи стъпки с MCP

Добре дошли в първите ви стъпки с Model Context Protocol (MCP)! Независимо дали сте нови в MCP или искате да задълбочите познанията си, това ръководство ще ви преведе през основните стъпки за настройка и разработка. Ще откриете как MCP позволява безпроблемна интеграция между AI модели и приложения и ще научите как бързо да подготвите средата си за създаване и тестване на решения, базирани на MCP.

TLDR; Ако създавате AI приложения, знаете, че можете да добавяте инструменти и други ресурси към вашия LLM (голям езиков модел), за да го направите по-знаещ. Но ако поставите тези инструменти и ресурси на сървър, приложението и възможностите на сървъра могат да бъдат използвани от всеки клиент със или без LLM.

Общ преглед

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

Model Context Protocol (MCP) е отворен протокол, който стандартизира начина, по който приложенията предоставят контекст на LLM. Мислете за MCP като за USB-C порт за AI приложения - той предоставя стандартизиран начин за свързване на AI модели с различни източници на данни и инструменти.

Учебни цели

До края на този урок ще можете да:

  • Настроите среди за разработка за MCP на C#, Java, Python, TypeScript и Rust
  • Създавате и внедрявате основни MCP сървъри с персонализирани функции (ресурси, подсказки и инструменти)
  • Създавате хост приложения, които се свързват с MCP сървъри
  • Тествате и отстранявате грешки в MCP реализации

Настройка на вашата MCP среда

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

Предварителни изисквания

Преди да се потопите в разработката с MCP, уверете се, че разполагате с:

  • Среда за разработка: За избрания от вас език (C#, Java, Python, TypeScript или Rust)
  • IDE/Редактор: Visual Studio, Visual Studio Code, IntelliJ, Eclipse, PyCharm или друг модерен редактор за код
  • Мениджъри на пакети: NuGet, Maven/Gradle, pip, npm/yarn или Cargo
  • API ключове: За всякакви AI услуги, които планирате да използвате във вашите хост приложения

Основна структура на MCP сървър

Типичният MCP сървър включва:

  • Конфигурация на сървъра: Настройка на порт, автентикация и други параметри
  • Ресурси: Данни и контекст, предоставени на LLM
  • Инструменти: Функционалности, които моделите могат да извикват
  • Подсказки: Шаблони за генериране или структуриране на текст

Ето опростен пример на TypeScript:

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Create an MCP server
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// Add an addition tool
server.tool("add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// Add a dynamic greeting resource
server.resource(
  "file",
  // The 'list' parameter controls how the resource lists available files. Setting it to undefined disables listing for this resource.
  new ResourceTemplate("file://{path}", { list: undefined }),
  async (uri, { path }) => ({
    contents: [{
      uri: uri.href,
      text: `File, ${path}!`
    }]
// Add a file resource that reads the file contents
server.resource(
  "file",
  new ResourceTemplate("file://{path}", { list: undefined }),
  async (uri, { path }) => {
    let text;
    try {
      text = await fs.readFile(path, "utf8");
    } catch (err) {
      text = `Error reading file: ${err.message}`;
    }
    return {
      contents: [{
        uri: uri.href,
        text
      }]
    };
  }
);

server.prompt(
  "review-code",
  { code: z.string() },
  ({ code }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Please review this code:\n\n${code}`
      }
    }]
  })
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

В горния код:

  • Импортираме необходимите класове от MCP TypeScript SDK.
  • Създаваме и конфигурираме нова инстанция на MCP сървър.
  • Регистрираме персонализиран инструмент (calculator) с функция за обработка.
  • Стартираме сървъра, за да слуша входящи MCP заявки.

Тестване и отстраняване на грешки

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

MCP предоставя инструменти за тестване и отстраняване на грешки на вашите сървъри:

  • Инструмент за инспекция: Графичен интерфейс, който ви позволява да се свържете със сървъра и да тествате вашите инструменти, подсказки и ресурси.
  • curl: Можете също да се свържете със сървъра, използвайки команден инструмент като curl или други клиенти, които могат да създават и изпълняват HTTP команди.

Използване на MCP Inspector

MCP Inspector е визуален инструмент за тестване, който ви помага:

  1. Откриване на възможностите на сървъра: Автоматично откриване на налични ресурси, инструменти и подсказки
  2. Тестване на изпълнението на инструменти: Изпробване на различни параметри и преглед на отговорите в реално време
  3. Преглед на метаданни на сървъра: Изследване на информация за сървъра, схеми и конфигурации
# ex TypeScript, installing and running MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Когато изпълните горните команди, MCP Inspector ще стартира локален уеб интерфейс във вашия браузър. Можете да очаквате да видите табло, показващо вашите регистрирани MCP сървъри, техните налични инструменти, ресурси и подсказки. Интерфейсът ви позволява интерактивно да тествате изпълнението на инструменти, да инспектирате метаданни на сървъра и да преглеждате отговори в реално време, което улеснява валидирането и отстраняването на грешки във вашите MCP реализации.

Ето как може да изглежда:

MCP Inspector server connection

Често срещани проблеми при настройка и решения

Проблем Възможно решение
Отказ на връзката Проверете дали сървърът работи и портът е правилен
Грешки при изпълнение на инструменти Прегледайте валидирането на параметрите и обработката на грешки
Неуспешна автентикация Уверете се, че API ключовете и разрешенията са правилни
Грешки при валидиране на схема Уверете се, че параметрите съответстват на дефинираната схема
Сървърът не стартира Проверете за конфликти на портове или липсващи зависимости
CORS грешки Конфигурирайте правилни CORS заглавия за заявки от различни източници
Проблеми с автентикация Проверете валидността на токените и разрешенията

Локална разработка

За локална разработка и тестване можете да стартирате MCP сървъри директно на вашата машина:

  1. Стартирайте процеса на сървъра: Стартирайте вашето MCP сървърно приложение
  2. Конфигурирайте мрежата: Уверете се, че сървърът е достъпен на очаквания порт
  3. Свържете клиенти: Използвайте локални URL адреси за връзка като http://localhost:3000
# Example: Running a TypeScript MCP server locally
npm run start
# Server running at http://localhost:3000

Създаване на първия ви MCP сървър

Разгледахме Основни концепции в предишен урок, сега е време да приложим тези знания на практика.

Какво може да прави сървърът

Преди да започнем да пишем код, нека си припомним какво може да прави един сървър:

MCP сървърът може например:

  • Да достъпва локални файлове и бази данни
  • Да се свързва с отдалечени API
  • Да извършва изчисления
  • Да се интегрира с други инструменти и услуги
  • Да предоставя потребителски интерфейс за взаимодействие

Чудесно, сега, когато знаем какво можем да направим, нека започнем с кодирането. Свързване

Вече сте свързани със сървъра
Секцията за тестване на Java сървъра е завършена

Следващата секция е за взаимодействие със сървъра.

Трябва да видите следния потребителски интерфейс:

Свързване

  1. Свържете се със сървъра, като изберете бутона "Connect".
    След като се свържете със сървъра, трябва да видите следното:

    Свързан

  2. Изберете "Tools" и "listTools". Трябва да видите "Add", изберете "Add" и попълнете стойностите на параметрите.

    Трябва да видите следния отговор, т.е. резултат от инструмента "add":

    Резултат от изпълнение на add

Поздравления, успяхте да създадете и изпълните първия си сървър!

Rust

За да стартирате Rust сървъра с MCP Inspector CLI, използвайте следната команда:

npx @modelcontextprotocol/inspector cargo run --cli --method tools/call --tool-name add --tool-arg a=1 b=2

Официални SDKs

MCP предоставя официални SDKs за множество езици:

  • C# SDK - Поддържан в сътрудничество с Microsoft
  • Java SDK - Поддържан в сътрудничество със Spring AI
  • TypeScript SDK - Официалната TypeScript имплементация
  • Python SDK - Официалната Python имплементация
  • Kotlin SDK - Официалната Kotlin имплементация
  • Swift SDK - Поддържан в сътрудничество с Loopwork AI
  • Rust SDK - Официалната Rust имплементация

Основни моменти

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

Примери

Задача

Създайте прост MCP сървър с инструмент по ваш избор:

  1. Имплементирайте инструмента на предпочитания от вас език (.NET, Java, Python, TypeScript или Rust).
  2. Дефинирайте входни параметри и стойности за връщане.
  3. Стартирайте инспектор инструмента, за да се уверите, че сървърът работи правилно.
  4. Тествайте имплементацията с различни входни данни.

Решение

Решение

Допълнителни ресурси

Какво следва

Следва: Започване с MCP клиенти

Отказ от отговорност:
Този документ е преведен с помощта на AI услуга за превод Co-op Translator. Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод.