MCP serveri seadistamine ja ühendamine Claude'iga

Mis on MCP server?

MCP server (Model Context Protocol server) on programm, mis võimaldab tehisintellektil (nt Claude'il) suhelda väliste tööriistade ja andmetega — näiteks lugeda dokumente, küsida andmebaasist infot või käivitada skripte. Muidu AI ei saa turva- ja arhitektuuripiirangute tõttu teiste süsteemidega otse ühendust luua.

Ilma MCP serverita:

LLM AI  —X—  väline rakendus (nt Messenger)

MCP serveri abil:

LLM AI  —  MCP server  —  (REST API)  —  väline rakendus

MCP server tõlgendab AI poolt genereeritud käsud ning vahendab need sobival kujul välistele süsteemidele, võimaldades ligipääsu andmetele ja funktsionaalsusele, mis muidu oleksid AI-le kättesaamatud.

Näited MCP serveri kasutusvõimalustest

Pärast MCP serveri ning vastavate ühenduste (nt REST API) seadistamist on võimalik anda AI-le mitmesuguseid ülesandeid, näiteks:

  • analüüsida Google Drive'i kaustas „TalTech" asuvaid märkmeid ning koostada nende põhjal õppimisplaan (eeldab REST API ühenduse loomist Google Drive'i ja MCP serveri vahel);

  • käivitada lokaalne skript kindla käsu alusel, näiteks koodi testimiseks (vajalik on vaid ligipääs lokaalsele koodifailile);

  • otsida GitHubi repositooriumitest viimase nädala jooksul tehtud muudatusi tarkvaraarendusprojektis ning koostada neist inimloetav kokkuvõte (eeldab REST API ühendust GitHubiga);

  • "Loe läbi kõik mu kaust 'Päevik' .txt sissekanded ajaperioodist 2024 mai-juuni. Analüüsi kas ja kui palju mu stressitase tõusis sessi ajal ja küsi lisaküsimusi kui vaja."

Käesolevas õppematerjalis käsitletakse viimast näidet lihtsustatud kujul, et demonstreerida MCP serveri ja AI koostööpõhimõtteid praktilise ülesande kaudu.

Eeldused ja vajalikud vahendid

Õppematerjali läbimiseks on vajalikud järgmised eeldused ja töövahendid:

  • arvuti, millel on võimalik arendustarkvara käivitada;

  • paigaldatud Claude Desktop rakendus, mis on allalaaditav aadressilt https://claude.ai/download (soovitatav on pärast paigaldamist kontrollida rakenduse toimimist lihtsa päringuga);

  • algteadmised Java programmeerimiskeelest;

  • käesolev õppematerjal tugineb osaliselt juhendile https://www.danvega.dev/blog/creating-your-first-mcp-server-java, millega on soovitatav soovi korral täiendavalt tutvuda.

Lisaks on vajalik järgmine tarkvara:

  • Java Development Kit (JDK) 17 või uuem — tavaliselt olemas kooliprojektide raames kasutatavates arenduskeskkondades (nt IntelliJ IDEA kaudu);

  • Maven või Gradle sõltuvuste haldamiseks, sõltuvalt valitud projekti seadistusest;

  • elementaarne arusaam Spring Boot-ist on soovitatav, kuid ei ole hädavajalik;

  • MCP klienditarkvara testimiseks — käesolevas juhendis kasutatakse Claude Desktopi rakendust.

Projekti loomise alustamine

Järgnevalt alustatakse MCP serveri projekti loomisega Spring Initializr'i abil.

  1. Ava veebileht https://start.spring.io/ ja vali projekti jaoks sobivad seadistused.

  2. Enne projekti loomist kontrolli Java versiooni oma arvutis. Seda saab teha näiteks terminalis:

    java -version

    Vastuseks saad nt openjdk version "21.0.10" — vali vastavalt.

../_images/project-setup.png

  1. Kasuta otsinguvälja (Search) ja otsi MCP.

  2. Täida Metadata väljad.

../_images/protocol.png

  1. Vajuta Generate.

../_images/metadata.png

Projekti avamine ja Note klassi loomine

  1. Unzip allalaaditud kaust ja ava oma IDE's (nt IntelliJ IDEA).

  2. Kaustas src/main/[SinuSpringIoProjektiNimi] loo uus Java klassifail, mille nimi peegeldab selle otstarvet. Näiteks Note — tööriist päevikumärkmete lugemiseks.

../_images/class.png

Note

Uuemates Java versioonides on soovitatav kasutada class asemel record.

  1. Muuda klassideklaratsioon järgmisele kujule:

../_images/record.png 
package taltech.stkang.mcpserver;

public record Note(String title, String content) {}

NoteHandling klassi loomine

Loo uus klass NoteHandling, kuhu hakkad lisama @Tool annoteeritud meetodeid, mida Claude kasutama hakkab:

Note

@Tool on Spring AI annotatsioon, mis märgib meetodi Claude'ile kasutamiseks kättesaadavaks. Parameeter name on tööriista identifikaator ja description selgitab Claude'ile, millal ja miks seda tööriista kasutada.

package taltech.stkang.mcpserver;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class NoteHandling {
    private static final List<Note> notes = List.of(
        new Note("Monday", "esmasp olin väga kurb"),
        new Note("Tuesday", "teisiga sain aru et ma ei oska matemaatikat, aga mulle meeldivad kassid"),
        new Note("Wednesday", "kolmap oli hea tuju, sest sees edukalt läbi")
    );

    @Tool(name = "get_notes", description = "return my notes")
    public List<Note> getNotes() {
        return notes;
    }

    @Tool(name = "get_notes_content_by_day", description = "return notes content based on weekday")
    public List<Note> getNotesByDay(String day) {
        return notes.stream().filter(note -> note.title().equalsIgnoreCase(day)).toList();
    }
}

Bean'i lisamine põhiklassi

Mine tagasi põhiklassi (Spring Initializr poolt loodud, nt McpserverApplication) ja lisa sinna Bean:

../_images/bean.png 
@SpringBootApplication
public class McpserverApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpserverApplication.class, args);
    }

    @Bean
    public List<ToolCallback> noteTools(NoteHandling noteHandling) {
        return List.of(ToolCallbacks.from(noteHandling));
    }
}

Serveri konfigureerimine

Ava fail application.properties ja lisa järgmised seadistused:

spring.application.name=mcpserver

spring.main.web-application-type=none
spring.ai.mcp.server.name=stkang-mcp-server
spring.ai.mcp.server.version=0.0.1

# STDIO transpordi toimimiseks on vajalik keelata banner ja konsoolilogimine!
spring.main.banner-mode=off
logging.pattern.console=

Warning

Spring Boot versiooni 3.5.0+ korral kasuta logging.pattern.console= asemel logging.level.root=OFF.

Projekti ehitamine Gradle'iga

IntelliJ IDEA's ava parempoolsel paneelil Gradle tööriistavaade (elevandi ikoon).

  1. Tee topeltklõps käsul clean ja oota lõpetamist.

  2. Tee topeltklõps käsul build ja oota lõpetamist.

See vastab käsureal käsule:

./gradlew clean build

Claude Desktop seadistamine

Claude Desktop rakenduses ava: Settings → Developer → Edit Config.

../_images/config.png

Leia konfiguratsioonifail ja ava see oma IDE's. Lisa järgmised seadistused, asendades näidisväärtused oma süsteemile vastavate teedega:

Windows:

{
  "mcpServers": {
    "stkang-mcp-server": {
      "command": "C:\\Program Files\\Eclipse Adoptium\\jdk-21.0.10.7-hotspot\\bin\\java.exe",
      "args": [
        "-jar",
        "C:\\Users\\Administrator\\Desktop\\mcpserver\\mcpserver\\build\\libs\\mcpserver-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Note

  • command — asenda oma Java asukoha teega

  • args — asenda oma Spring projekti build/libs/...-SNAPSHOT.jar faili teega

Pärast muudatuste salvestamist sulge Claude Desktop ja ava uuesti, et konfiguratsioon rakenduda.

Kasutamine

Pärast edukat seadistamist:

  1. Ava chat Claude'ga.

  2. Esmakordsel kasutamisel küsib rakendus luba MCP serveri tööriistade kasutamiseks — kinnita vajalikud õigused.

  3. Claude saab nüüd kasutada loodud @Tool meetodeid ja pääseda ligi konfigureeritud lokaalsetele andmetele.

Sama põhimõtte alusel saab lisada täiendavaid @Tool annotatsiooniga meetodeid, et laiendada süsteemi funktsionaalsust.

Note

Kas juhendis esineb ebatäpsusi, mitmetimõistetavust või puudujääke? Tagasiside on teretulnud.

Warning

Kui MCP server ei käivitu ja kasutatakse Spring Boot versiooni 3.5.0 või uuemat, võib probleem olla seotud versioonimuudatustega. Sellisel juhul määra projektis Spring Boot versiooniks 3.4.5, mis on stabiilsem. Pärast versiooni muutmist käivita Gradle'i kaudu uuesti clean ja build.