使用说明

项目简介

'mcp-declarative-java-sdk' 是一个Java SDK，旨在简化Model Context Protocol (MCP) 服务器的开发。它通过注解的方式，让开发者能够更方便地声明和注册 MCP 服务器的资源 (Resources) 和工具 (Tools)，从而快速构建符合 MCP 协议的应用后端。

主要功能点

声明式资源定义: 使用 '@McpResources' 和 '@McpResource' 注解，将 Java 类和方法声明为 MCP 资源，支持自定义 URI、名称、描述、MIME 类型、角色和优先级。
声明式工具定义: 使用 '@McpTools' 和 '@McpTool' 注解，将 Java 类和方法声明为 MCP 工具，支持定义工具名称、描述和参数（通过 '@McpToolParam' 注解）。
支持 Stdio 和 SSE 传输协议: 内置支持标准输入输出流 (Stdio) 和服务器发送事件 (SSE) 传输协议，方便与 MCP 客户端进行通信。
自动扫描和注册: 通过 '@McpComponentScan' 注解，自动扫描指定包下的类，注册带有 '@McpResources' 和 '@McpTools' 注解的类及其中的资源和工具方法。
基于 Jetty 的 HTTP 服务器: 对于 SSE 传输协议，内置基于 Jetty 的 HTTP 服务器，简化部署和运行。

安装步骤

由于这是一个 SDK，你需要将其作为依赖添加到你的 Java 项目中。如果你使用 Maven，可以在 'pom.xml' 文件中添加以下依赖 (请根据实际仓库发布情况修改版本号)：

<dependency>
    <groupId>com.github.codeboyzhou</groupId>
    <artifactId>mcp-declarative-java-sdk</artifactId>
    <version>latest-version</version>  <!-- 请替换为实际版本号 -->
</dependency>

如果你使用 Gradle，请在 'build.gradle' 文件中添加：

dependencies {
    implementation 'com.github.codeboyzhou:mcp-declarative-java-sdk:latest-version' // 请替换为实际版本号
}

服务器配置 (MCP 客户端配置)

Stdio 服务器配置

对于 Stdio 传输协议，MCP 客户端通常需要配置服务器的启动命令 (command) 和参数 (args)。假设你的 Java 应用程序打包成了一个可执行的 JAR 文件 'your-application.jar'，并且你的主类使用了 'McpServers' SDK 来启动 Stdio MCP 服务器。

{
  "serverName": "my-mcp-stdio-server",
  "command": "java",
  "args": ["-jar", "your-application.jar"]
}

SSE 服务器配置

对于 SSE 传输协议，除了启动命令，还需要配置服务器的地址 (baseURL)。假设你的 Java 应用程序使用 SDK 启动了 SSE MCP 服务器，并监听在默认端口 8080。

{
  "serverName": "my-mcp-sse-server",
  "command": "java",
  "args": ["-jar", "your-application.jar"],
  "baseURL": "http://127.0.0.1:8080"
}

注意:

'your-application.jar' 需要替换成你实际打包的应用 JAR 文件名。
如果你的 SSE 服务器配置了不同的端口或端点，你需要相应地修改 'baseURL'。
'serverName' 可以自定义，用于在 MCP 客户端中标识不同的服务器。

基本使用方法

创建 MCP 资源类: 使用 '@McpResources' 注解类，并使用 '@McpResource' 注解方法来定义资源。

import com.github.codeboyzhou.mcp.declarative.annotation.McpResource;
import com.github.codeboyzhou.mcp.declarative.annotation.McpResources;

@McpResources
public class MyResources {

    @McpResource(uri = "/hello", name = "helloResource", description = "返回问候语")
    public String hello() {
        return "Hello from MCP Server!";
    }
}

创建 MCP 工具类: 使用 '@McpTools' 注解类，并使用 '@McpTool' 注解方法来定义工具。使用 '@McpToolParam' 注解方法的参数来定义工具的参数。

import com.github.codeboyzhou.mcp.declarative.annotation.McpTool;
import com.github.codeboyzhou.mcp.declarative.annotation.McpToolParam;
import com.github.codeboyzhou.mcp.declarative.annotation.McpTools;

@McpTools
public class MyTools {

    @McpTool(name = "echoTool", description = "回显输入的文本")
    public String echo(@McpToolParam(name = "text", description = "要回显的文本") String text) {
        return "You said: " + text;
    }
}

启动 MCP 服务器: 在你的主应用程序类中，使用 'McpServers' 类来启动 MCP 服务器。你需要使用 '@McpComponentScan' 注解来指定扫描的包，并调用 'McpServers.run()' 方法初始化，然后选择 'startSyncStdioServer' 或 'startSyncSseServer' 方法启动相应类型的服务器。

import com.github.codeboyzhou.mcp.declarative.McpServers;
import com.github.codeboyzhou.mcp.declarative.annotation.McpComponentScan;

@McpComponentScan
public class MyApplication {

    public static void main(String[] args) {
        McpServers.run(MyApplication.class, args)
                .startSyncStdioServer("My MCP Server", "1.0.0"); // 启动 Stdio 服务器
        // 或者
        // McpServers.run(MyApplication.class, args)
        //         .startSyncSseServer("My MCP Server", "1.0.0"); // 启动 SSE 服务器 (默认端口 8080)
    }
}

运行你的应用程序后，MCP 服务器将启动，并可以通过配置的 MCP 客户端进行访问和使用。

关键词