Skip to content

Latest commit

 

History

History
243 lines (174 loc) · 13.2 KB

README.md

File metadata and controls

243 lines (174 loc) · 13.2 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 Token:

    Для використання AI-моделей GitHub (наприклад, phi-4) потрібен персональний токен доступу GitHub:

    a. Перейдіть у налаштування свого облікового запису GitHub: https://github.com/settings/tokens

    b. Натисніть "Generate new token" → "Generate new token (classic)"

    c. Дайте токену описову назву

    d. Виберіть такі області доступу:

    • repo (Повний контроль приватних репозиторіїв)
    • read:org (Читання організацій та членства в командах, читання проєктів організації)
    • gist (Створення gist)
    • user:email (Доступ до електронних адрес користувача (тільки для читання))

    e. Натисніть "Generate token" і скопіюйте новий токен

    f. Встановіть його як змінну середовища:

    На Windows:

    set GITHUB_TOKEN=your-github-token

    На macOS/Linux:

    export GITHUB_TOKEN=your-github-token

    g. Для постійного налаштування додайте його у змінні середовища через системні налаштування

  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 для створення чат-бота, який використовує операції калькулятора
  • Інтеграцію з AI-моделями GitHub (тепер з моделлю phi-4)

Клієнт надсилає такі приклади запитів для демонстрації функціоналу:

  1. Обчислення суми двох чисел
  2. Знаходження квадратного кореня числа
  3. Отримання інформації про доступні операції калькулятора

Запустіть приклад і перевірте вивід у консолі, щоб побачити, як AI-модель використовує інструменти калькулятора для відповіді на запити.

Налаштування моделі GitHub

Клієнт LangChain4j налаштований на використання моделі phi-4 GitHub з такими параметрами:

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 Token

  1. Проблеми з дозволами токена: Якщо ви отримуєте помилку 403 Forbidden, перевірте, чи має ваш токен правильні дозволи, як описано у вимогах.

  2. Токен не знайдено: Якщо з’являється помилка "No API key found", переконайтеся, що змінна середовища GITHUB_TOKEN встановлена правильно.

  3. Обмеження швидкості (Rate Limiting): GitHub API має обмеження на кількість запитів. Якщо ви отримали помилку з кодом 429, зачекайте кілька хвилин і спробуйте знову.

  4. Термін дії токена минув: Токени GitHub можуть мати термін дії. Якщо після деякого часу виникають помилки автентифікації, створіть новий токен і оновіть змінну середовища.

Якщо потрібна додаткова допомога, звертайтеся до документації LangChain4j або документації GitHub API.

Відмова від відповідальності:
Цей документ було перекладено за допомогою сервісу автоматичного перекладу Co-op Translator. Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується звертатися до професійного людського перекладу. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу.