Files

T

wehub-resource-sync c275ba2868 chore: import upstream snapshot with attribution

2026-07-13 13:31:35 +08:00

40 KiB

Raw Permalink Blame History

Mula Dengan MCP

Selamat datang ke langkah pertama anda dengan Model Context Protocol (MCP)! Sama ada anda baru dengan MCP atau ingin mendalami pemahaman anda, panduan ini akan membawa anda melalui proses penyediaan dan pembangunan penting. Anda akan mengetahui bagaimana MCP membolehkan integrasi lancar antara model AI dan aplikasi, dan belajar cara menyediakan persekitaran anda dengan cepat untuk membina dan menguji penyelesaian yang dipacu oleh MCP.

TLDR; Jika anda membina aplikasi AI, anda tahu bahawa anda boleh menambah alat dan sumber lain ke dalam LLM (model bahasa besar) anda, untuk menjadikan LLM itu lebih berpengetahuan. Namun jika anda meletakkan alat dan sumber tersebut di atas pelayan, keupayaan aplikasi dan pelayan boleh digunakan oleh mana-mana pelanggan dengan/tanpa LLM.

Gambaran Keseluruhan

Pelajaran ini memberikan panduan praktikal tentang penyediaan persekitaran MCP dan membina aplikasi MCP pertama anda. Anda akan belajar cara menyediakan alat dan rangka kerja yang diperlukan, membina pelayan MCP asas, mencipta aplikasi hos, dan menguji pelaksanaan anda.

Model Context Protocol (MCP) adalah protokol terbuka yang menstandardkan bagaimana aplikasi menyediakan konteks kepada LLM. Anggap MCP seperti port USB-C untuk aplikasi AI - ia menyediakan cara standard untuk menyambungkan model AI kepada pelbagai sumber data dan alat.

Objektif Pembelajaran

Menjelang akhir pelajaran ini, anda akan dapat:

Menyediakan persekitaran pembangunan untuk MCP dalam C#, Java, Python, TypeScript, dan Rust
Membina dan menyebarkan pelayan MCP asas dengan ciri tersuai (sumber, prompt, dan alat)
Mencipta aplikasi hos yang menyambung ke pelayan MCP
Menguji dan menyahpepijat pelaksanaan MCP

Menyediakan Persekitaran MCP Anda

Sebelum anda mula bekerja dengan MCP, penting untuk menyediakan persekitaran pembangunan anda dan memahami aliran kerja asas. Bahagian ini akan membimbing anda melalui langkah-langkah penyediaan awal untuk memastikan permulaan lancar dengan MCP.

Prasyarat

Sebelum menerokai pembangunan MCP, pastikan anda mempunyai:

Persekitaran Pembangunan: Untuk bahasa pilihan anda (C#, Java, Python, TypeScript, atau Rust)
IDE/Penyunting: Visual Studio, Visual Studio Code, IntelliJ, Eclipse, PyCharm, atau mana-mana penyunting kod moden
Pengurus Pakej: NuGet, Maven/Gradle, pip, npm/yarn, atau Cargo
Kunci API: Untuk sebarang perkhidmatan AI yang anda rancang gunakan dalam aplikasi hos anda

Struktur Pelayan MCP Asas

Pelayan MCP biasanya merangkumi:

Konfigurasi Pelayan: Menyediakan port, pengesahan, dan tetapan lain
Sumber: Data dan konteks yang disediakan kepada LLM
Alat: Fungsi yang boleh dipanggil oleh model
Prompt: Templat untuk menghasilkan atau menyusun teks

Berikut adalah contoh mudah dalam TypeScript:

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Cipta pelayan MCP
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// Tambah alat tambahan
server.tool("add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// Tambah sumber ucapan dinamik
server.resource(
  "file",
  // Parameter 'senarai' mengawal bagaimana sumber menyenaraikan fail yang tersedia. Menetapkannya kepada tidak ditakrifkan mematikan penyenaraian untuk sumber ini.
  new ResourceTemplate("file://{path}", { list: undefined }),
  async (uri, { path }) => ({
    contents: [{
      uri: uri.href,
      text: `File, ${path}!`
    }]
  })
);

// Tambah sumber fail yang membaca kandungan fail
server.resource(
  "file",
  new ResourceTemplate("file://{path}", { list: undefined }),
  async (uri, { path }) => {
    let text;
    try {
      text = await fs.readFile(path, "utf8");
    } catch (err) {
      text = `Error reading file: ${err.message}`;
    }
    return {
      contents: [{
        uri: uri.href,
        text
      }]
    };
  }
);

server.prompt(
  "review-code",
  { code: z.string() },
  ({ code }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Please review this code:\n\n${code}`
      }
    }]
  })
);

// Mula menerima mesej di stdin dan menghantar mesej di stdout
const transport = new StdioServerTransport();
await server.connect(transport);

Dalam kod sebelumnya kami:

Mengimport kelas yang diperlukan daripada SDK MCP TypeScript.
Mencipta dan mengkonfigurasi instans pelayan MCP baru.
Mendaftarkan alat tersuai (calculator) dengan fungsi pengendali.
Memulakan pelayan untuk mendengar permintaan MCP masuk.

Ujian dan Penyahpepijatan

Sebelum anda mula menguji pelayan MCP anda, penting untuk memahami alat yang tersedia dan amalan terbaik untuk penyahpepijatan. Ujian yang berkesan memastikan pelayan anda berfungsi seperti yang dijangkakan dan membantu anda mengenal pasti serta menyelesaikan masalah dengan cepat. Bahagian berikut menggariskan pendekatan yang disyorkan untuk mengesahkan pelaksanaan MCP anda.

MCP menyediakan alat untuk membantu anda menguji dan menyahpepijat pelayan anda:

Alat Inspector, antara muka grafik ini membolehkan anda menyambung ke pelayan anda dan menguji alat, prompt dan sumber anda.
curl, anda juga boleh menyambung ke pelayan anda menggunakan alat baris arahan seperti curl atau klien lain yang boleh mencipta dan menjalankan perintah HTTP.

Menggunakan MCP Inspector

MCP Inspector adalah alat ujian visual yang membantu anda:

Menemui Keupayaan Pelayan: Mengesan sumber, alat, dan prompt yang tersedia secara automatik
Uji Pelaksanaan Alat: Cuba parameter berbeza dan lihat respons secara masa nyata
Lihat Metadata Pelayan: Periksa maklumat pelayan, skema, dan konfigurasi

# Contoh TypeScript, memasang dan menjalankan MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Apabila anda menjalankan arahan di atas, MCP Inspector akan melancarkan antara muka web tempatan dalam pelayar anda. Anda boleh menjangkakan papan pemuka yang memaparkan pelayan MCP yang telah didaftarkan, alat, sumber, dan prompt yang tersedia. Antara muka membolehkan anda menguji pelaksanaan alat secara interaktif, memeriksa metadata pelayan, dan melihat respons masa nyata, menjadikan ia lebih mudah untuk mengesahkan dan menyahpepijat pelaksanaan pelayan MCP anda.

Berikut adalah tangkapan skrin bagaimana rupa antara mukanya:

Isu dan Penyelesaian Penyediaan Biasa

Isu	Penyelesaian Mungkin
Sambungan ditolak	Semak jika pelayan sedang berjalan dan port adalah betul
Ralat pelaksanaan alat	Semak semula pengesahan parameter dan penanganan ralat
Kegagalan pengesahan	Sahkan kunci API dan kebenaran
Ralat pengesahan skema	Pastikan parameter sepadan dengan skema yang ditakrifkan
Pelayan tidak bermula	Semak konflik port atau kebergantungan yang hilang
Ralat CORS	Konfigurasikan header CORS yang betul untuk permintaan rentas asal
Isu pengesahan	Sahkan kesahihan token dan kebenaran

Pembangunan Tempatan

Untuk pembangunan dan ujian tempatan, anda boleh menjalankan pelayan MCP terus di mesin anda:

Mulakan proses pelayan: Jalankan aplikasi pelayan MCP anda
Konfigurasi rangkaian: Pastikan pelayan boleh diakses pada port yang dijangkakan
Sambungkan klien: Gunakan URL sambungan tempatan seperti http://localhost:3000

# Contoh: Menjalankan pelayan MCP TypeScript secara tempatan
npm run start
# Pelayan berjalan di http://localhost:3000

Membina Pelayan MCP Pertama Anda

Kita telah membincangkan Konsep Teras dalam pelajaran sebelum ini, kini tiba masanya menggunakan pengetahuan itu.

Apa yang boleh dilakukan oleh pelayan

Sebelum kita mula menulis kod, mari kita ingat apa yang boleh dilakukan oleh pelayan:

Pelayan MCP boleh contohnya:

Mengakses fail dan pangkalan data tempatan
Menyambung ke API jauh
Melakukan pengiraan
Mengintegrasi dengan alat dan perkhidmatan lain
Menyediakan antara muka pengguna untuk interaksi

Bagus, sekarang kita tahu apa yang boleh kita lakukan untuknya, mari kita mulakan pengekodan.

Latihan: Mencipta pelayan

Untuk mencipta pelayan, anda perlu mengikuti langkah berikut:

Pasang SDK MCP.
Cipta projek dan susun struktur projek.
Tulis kod pelayan.
Uji pelayan.

-1- Cipta projek

TypeScript

# Cipta direktori projek dan inisialisasi projek npm
mkdir calculator-server
cd calculator-server
npm init -y

Python

# Buat direktori projek
mkdir calculator-server
cd calculator-server
# Buka folder dalam Visual Studio Code - Langkau ini jika anda menggunakan IDE lain
code .

.NET

dotnet new console -n McpCalculatorServer
cd McpCalculatorServer

Java

Untuk Java, cipta projek Spring Boot:

curl https://start.spring.io/starter.zip \
  -d dependencies=web \
  -d javaVersion=21 \
  -d type=maven-project \
  -d groupId=com.example \
  -d artifactId=calculator-server \
  -d name=McpServer \
  -d packageName=com.microsoft.mcp.sample.server \
  -o calculator-server.zip

Ekstrak fail zip:

unzip calculator-server.zip -d calculator-server
cd calculator-server
# pilihan untuk mengeluarkan ujian yang tidak digunakan
rm -rf src/test/java

Tambah konfigurasi lengkap berikut ke dalam fail pom.xml anda:

<?xml version="1.0" encoding="UTF-8"?>
<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <!-- Spring Boot parent for dependency management -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.0</version>
        <relativePath />
    </parent>

    <!-- Project coordinates -->
    <groupId>com.example</groupId>
    <artifactId>calculator-server</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>Calculator Server</name>
    <description>Basic calculator MCP service for beginners</description>

    <!-- Properties -->
    <properties>
        <java.version>21</java.version>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
    </properties>

    <!-- Spring AI BOM for version management -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>1.0.0-SNAPSHOT</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- Dependencies -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-test</artifactId>
         <scope>test</scope>
      </dependency>
    </dependencies>

    <!-- Build configuration -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <release>21</release>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <!-- Repositories for Spring AI snapshots -->
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <releases>
                <enabled>false</enabled>
            </releases>
        </repository>
    </repositories>
</project>

Rust

mkdir calculator-server
cd calculator-server
cargo init

-2- Tambah kebergantungan

Sekarang projek anda sudah dicipta, mari tambah kebergantungan pula:

TypeScript

# Jika belum dipasang, pasang TypeScript secara global
npm install typescript -g

# Pasang MCP SDK dan Zod untuk pengesahan skema
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

Python

# Cipta persekitaran maya dan pasang kebergantungan
python -m venv venv
venv\Scripts\activate
pip install "mcp[cli]"

Java

cd calculator-server
./mvnw clean install -DskipTests

Rust

cargo add rmcp --features server,transport-io
cargo add serde
cargo add tokio --features rt-multi-thread

-3- Cipta fail projek

TypeScript

Buka fail package.json dan gantikan kandungan dengan yang berikut untuk memastikan anda boleh bina dan jalankan pelayan:

{
  "name": "calculator-server",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "npm run build && node ./build/index.js",
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "A simple calculator server using Model Context Protocol",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.16.0",
    "zod": "^3.25.76"
  },
  "devDependencies": {
    "@types/node": "^24.0.14",
    "typescript": "^5.8.3"
  }
}

Cipta tsconfig.json dengan kandungan berikut:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Cipta direktori untuk kod sumber anda:

mkdir src
touch src/index.ts

Python

Cipta fail server.py

touch server.py

.NET

Pasang pakej NuGet yang diperlukan:

dotnet add package ModelContextProtocol --prerelease
dotnet add package Microsoft.Extensions.Hosting

Java

Untuk projek Java Spring Boot, struktur projek dicipta secara automatik.

Rust

Untuk Rust, fail src/main.rs dicipta secara lalai apabila anda jalankan cargo init. Buka fail dan padamkan kod lalai.

-4- Tulis kod pelayan

TypeScript

Cipta fail index.ts dan tambah kod berikut:

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
// Cipta pelayan MCP
const server = new McpServer({
  name: "Calculator MCP Server",
  version: "1.0.0"
});

Sekarang anda mempunyai pelayan, tetapi ia tidak melakukan banyak, mari betulkan itu.

Python

# server.py
from mcp.server.fastmcp import FastMCP

# Cipta pelayan MCP
mcp = FastMCP("Demo")

.NET

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
    // Configure all logs to go to stderr
    consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();
await builder.Build().RunAsync();

// add features

Java

Untuk Java, cipta komponen teras pelayan. Pertama, ubah kelas aplikasi utama:

src/main/java/com/microsoft/mcp/sample/server/McpServerApplication.java:

package com.microsoft.mcp.sample.server;

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import com.microsoft.mcp.sample.server.service.CalculatorService;

@SpringBootApplication
public class McpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
    
    @Bean
    public ToolCallbackProvider calculatorTools(CalculatorService calculator) {
        return MethodToolCallbackProvider.builder().toolObjects(calculator).build();
    }
}

Cipta perkhidmatan kalkulator src/main/java/com/microsoft/mcp/sample/server/service/CalculatorService.java:

package com.microsoft.mcp.sample.server.service;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;

/**
 * Service for basic calculator operations.
 * This service provides simple calculator functionality through MCP.
 */
@Service
public class CalculatorService {

    /**
     * Add two numbers
     * @param a The first number
     * @param b The second number
     * @return The sum of the two numbers
     */
    @Tool(description = "Add two numbers together")
    public String add(double a, double b) {
        double result = a + b;
        return formatResult(a, "+", b, result);
    }

    /**
     * Subtract one number from another
     * @param a The number to subtract from
     * @param b The number to subtract
     * @return The result of the subtraction
     */
    @Tool(description = "Subtract the second number from the first number")
    public String subtract(double a, double b) {
        double result = a - b;
        return formatResult(a, "-", b, result);
    }

    /**
     * Multiply two numbers
     * @param a The first number
     * @param b The second number
     * @return The product of the two numbers
     */
    @Tool(description = "Multiply two numbers together")
    public String multiply(double a, double b) {
        double result = a * b;
        return formatResult(a, "*", b, result);
    }

    /**
     * Divide one number by another
     * @param a The numerator
     * @param b The denominator
     * @return The result of the division
     */
    @Tool(description = "Divide the first number by the second number")
    public String divide(double a, double b) {
        if (b == 0) {
            return "Error: Cannot divide by zero";
        }
        double result = a / b;
        return formatResult(a, "/", b, result);
    }

    /**
     * Calculate the power of a number
     * @param base The base number
     * @param exponent The exponent
     * @return The result of raising the base to the exponent
     */
    @Tool(description = "Calculate the power of a number (base raised to an exponent)")
    public String power(double base, double exponent) {
        double result = Math.pow(base, exponent);
        return formatResult(base, "^", exponent, result);
    }

    /**
     * Calculate the square root of a number
     * @param number The number to find the square root of
     * @return The square root of the number
     */
    @Tool(description = "Calculate the square root of a number")
    public String squareRoot(double number) {
        if (number < 0) {
            return "Error: Cannot calculate square root of a negative number";
        }
        double result = Math.sqrt(number);
        return String.format("√%.2f = %.2f", number, result);
    }

    /**
     * Calculate the modulus (remainder) of division
     * @param a The dividend
     * @param b The divisor
     * @return The remainder of the division
     */
    @Tool(description = "Calculate the remainder when one number is divided by another")
    public String modulus(double a, double b) {
        if (b == 0) {
            return "Error: Cannot divide by zero";
        }
        double result = a % b;
        return formatResult(a, "%", b, result);
    }

    /**
     * Calculate the absolute value of a number
     * @param number The number to find the absolute value of
     * @return The absolute value of the number
     */
    @Tool(description = "Calculate the absolute value of a number")
    public String absolute(double number) {
        double result = Math.abs(number);
        return String.format("|%.2f| = %.2f", number, result);
    }

    /**
     * Get help about available calculator operations
     * @return Information about available operations
     */
    @Tool(description = "Get help about available calculator operations")
    public String help() {
        return "Basic Calculator MCP Service\n\n" +
               "Available operations:\n" +
               "1. add(a, b) - Adds two numbers\n" +
               "2. subtract(a, b) - Subtracts the second number from the first\n" +
               "3. multiply(a, b) - Multiplies two numbers\n" +
               "4. divide(a, b) - Divides the first number by the second\n" +
               "5. power(base, exponent) - Raises a number to a power\n" +
               "6. squareRoot(number) - Calculates the square root\n" + 
               "7. modulus(a, b) - Calculates the remainder of division\n" +
               "8. absolute(number) - Calculates the absolute value\n\n" +
               "Example usage: add(5, 3) will return 5 + 3 = 8";
    }

    /**
     * Format the result of a calculation
     */
    private String formatResult(double a, String operator, double b, double result) {
        return String.format("%.2f %s %.2f = %.2f", a, operator, b, result);
    }
}

Komponen pilihan untuk perkhidmatan sedia produksi:

Cipta konfigurasi permulaan src/main/java/com/microsoft/mcp/sample/server/config/StartupConfig.java:

package com.microsoft.mcp.sample.server.config;

import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class StartupConfig {
    
    @Bean
    public CommandLineRunner startupInfo() {
        return args -> {
            System.out.println("\n" + "=".repeat(60));
            System.out.println("Calculator MCP Server is starting...");
            System.out.println("SSE endpoint: http://localhost:8080/sse");
            System.out.println("Health check: http://localhost:8080/actuator/health");
            System.out.println("=".repeat(60) + "\n");
        };
    }
}

Cipta pengawal kesihatan src/main/java/com/microsoft/mcp/sample/server/controller/HealthController.java:

package com.microsoft.mcp.sample.server.controller;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

@RestController
public class HealthController {
    
    @GetMapping("/health")
    public ResponseEntity<Map<String, Object>> healthCheck() {
        Map<String, Object> response = new HashMap<>();
        response.put("status", "UP");
        response.put("timestamp", LocalDateTime.now().toString());
        response.put("service", "Calculator MCP Server");
        return ResponseEntity.ok(response);
    }
}

Cipta pengendali pengecualian src/main/java/com/microsoft/mcp/sample/server/exception/GlobalExceptionHandler.java:

package com.microsoft.mcp.sample.server.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<ErrorResponse> handleIllegalArgumentException(IllegalArgumentException ex) {
        ErrorResponse error = new ErrorResponse(
            "Invalid_Input", 
            "Invalid input parameter: " + ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
    }

    public static class ErrorResponse {
        private String code;
        private String message;

        public ErrorResponse(String code, String message) {
            this.code = code;
            this.message = message;
        }

        // Pengambil
        public String getCode() { return code; }
        public String getMessage() { return message; }
    }
}

Cipta sepanduk tersuai src/main/resources/banner.txt:

_____      _            _       _             
 / ____|    | |          | |     | |            
| |     __ _| | ___ _   _| | __ _| |_ ___  _ __ 
| |    / _` | |/ __| | | | |/ _` | __/ _ \| '__|
| |___| (_| | | (__| |_| | | (_| | || (_) | |   
 \_____\__,_|_|\___|\__,_|_|\__,_|\__\___/|_|   
                                                
Calculator MCP Server v1.0
Spring Boot MCP Application

Rust

Tambah kod berikut ke atas fail src/main.rs. Ini mengimport perpustakaan dan modul yang diperlukan untuk pelayan MCP anda.

use rmcp::{
    handler::server::{router::tool::ToolRouter, tool::Parameters},
    model::{ServerCapabilities, ServerInfo},
    schemars, tool, tool_handler, tool_router,
    transport::stdio,
    ServerHandler, ServiceExt,
};
use std::error::Error;

Pelayan kalkulator akan menjadi mudah yang boleh menambah dua nombor bersama. Mari cipta struct untuk mewakili permintaan kalkulator.

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct CalculatorRequest {
    pub a: f64,
    pub b: f64,
}

Seterusnya, cipta struct untuk mewakili pelayan kalkulator. Struct ini akan memegang router alat, yang digunakan untuk mendaftarkan alat.

#[derive(Debug, Clone)]
pub struct Calculator {
    tool_router: ToolRouter<Self>,
}

Kini, kita boleh melaksanakan struct Calculator untuk mencipta instans baru pelayan dan melaksanakan pengendali pelayan untuk menyediakan maklumat pelayan.

#[tool_router]
impl Calculator {
    pub fn new() -> Self {
        Self {
            tool_router: Self::tool_router(),
        }
    }
}

#[tool_handler]
impl ServerHandler for Calculator {
    fn get_info(&self) -> ServerInfo {
        ServerInfo {
            instructions: Some("A simple calculator tool".into()),
            capabilities: ServerCapabilities::builder().enable_tools().build(),
            ..Default::default()
        }
    }
}

Akhir sekali, kita perlu melaksanakan fungsi utama untuk memulakan pelayan. Fungsi ini akan mencipta instans struct Calculator dan menyajikannya melalui input/output standard.

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let service = Calculator::new().serve(stdio()).await?;
    service.waiting().await?;
    Ok(())
}

Pelayan kini disediakan untuk menyediakan maklumat asas tentang dirinya. Seterusnya, kita akan menambah alat untuk melakukan penambahan.

-5- Menambah alat dan sumber

Tambah alat dan sumber dengan menambah kod berikut:

TypeScript

server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  async (uri, { name }) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

Alat anda mengambil parameter a dan b dan menjalankan fungsi yang menghasilkan respons dalam bentuk:

{
  contents: [{
    type: "text", content: "some content"
  }]
}

Sumber anda diakses melalui rentetan "greeting" dan mengambil parameter name serta menghasilkan respons yang serupa dengan alat:

{
  uri: "<href>",
  text: "a text"
}

Python

# Tambah alat penambahan
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b


# Tambah sumber sapaan dinamik
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

Dalam kod sebelumnya kami telah:

Mendefinisikan alat add yang mengambil parameter a dan b, kedua-duanya integer.
Mencipta sumber yang dipanggil greeting yang mengambil parameter name.

.NET

Tambah ini ke fail Program.cs anda:

[McpServerToolType]
public static class CalculatorTool
{
    [McpServerTool, Description("Adds two numbers")]
    public static string Add(int a, int b) => $"Sum {a + b}";
}

Java

Alat telahpun dicipta dalam langkah sebelumnya.

Rust

Tambah alat baru di dalam blok impl Calculator:

#[tool(description = "Adds a and b")]
async fn add(
    &self,
    Parameters(CalculatorRequest { a, b }): Parameters<CalculatorRequest>,
) -> String {
    (a + b).to_string()
}

-6- Kod akhir

Mari kita tambah kod terakhir yang diperlukan supaya pelayan boleh bermula:

TypeScript

// Mula menerima mesej pada stdin dan menghantar mesej pada stdout
const transport = new StdioServerTransport();
await server.connect(transport);

Berikut adalah kod penuh:

// index.ts
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Buat pelayan MCP
const server = new McpServer({
  name: "Calculator MCP Server",
  version: "1.0.0"
});

// Tambah alat tambahan
server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// Tambah sumber ucapan dinamik
server.resource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  async (uri, { name }) => ({
    contents: [{
      uri: uri.href,
      text: `Hello, ${name}!`
    }]
  })
);

// Mula menerima mesej di stdin dan menghantar mesej di stdout
const transport = new StdioServerTransport();
server.connect(transport);

Python

# server.py
from mcp.server.fastmcp import FastMCP

# Cipta pelayan MCP
mcp = FastMCP("Demo")


# Tambah alat penambahan
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b


# Tambah sumber ucapan selamat dinamik
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

# Blok pelaksanaan utama - ini diperlukan untuk menjalankan pelayan
if __name__ == "__main__":
    mcp.run()

.NET

Cipta fail Program.cs dengan kandungan berikut:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
    // Configure all logs to go to stderr
    consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();
await builder.Build().RunAsync();

[McpServerToolType]
public static class CalculatorTool
{
    [McpServerTool, Description("Adds two numbers")]
    public static string Add(int a, int b) => $"Sum {a + b}";
}

Java

Kelas aplikasi utama lengkap anda harus kelihatan seperti ini:

// McpServerApplication.java
package com.microsoft.mcp.sample.server;

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import com.microsoft.mcp.sample.server.service.CalculatorService;

@SpringBootApplication
public class McpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
    
    @Bean
    public ToolCallbackProvider calculatorTools(CalculatorService calculator) {
        return MethodToolCallbackProvider.builder().toolObjects(calculator).build();
    }
}

Rust

Kod akhir untuk pelayan Rust harus kelihatan seperti ini:

use rmcp::{
    ServerHandler, ServiceExt,
    handler::server::{router::tool::ToolRouter, tool::Parameters},
    model::{ServerCapabilities, ServerInfo},
    schemars, tool, tool_handler, tool_router,
    transport::stdio,
};
use std::error::Error;

#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct CalculatorRequest {
    pub a: f64,
    pub b: f64,
}

#[derive(Debug, Clone)]
pub struct Calculator {
    tool_router: ToolRouter<Self>,
}

#[tool_router]
impl Calculator {
    pub fn new() -> Self {
        Self {
            tool_router: Self::tool_router(),
        }
    }
    
    #[tool(description = "Adds a and b")]
    async fn add(
        &self,
        Parameters(CalculatorRequest { a, b }): Parameters<CalculatorRequest>,
    ) -> String {
        (a + b).to_string()
    }
}

#[tool_handler]
impl ServerHandler for Calculator {
    fn get_info(&self) -> ServerInfo {
        ServerInfo {
            instructions: Some("A simple calculator tool".into()),
            capabilities: ServerCapabilities::builder().enable_tools().build(),
            ..Default::default()
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let service = Calculator::new().serve(stdio()).await?;
    service.waiting().await?;
    Ok(())
}

-7- Uji pelayan

Mulakan pelayan dengan arahan berikut:

TypeScript

npm run build

Python

mcp run server.py

Untuk menggunakan MCP Inspector, gunakan mcp dev server.py yang secara automatik melancarkan Inspector dan menyediakan token sesi proksi yang diperlukan. Jika menggunakan mcp run server.py, anda perlu memulakan Inspector secara manual dan konfigurasi sambungan.

.NET

Pastikan anda berada dalam direktori projek anda:

cd McpCalculatorServer
dotnet run

Java

./mvnw clean install -DskipTests
java -jar target/calculator-server-0.0.1-SNAPSHOT.jar

Rust

Jalankan arahan berikut untuk memformat dan menjalankan pelayan:

cargo fmt
cargo run

-8- Jalankan menggunakan inspector

Inspector adalah alat hebat yang boleh memulakan pelayan anda dan membolehkan anda berinteraksi dengannya supaya anda boleh menguji bahawa ia berfungsi. Mari mulakan:

Note

ia mungkin kelihatan berbeza dalam medan "command" kerana ia mengandungi arahan untuk menjalankan pelayan dengan runtime khusus anda/

TypeScript

npx @modelcontextprotocol/inspector node build/index.js

atau tambahkan ia ke dalam package.json anda seperti berikut: "inspector": "npx @modelcontextprotocol/inspector node build/index.js" dan kemudian jalankan npm run inspector

Python

Python membalut alat Node.js yang dipanggil inspector. Ia boleh dipanggil alat tersebut seperti berikut:

mcp dev server.py

Walau bagaimanapun, ia tidak melaksanakan semua kaedah yang tersedia pada alat itu jadi anda disarankan menjalankan alat Node.js secara langsung seperti di bawah:

npx @modelcontextprotocol/inspector mcp run server.py

Jika anda menggunakan alat atau IDE yang membolehkan anda mengkonfigurasi arahan dan argumen untuk menjalankan skrip, pastikan untuk menetapkan python dalam medan Command dan server.py sebagai Arguments. Ini memastikan skrip berjalan dengan betul.

.NET

Pastikan anda berada dalam direktori projek anda:

cd McpCalculatorServer
npx @modelcontextprotocol/inspector dotnet run

Java

Pastikan pelayan kalkulator anda sedang berjalan
Kemudian jalankan pemeriksa:

npx @modelcontextprotocol/inspector

Dalam antara muka web pemeriksa:

Pilih "SSE" sebagai jenis pengangkutan
Tetapkan URL kepada: http://localhost:8080/sse
Klik "Connect"

Anda kini bersambung ke pelayan
Bahagian ujian pelayan Java kini selesai

Bahagian seterusnya adalah mengenai berinteraksi dengan pelayan.

Anda sepatutnya melihat antara muka pengguna berikut:

Sambungkan ke pelayan dengan memilih butang Connect
Setelah anda bersambung ke pelayan, anda sepatutnya melihat yang berikut:

Pilih "Tools" dan "listTools", anda sepatutnya melihat "Add" muncul, pilih "Add" dan isikan nilai parameter.

Anda sepatutnya melihat respons berikut, iaitu keputusan daripada alat "add":

Tahniah, anda telah berjaya mencipta dan menjalankan pelayan pertama anda!

Rust

Untuk menjalankan pelayan Rust dengan MCP Inspector CLI, gunakan perintah berikut:

npx @modelcontextprotocol/inspector cargo run --cli --method tools/call --tool-name add --tool-arg a=1 b=2

SDK Rasmi

MCP menyediakan SDK rasmi untuk pelbagai bahasa:

C# SDK - Diselenggara bersama Microsoft
Java SDK - Diselenggara bersama Spring AI
TypeScript SDK - Pelaksanaan rasmi TypeScript
Python SDK - Pelaksanaan rasmi Python
Kotlin SDK - Pelaksanaan rasmi Kotlin
Swift SDK - Diselenggara bersama Loopwork AI
Rust SDK - Pelaksanaan rasmi Rust

Pengajaran Utama

Menyediakan persekitaran pembangunan MCP mudah dengan SDK khusus bahasa
Membangun pelayan MCP melibatkan penciptaan dan pendaftaran alat dengan skema jelas
Ujian dan penyahpepijatan adalah penting untuk pelaksanaan MCP yang boleh dipercayai

Contoh

Tugasan

Cipta pelayan MCP ringkas dengan alat pilihan anda:

Laksanakan alat dalam bahasa pilihan anda (.NET, Java, Python, TypeScript, atau Rust).
Definisikan parameter input dan nilai pulangan.
Jalankan alat pemeriksa untuk memastikan pelayan berfungsi seperti yang diinginkan.
Uji pelaksanaan dengan pelbagai input.

Penyelesaian

Sumber Tambahan

Apa seterusnya

Seterusnya: Memulakan dengan Klien MCP

Penafian:
Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI Co-op Translator. Walaupun kami berusaha untuk ketepatan, sila ambil perhatian bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat kritikal, terjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau penafsiran salah yang timbul daripada penggunaan terjemahan ini.

40 KiB Raw Permalink Blame History

Mula Dengan MCP

Gambaran Keseluruhan

Objektif Pembelajaran

Menyediakan Persekitaran MCP Anda

Prasyarat

Struktur Pelayan MCP Asas

Ujian dan Penyahpepijatan

Menggunakan MCP Inspector

Isu dan Penyelesaian Penyediaan Biasa

Pembangunan Tempatan

Membina Pelayan MCP Pertama Anda

Apa yang boleh dilakukan oleh pelayan

Latihan: Mencipta pelayan

-1- Cipta projek

TypeScript

Python

.NET

Java

Rust

-2- Tambah kebergantungan

TypeScript

Python

Java

Rust

-3- Cipta fail projek

TypeScript

Python

.NET

Java

Rust

-4- Tulis kod pelayan

TypeScript

Python

.NET

Java

Rust

-5- Menambah alat dan sumber

TypeScript

Python

.NET

Java

Rust

-6- Kod akhir

TypeScript

Python

.NET

Java

Rust

-7- Uji pelayan

TypeScript

Python

.NET

Java

Rust

-8- Jalankan menggunakan inspector

TypeScript

Python

.NET

Java

Rust

SDK Rasmi

Pengajaran Utama

Contoh

Tugasan

Penyelesaian

Sumber Tambahan

Apa seterusnya

40 KiB

Raw Permalink Blame History