Declarative MCP Java SDK Development with Java Annotations.

Advantages

• No Spring Framework Required.
• Instant MCP Java server in 1 LOC.
• No need to write more SDK low-level codes.
• Get rid of complex and lengthy JSON schema definitions.
• Just focus on your core logic (resources/prompts/tools).
• Configuration file compatible with the Spring AI framework.

Showcase

Just put this one line code in your main method:

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

// You can use this annotation to specify the base package
// to scan for MCP resources, prompts, tools, but it's optional.
// If not specified, it will scan the package where the main method is located.
@McpComponentScan(basePackage = "com.github.codeboyzhou.mcp.server.examples")
public class MyMcpServer {

    public static void main(String[] args) {
        // Start a STDIO MCP server
        McpServers.run(MyMcpServer.class, args).startSyncStdioServer(
            McpServerInfo.builder().name("mcp-server").version("1.0.0").build()
        );
        // or a HTTP SSE MCP server
        McpServers.run(MyMcpServer.class, args).startSyncSseServer(
            McpSseServerInfo.builder().name("mcp-server").version("1.0.0").port(8080).build()
        );
        // or start with yaml configuration file (compatible with the Spring AI framework)
        McpServers.run(MyMcpServer.class, args).startServer();
        // or start with a specific configuration file (compatible with the Spring AI framework)
        McpServers.run(MyMcpServer.class, args).startServer("my-mcp-server.yml");
    }

}

This is a yaml configuration file example (named mcp-server.yml by default, or also mcp-server.yaml) only if you are using startServer() method:

enabled: true
stdio: false
name: mcp-server
version: 1.0.0
instructions: mcp-server
request-timeout: 30000
type: SYNC
resource-change-notification: true
prompt-change-notification: true
tool-change-notification: true
sse-message-endpoint: /mcp/message
sse-endpoint: /sse
base-url: http://localhost:8080
sse-port: 8080

No need to care about the low-level details of native MCP Java SDK and how to create the MCP resources, prompts, and tools. Just annotate them like this:

@McpResources
public class MyMcpResources {

    // This method defines a MCP resource to expose the OS env variables
    @McpResource(uri = "env://variables", description = "OS env variables")
    public String getSystemEnv() {
        // Just put your logic code here, forget about the MCP SDK details.
        return System.getenv().toString();
    }

    // Your other MCP resources here...
}

@McpPrompts
public class MyMcpPrompts {

    @McpPrompt(description = "A simple prompt to read a file")
    public String readFile(
        @McpPromptParam(name = "path", description = "filepath", required = true) String path) {
        // Just put your logic code here, forget about the MCP SDK details.
        return String.format("What is the complete contents of the file: %s", path);
    }

}

@McpTools
public class MyMcpTools {

    // This method defines a MCP tool to read a file
    @McpTool(description = "Read complete file contents with UTF-8 encoding")
    public String readFile(
        @McpToolParam(name = "path", description = "filepath", required = true) String path) {
        // Just put your logic code here, forget about the MCP SDK details.
        return Files.readString(Path.of(path));
    }

    // Your other MCP tools here...
}

Now it's all set, run your MCP server, choose one MCP client you like and start your MCP exploration journey.

[!WARNING] Please note that this project is under development and is not ready for production use.

Getting Started

Requirements

• Java 17 or later (Restricted by MCP Java SDK)

Installation

Add the following Maven dependency to your project:

<!-- Internally relies on native MCP Java SDK 0.10.0 -->
<dependency>
    <groupId>io.github.codeboyzhou</groupId>
    <artifactId>mcp-declarative-java-sdk</artifactId>
    <version>0.4.0</version>
</dependency>

Examples

You can find more examples and usages in this repository.

What is MCP?

The Model Context Protocol (MCP) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:

• Expose data through Resources (think of these sort of like GET endpoints; they are used to load information into the LLM's context)
• Provide functionality through Tools (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)
• Define interaction patterns through Prompts (reusable templates for LLM interactions)
• And more!

You can start exploring everything about MCP from here.