README.md

ప్రాథమిక క్యాల్క్యులేటర్ MCP సర్వీస్

ఈ సర్వీస్ మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ (MCP) ద్వారా ప్రాథమిక క్యాల్క్యులేటర్ ఆపరేషన్లను Spring Boot తో WebFlux ట్రాన్స్‌పోర్ట్ ఉపయోగించి అందిస్తుంది. ఇది MCP అమలు గురించి నేర్చుకుంటున్న ప్రారంభకులకు ఒక సాదారణ ఉదాహరణగా రూపొందించబడింది.

మరింత సమాచారం కోసం, MCP సర్వర్ బూట్ స్టార్టర్ సూచన డాక్యుమెంటేషన్ చూడండి.

అవలోకనం

ఈ సర్వీస్ ఈ క్రింది అంశాలను ప్రదర్శిస్తుంది:

• SSE (సర్వర్-సెంట్స్ ఈవెంట్స్) కి మద్దతు
• Spring AI యొక్క @Tool అనోటేషన్ ఉపయోగించి ఆటోమేటిక్ టూల్ రిజిస్ట్రేషన్
• ప్రాథమిక క్యాల్క్యులేటర్ ఫంక్షన్లు:
  • జోడింపు, తీసివేత, గుణకం, భాగాకారం
  • పవర్ లెక్కింపు మరియు వర్గమూలం
  • మాడ్యులస్ (శేషం) మరియు సాపేక్ష విలువ
  • ఆపరేషన్ వివరణల కోసం సహాయం ఫంక్షన్

లక్షణాలు

ఈ క్యాల్క్యులేటర్ సర్వీస్ క్రింది సామర్థ్యాలను అందిస్తుంది:

1. ప్రాథమిక గణిత ఆపరేషన్లు:

   • రెండు సంఖ్యల జోడింపు
   • ఒక సంఖ్య నుండి మరొక సంఖ్య తీసివేత
   • రెండు సంఖ్యల గుణకం
   • ఒక సంఖ్యను మరొక సంఖ్యతో భాగించడం (శూన్యం భాగాకారం తనిఖీతో)

2. అధునాతన ఆపరేషన్లు:

   • పవర్ లెక్కింపు (బేస్ ను ఎక్స్‌పోనెంట్ కు ఎత్తడం)
   • వర్గమూలం లెక్కింపు (నెగటివ్ సంఖ్య తనిఖీతో)
   • మాడ్యులస్ (శేషం) లెక్కింపు
   • సాపేక్ష విలువ లెక్కింపు

3. సహాయం వ్యవస్థ:

   • అందుబాటులో ఉన్న అన్ని ఆపరేషన్లను వివరిస్తున్న బిల్ట్-ఇన్ సహాయం ఫంక్షన్

సర్వీస్ ఉపయోగించడం

ఈ సర్వీస్ MCP ప్రోటోకాల్ ద్వారా క్రింది API ఎండ్‌పాయింట్లను అందిస్తుంది:

• 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 క్లయింట్ ఉపయోగించడం

ప్రాజెక్ట్‌లో com.microsoft.mcp.sample.client.LangChain4jClient లో LangChain4j ఉదాహరణ క్లయింట్ ఉంది, ఇది క్యాల్క్యులేటర్ సర్వీస్‌ను LangChain4j మరియు GitHub మోడల్స్‌తో ఎలా ఇంటిగ్రేట్ చేయాలో చూపిస్తుంది:

ముందస్తు అవసరాలు

1. GitHub టోకెన్ సెటప్:

   GitHub యొక్క AI మోడల్స్ (ఉదా: phi-4) ఉపయోగించడానికి, మీకు GitHub వ్యక్తిగత యాక్సెస్ టోకెన్ అవసరం:

   a. మీ GitHub ఖాతా సెట్టింగ్స్‌కు వెళ్ళండి: https://github.com/settings/tokens

   b. "Generate new token" → "Generate new token (classic)" క్లిక్ చేయండి

   c. మీ టోకెన్‌కు వివరణాత్మక పేరు ఇవ్వండి

   d. క్రింది స్కోప్స్ ఎంచుకోండి:

   • repo (ప్రైవేట్ రిపోజిటరీల పూర్తి నియంత్రణ)
   • read:org (ఆర్గ్ మరియు టీమ్ సభ్యత్వం చదవడం, ఆర్గ్ ప్రాజెక్టులు చదవడం)
   • 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 క్లయింట్ నడపడం

ఈ ఉదాహరణ చూపిస్తుంది:

• SSE ట్రాన్స్‌పోర్ట్ ద్వారా క్యాల్క్యులేటర్ MCP సర్వర్‌కు కనెక్ట్ అవడం
• 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 ఇన్స్పెక్టర్ ఉపయోగించడం

MCP ఇన్స్పెక్టర్ MCP సర్వీసులతో ఇంటరాక్ట్ అయ్యేందుకు ఉపయోగకరమైన టూల్. ఈ క్యాల్క్యులేటర్ సర్వీస్‌తో ఉపయోగించడానికి:

1. MCP ఇన్స్పెక్టర్ ఇన్‌స్టాల్ చేసి నడపండి కొత్త టెర్మినల్ విండోలో:

   npx @modelcontextprotocol/inspector

2. వెబ్ UI యాక్సెస్ చేయండి యాప్ చూపించే URL పై క్లిక్ చేయండి (సాధారణంగా http://localhost:6274)

3. కనెక్షన్ కాన్ఫిగర్ చేయండి:

   • ట్రాన్స్‌పోర్ట్ టైప్‌ను "SSE" గా సెట్ చేయండి
   • మీ నడుస్తున్న సర్వర్ యొక్క SSE ఎండ్‌పాయింట్ URL ను సెట్ చేయండి: http://localhost:8080/sse
   • "Connect" క్లిక్ చేయండి

4. టూల్స్ ఉపయోగించండి:

   • "List Tools" క్లిక్ చేసి అందుబాటులో ఉన్న క్యాల్క్యులేటర్ ఆపరేషన్లను చూడండి
   • ఒక టూల్ ఎంచుకుని "Run Tool" క్లిక్ చేసి ఆపరేషన్ నడపండి

Docker ఉపయోగించడం

ప్రాజెక్ట్‌లో కంటైనర్ డిప్లాయ్‌మెంట్ కోసం Dockerfile ఉంది:

1. Docker ఇమేజ్ నిర్మించండి:

   docker build -t calculator-mcp-service .

2. Docker కంటైనర్ నడపండి:

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

ఇది:

• Maven 3.9.9 మరియు Eclipse Temurin 24 JDK తో మల్టీ-స్టేజ్ Docker ఇమేజ్‌ను నిర్మిస్తుంది
• ఆప్టిమైజ్డ్ కంటైనర్ ఇమేజ్ సృష్టిస్తుంది
• సర్వీస్‌ను 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 ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నించినప్పటికీ, ఆటోమేటెడ్ అనువాదాల్లో పొరపాట్లు లేదా తప్పిదాలు ఉండవచ్చు. మూల పత్రం దాని స్వదేశీ భాషలో అధికారిక మూలంగా పరిగణించాలి. ముఖ్యమైన సమాచారానికి, ప్రొఫెషనల్ మానవ అనువాదం సిఫార్సు చేయబడుతుంది. ఈ అనువాదం వాడకంలో ఏర్పడిన ఏవైనా అపార్థాలు లేదా తప్పుదారుల కోసం మేము బాధ్యత వహించము.