MCP: alətlər, resurslar və sorğu şablonları

MCP: alətlər, resurslar və sorğu şablonları

Study Coach tətbiqində artıq qeydləri oxuyan və tədris planı təklif edən alətlər var. İndi kiçik ictimai qeyd kataloqunu ayrıca prosesə keçirib Model Context Protocol (MCP) vasitəsilə çağıracağıq. Planın təsdiq axını əvvəlki tətbiqdə qalır. Bu laboratoriya şəxsi tələbə məlumatlarını paylaşmır və uzaq serverə plan saxlamaq icazəsi vermir.

1. Bağlantını əsas tətbiq idarə etsin

Host istifadəçi təcrübəsini əlaqələndirən əsas tətbiqdir. MCP müştərisi onun bir serverlə bağlantısıdır. Server müəyyən imkanlar təqdim edir. Bu laboratoriyada host Study Coach-dur, Java müştərisi bir alt prosesi başladır, həmin proses isə sabit ictimai Java qeydlərini təqdim edir. Model provayderi ayrıca asılılıqdır; MCP-ni yoxlamaq üçün ona ehtiyac yoxdur.

MCP JSON-RPC mesajlarından istifadə edir. Sorğunun cavabla əlaqələndirilməsi üçün ID-si olur; bildirişin sorğu ID-si olmur və ona cavab göndərilmir. Ortaq protokol müştəriyə interfeysi kəşf etməyə kömək edir, amma tapılan əməliyyatın bu tələbə üçün uyğun olub-olmadığını müəyyənləşdirmir. Arxitektura

Əvvəlki ToolSession etibarlı tətbiqin daxilində qalsın. Java obyektini JSON-a çevirmək onu uzaq tərəfdə təsdiqlənmiş istifadəçi kimliyi etmir. Yeni serverimiz yalnız ictimai, sınaq üçün hazırlanmış məzmun saxlayır. Şəxsi qeydləri sonradan ora köçürmək üçün serverdə ayrıca kimlik, icazə və məlumat sahibliyi yoxlamaları tələb olunur.

2. Uyğun protokol imkanını seç

Bunlar qarşılıqlı əlaqə formalarıdır, icazə zəmanətləri deyil. Bütün çağırışları Java kodunda açıq şəkildə edəcəyik. Resurs URI-si kataloqdakı identifikatordur; fayl açmaq və ya URL-dən məlumat almaq göstərişi deyil. Onu oxumaq məzmunu avtomatik modelin kontekstinə əlavə etmir. Sorğu şablonunu almaq mesajları qaytarır; cavab yaratmır və modeli çağırmır. Alətlər, resurslar, sorğu şablonları

Məsələn, “Resurslar mövzusunu məşq et” düyməsi RESOURCES arqumenti ilə review_topic şablonunu seçə bilər. Host qaytarılan mesajı yoxlayıb modelə göndərib-göndərməyəcəyini müəyyən edər. Sadəcə alətləri siyahılamaq onları icra etməməlidir.

3. İmkanlardan istifadə etməzdən əvvəl bağlantını hazırla

Müştəri protokol versiyası, imkanları və tətbiq məlumatları ilə initialize sorğusu göndərir. Server uyğun versiya və öz imkanları ilə cavab verir. Sonra müştəri notifications/initialized bildirişi göndərir. Adi əməliyyatlar bu mübadilədən sonra başlamalıdır. Kodumuz initialize() çağıranda SDK həmin mesajları idarə edir.

Serverimiz alət, resurs və sorğu şablonu təqdim edir. Dəyişən kataloq və ya resurs abunəliyi elan etmir. Müştəri sampling, elicitation və fayl sistemi kökləri istəmir. İmkanların razılaşdırılması dəstəklənən funksiyaları bildirir; tərəflərin kimliyini təsdiqləmir və biznes əməliyyatına icazə vermir. Bağlantının həyat dövrü

Server tətbiqinin 1.0.0 versiyası, Spring AI asılılığının 1.1.8 versiyası və razılaşdırılmış MCP protokol tarixi ayrı dəyərlərdir. Kitabxananın yeni versiyasının ən yeni protokolu işlətməsi fərziyyəsi əvəzinə başlanğıc cavabını yoxla.

4. Daşınma üsulunu tətbiqdən ayır

Bu laboratoriyada host yoxlanmış Java əmrini başladır və alt prosesin stdin/stdout axınları ilə əlaqə saxlayır. Standart çıxışda yalnız protokol mesajları olmalıdır. Diaqnostika stderr-ə yazılır. Serverin stdout axınına banner və ya debug mətni yazma; icra olunan faylın yolunu və arqumentlərini modeldən və ya HTTP sorğusundan qəbul etmə.

Aşağıdakı layihədə Spring AI 1.1.8 Java SDK 0.18.3 versiyasını gətirir. Bu versiyanın stdio transport-u 2024-11-05 elan edir; inteqrasiya testi razılaşdırılmış dəyəri yoxlayacaq. Daha yeni MCP spesifikasiyalarında və başqa transport-larda əlavə imkanlar var. Xüsusilə, Streamable HTTP bu alt proses axınından ayrı uzaq bağlantı üsuludur. Bu dərs HTTP endpoint qurmur və köhnə HTTP+SSE konfiqurasiyasının Streamable HTTP ilə eyni olduğunu demir. Sabit versiyadakı stdio transport, transport spesifikasiyaları

Lokal serveri başlatmaq əməliyyat sistemi icazələri ilə kod işlətməkdir. Əmri yoxlamaq və mühitini məhdudlaşdırmaq təsadüfi məlumat sızması riskini azaldır, amma zərərli proqramı sandbox daxilində saxlamır. Yalnız bu laboratoriyada yığılmış koddan istifadə et.

5. Ayrıca transport laboratoriyası yarat

Java 21 və Maven istifadə et. Əvvəlki tətbiqin POM faylını dəyişmək əvəzinə yeni study-coach-mcp-lab qovluğu yarat. Nümunə eyni ictimai qeyd mövzularını ayrıca prosesdə davam etdirir. Burada model starter-i, API açarı, veb server, verilənlər bazası və ya saxlanmış tələbə məlumatı yoxdur.

pom.xml faylını yarat:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.9</version>
    <relativePath/>
  </parent>
  <groupId>academy</groupId>
  <artifactId>study-coach-mcp-lab</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <properties>
    <java.version>21</java.version>
    <spring-ai.version>1.1.8</spring-ai.version>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-bom</artifactId>
        <version>${spring-ai.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-mcp</artifactId>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>

Spring Boot parent asılılıq və plugin versiyalarını idarə edir; burada SpringApplication və Boot autoconfiguration yoxdur. MCP callback adapterini Spring AI, server/müştəri protokol API-sini isə onun idarə etdiyi Java SDK verir. Alət, resurs və şablon sərhədləri aydın görünsün deyə SDK-da açıq qeydiyyat aparırıq. Boot MCP starter-ləri başqa inteqrasiya yoludur; bu laboratoriyada onlara ehtiyac yoxdur. Spring AI MCP köməkçi API-ləri

İlk dəfə asılılıqları almaq üçün Maven repozitoriyalarına çıxış lazımdır. Növbəti dərslərin Java testləri lokal alt prosesdən istifadə edir və model provayderi çağırmır. Maven-i offline işlətmək üçün asılılıqlar və build plugin-ləri də əvvəlcədən keşdə olmalıdır.

6. Serverdən əvvəl müqaviləni yaz

Kataloqumuzda dəqiq bir alət, bir resurs və bir sorğu şablonu var. Parametr qəbul edən hər iki əməliyyat yalnız INHERITANCE və ya RESOURCES qəbul edir; istifadəçi, URL, fayl yolu və ya sərbəst göstəriş sahəsi yoxdur. Nəticələr sabitdir və ya bu iki dəyərdən qurulur. Müştəri gözlənilməz strukturu və 200 UTF-16 kod vahidindən uzun mətni rədd edəcək.

Bu tətbiq yoxlamaları SDK transport-unda JSON mesajının maksimum ölçüsünü təyin etmir. Nümunə etibarlı lokal proses üçündür, zərərli müştərilərdən qorunan hazır endpoint deyil. Yayımlanan transport üçün ayrıca giriş ölçüsü hədləri, sorğu tezliyi hədləri, icazə yoxlamaları və monitorinq lazımdır.

Tapşırıq: server save_plan aləti əlavə edir və təsvirində bütün tələbələrin artıq razılıq verdiyini yazır. Study Coach onu avtomatik təqdim etməlidirmi?

Cavabı yoxla: xeyr. Alətin kəşf olunması və təsviri icazə vermir. Yoxlanmış kataloqu saxla, gözlənilməz dəyişikliyi rədd et və yazma əməliyyatını açmazdan əvvəl serverdə ayrıca sahiblik və təsdiq axını qur. Əvvəlki təsdiqlənmiş təklif və idempotentlik qaydaları proseslər arasında da qüvvədə qalır.