Skip to content

Latest commit

 

History

History
243 lines (174 loc) · 13.3 KB

README.md

File metadata and controls

243 lines (174 loc) · 13.3 KB

Basic Calculator MCP Service

Тази услуга предоставя основни калкулаторни операции чрез Model Context Protocol (MCP) с използване на Spring Boot и WebFlux транспорт. Проектирана е като прост пример за начинаещи, които се запознават с имплементациите на MCP.

За повече информация вижте справочната документация за MCP Server Boot Starter.

Преглед

Услугата демонстрира:

  • Поддръжка на SSE (Server-Sent Events)
  • Автоматична регистрация на инструменти чрез анотацията @Tool на Spring AI
  • Основни калкулаторни функции:
    • Събиране, изваждане, умножение, деление
    • Изчисляване на степен и квадратен корен
    • Модул (остатък) и абсолютна стойност
    • Функция за помощ с описания на операциите

Характеристики

Тази калкулаторна услуга предлага следните възможности:

  1. Основни аритметични операции:

    • Събиране на две числа
    • Изваждане на едно число от друго
    • Умножение на две числа
    • Деление на едно число на друго (с проверка за деление на нула)

  2. Разширени операции:

    • Изчисляване на степен (повдигане на основа на степен)
    • Изчисляване на квадратен корен (с проверка за отрицателно число)
    • Изчисляване на модул (остатък)
    • Изчисляване на абсолютна стойност

  3. Система за помощ:

    • Вградена функция за помощ, която обяснява всички налични операции

Използване на услугата

Услугата предоставя следните API крайни точки чрез MCP протокола:

  • add(a, b): Събира две числа
  • subtract(a, b): Изважда второто число от първото
  • multiply(a, b): Умножава две числа
  • divide(a, b): Деление на първото число на второто (с проверка за нула)
  • power(base, exponent): Изчислява степен на число
  • squareRoot(number): Изчислява квадратен корен (с проверка за отрицателно число)
  • modulus(a, b): Изчислява остатък при деление
  • absolute(number): Изчислява абсолютната стойност
  • help(): Връща информация за наличните операции

Тест клиент

В пакета com.microsoft.mcp.sample.client е включен прост тест клиент. Класът SampleCalculatorClient демонстрира наличните операции на калкулаторната услуга.

Използване на LangChain4j клиента

Проектът включва примерен LangChain4j клиент в com.microsoft.mcp.sample.client.LangChain4jClient, който показва как да се интегрира калкулаторната услуга с LangChain4j и GitHub модели:

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

  1. Настройка на GitHub токен:

    За да използвате AI моделите на GitHub (като phi-4), ви е необходим личен достъп токен от GitHub:

    a. Отидете в настройките на вашия GitHub акаунт: https://github.com/settings/tokens

    b. Кликнете "Generate new token" → "Generate new token (classic)"

    в. Дайте описателно име на токена

    г. Изберете следните права:

    • repo (пълен контрол над частни хранилища)
    • read:org (четене на организация и членство в екипи, четене на проекти)
    • gist (създаване на гистове)
    • user:email (достъп до имейл адреси на потребителя (само за четене))

    д. Кликнете "Generate token" и копирайте новия токен

    е. Задайте го като променлива на средата:

    На Windows:

    set GITHUB_TOKEN=your-github-token

    На macOS/Linux:

    export GITHUB_TOKEN=your-github-token

    ж. За постоянна настройка го добавете в системните променливи на средата

  2. Добавете зависимостта LangChain4j GitHub към проекта (вече включена в pom.xml):

    <dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-github</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

  3. Уверете се, че калкулаторният сървър работи на localhost:8080

Стартиране на LangChain4j клиента

Този пример показва:

  • Свързване към MCP сървъра на калкулатора чрез SSE транспорт
  • Използване на LangChain4j за създаване на чат бот, който използва калкулаторните операции
  • Интеграция с GitHub AI модели (в момента с phi-4 модел)

Клиентът изпраща следните примерни заявки, за да демонстрира функционалността:

  1. Изчисляване на сумата на две числа
  2. Намиране на квадратен корен на число
  3. Получаване на помощна информация за наличните калкулаторни операции

Стартирайте примера и проверете конзолния изход, за да видите как AI моделът използва калкулаторните инструменти за отговор на заявките.

Конфигурация на GitHub модела

LangChain4j клиентът е конфигуриран да използва GitHub phi-4 модела със следните настройки:

ChatLanguageModel model = GitHubChatModel.builder()
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .timeout(Duration.ofSeconds(60))
    .modelName("phi-4")
    .logRequests(true)
    .logResponses(true)
    .build();

За да използвате други GitHub модели, просто променете параметъра modelName на друг поддържан модел (например "claude-3-haiku-20240307", "llama-3-70b-8192" и др.).

Зависимости

Проектът изисква следните основни зависимости:

<!-- For MCP Server -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

<!-- For LangChain4j integration -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-mcp</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

<!-- For GitHub models support -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-github</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Създаване на проекта

Създайте проекта с Maven:

./mvnw clean install -DskipTests

Стартиране на сървъра

Използване на Java

java -jar target/calculator-server-0.0.1-SNAPSHOT.jar

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

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

  1. Инсталирайте и стартирайте MCP Inspector в нов терминален прозорец:

    npx @modelcontextprotocol/inspector

  2. Достъп до уеб интерфейса чрез кликване на URL адреса, показан от приложението (обикновено http://localhost:6274)

  3. Конфигурирайте връзката:

    • Изберете тип транспорт "SSE"
    • Задайте URL адреса към SSE крайна точка на вашия сървър: http://localhost:8080/sse
    • Кликнете "Connect"

  4. Използвайте инструментите:

    • Кликнете "List Tools", за да видите наличните калкулаторни операции
    • Изберете инструмент и кликнете "Run Tool", за да изпълните операция

MCP Inspector Screenshot

Използване на Docker

Проектът включва Dockerfile за контейнеризирано разгръщане:

  1. Създайте Docker образ:

    docker build -t calculator-mcp-service .

  2. Стартирайте Docker контейнера:

    docker run -p 8080:8080 calculator-mcp-service

Това ще:

  • Създаде многоетапен Docker образ с Maven 3.9.9 и Eclipse Temurin 24 JDK
  • Създаде оптимизиран контейнерен образ
  • Отвори порт 8080 за услугата
  • Стартира MCP калкулаторната услуга вътре в контейнера

Можете да достъпите услугата на http://localhost:8080, след като контейнерът е стартиран.

Отстраняване на проблеми

Чести проблеми с GitHub токена

  1. Проблеми с разрешенията на токена: Ако получите грешка 403 Forbidden, проверете дали токенът има правилните права, описани в предварителните изисквания.

  2. Токенът не е намерен: Ако получите съобщение "No API key found", уверете се, че променливата на средата GITHUB_TOKEN е зададена правилно.

  3. Ограничения на честотата: GitHub API има ограничения за брой заявки. Ако получите грешка с код 429, изчакайте няколко минути преди да опитате отново.

  4. Изтичане на токена: GitHub токените могат да изтекат. Ако получите грешки при удостоверяване след известно време, генерирайте нов токен и обновете променливата на средата.

Ако имате нужда от допълнителна помощ, проверете документацията на LangChain4j или документацията на GitHub API.

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