MCP Server Howto

🚀 MCP 協議 Java SDK 全面指南

MCP（Model Context Protocol）協議是用於連接和管理模型上下文的開放標準，在人工智能和分佈式系統開發中應用廣泛。本指南將詳細介紹如何使用 MCP 協議的 Java SDK 進行開發。

🚀 快速開始

創建客戶端

使用 McpClient 工廠創建一個 MCP 客戶端：

import io.modelcontextprotocol.client.McpClient;

public class McpExample {
    public static void main(String[] args) {
        // 創建默認的 MCP 客戶端實例
        try (var client = McpClient.createDefault()) {
            // 使用客戶端進行操作
            System.out.println("MCP 客戶端已創建");
        }
    }
}

創建服務器

使用 McpServer 工廠創建一個 MCP 服務器：

import io.modelcontextprotocol.server.McpServer;

public class McpExample {
    public static void main(String[] args) {
        // 創建默認的 MCP 服務器實例
        try (var server = McpServer.createDefault()) {
            // 使用服務器進行操作
            System.out.println("MCP 服務器已創建");
        }
    }
}

✨ 主要特性

• 開放標準：MCP 協議是開放標準，便於在不同系統中集成和使用。
• 請求 - 響應模式：所有 MCP 操作都基於請求 - 響應模式，保證數據交互的有序性。
• 資源與工具管理：支持資源模板動態生成資源內容，以及自定義工具的定義和執行。

📦 安裝指南

下載 SDK

訪問 MCP 官方網站 下載適用於您項目的 MCP Java SDK 版本。

環境配置

1. 添加依賴
   在您的項目構建文件中（如 pom.xml 或 build.gradle）添加 MCP SDK 依賴：

   <dependency>
       <groupId>io.modelcontextprotocol</groupId>
       <artifactId>mcp-java-sdk</artifactId>
       <version>${mcp.sdk.version}</version>
   </dependency>
   

2. 配置環境變量
   確保 JDK 和 MCP SDK 已正確安裝，並將 MCP 工具添加到系統路徑中。

💻 使用示例

基礎用法

客戶端與服務端交互

所有 MCP 操作都基於請求 - 響應模式。以下是一個簡單的交互示例：

// 發起請求
var request = createRequest();
client.sendRequest(request);

// 處理響應
client.receiveResponse().thenAccept(response -> {
    System.out.println("收到響應: " + response.toString());
});

高級用法

資源與工具管理

資源模板

使用資源模板動態生成資源內容：

import io.modelcontextprotocol.schema.McpSchema;

public class McpExample {
    public static void main(String[] args) {
        // 創建一個簡單的資源模板
        var resourceTemplate = new Template() {
            @Override
            public String getResourceId() {
                return "example_resource";
            }

            @Override
            public Map<String, Object> getParameters() {
                return Collections.emptyMap();
            }
        };

        // 應用資源模板生成內容
        McpSchema.applyTemplate(resourceTemplate);
    }
}

工具執行

定義並執行自定義工具：

import io.modelcontextprotocol.tool.McpTool;

public class McpExample {
    public static void main(String[] args) {
        // 定義一個簡單的工具
        var tool = new Tool() {
            @Override
            public String getName() {
                return "example_tool";
            }

            @Override
            public void execute(List<String> arguments, Callback<String> callback) {
                callback.onResult("執行完成: " + arguments);
            }
        };

        // 執行工具並獲取結果
        var result = McpTool.execute(tool, List.of("arg1", "arg2"));
        System.out.println(result);
    }
}

📚 詳細文檔

核心概念

客戶端與服務端

• 客戶端：負責發起請求和接收響應。
• 服務端：負責處理客戶端的請求並返回響應。

請求與響應

所有 MCP 操作都基於請求 - 響應模式，確保數據在客戶端和服務端之間的有序交互。

🔧 技術細節

MCP 協議 Java SDK 基於開放標準 MCP 協議，採用請求 - 響應模式進行數據交互。客戶端通過 McpClient 發起請求，服務端通過 McpServer 處理請求。在資源與工具管理方面，支持使用資源模板動態生成資源內容，以及自定義工具的定義和執行，提高了系統的靈活性和可擴展性。

📄 最佳實踐

一般規範

1. 使用 BOM - 總是使用 MCP BOM 確保所有組件的兼容版本。
2. 關閉連接 - 處理完畢後，總是關閉客戶端和服務器實例。
3. 處理錯誤 - 實現所有 MCP 操作的適當錯誤處理。
4. 驗證輸入 - 在處理之前驗證所有輸入數據。
5. 選擇合適的傳輸機制 - 根據使用場景選擇適當的傳輸方式。

客戶端側

1. 重用客戶端 - 創建一個單獨的客戶端實例並多次使用。