Annotation-driven MCP Java SDK

🚀 Declarative MCP Java SDK Development with Java Annotations

Annotation-driven MCP Java SDK is a lightweight, annotation-based framework that simplifies MCP server development in Java. Define, develop and integrate your MCP Resources / Prompts / Tools with minimal code - No Spring Framework Required.

📖 Documentation | 💡 Examples | 🐛 Report Issues

✨ Why Choose This SDK?

Key Advantages

• 🚫 No Spring Framework Required - Pure Java, lightweight and fast
• ⚡ Instant MCP Server - Get your server running with just 1 line of code
• 🎉 Zero Boilerplate - No need to write low-level MCP SDK code
• 👏 No JSON Schema - Forget about complex and lengthy JSON definitions
• 🎯 Focus on Logic - Concentrate on your core business logic
• 🔌 Spring AI Compatible - Configuration file compatible with Spring AI Framework
• 🌍 Multilingual Support - Built-in i18n support for MCP components
• 📦 Type-Safe - Leverage Java's type system for compile-time safety

Comparison with Official MCP Java SDK

Feature	Official MCP SDK	This SDK
Code Required	~50-100 lines	~5-10 lines
JSON Schema	Hand-coded JSON	No need to care
Type Safety	Limited	Full
Learning Curve	Steep	Gentle
Multilingual	Unsupported	Supported

🎯 Quick Start

Prerequisites

• Java 17 or later (required by official MCP Java SDK)
• Maven 3.6+ or Gradle 7+

5-Minutes Tutorial

Step 1: Add Dependency

Maven:

<dependency>
    <groupId>io.github.codeboyzhou</groupId>
    <artifactId>mcp-declarative-java-sdk</artifactId>
    <version>0.9.0</version>
</dependency>

Gradle:

implementation 'io.github.codeboyzhou:mcp-declarative-java-sdk:0.9.0'

Step 2: Create Your First MCP Server

@McpServerApplication
// If your MCP server components don't need to be multilingual, you can remove this annotation.
@McpI18nEnabled(resourceBundleBaseName = "i18n/mcp_server_components_info")
public class MyFirstMcpServer {
    public static void main(String[] args) {
        McpServers.run(MyFirstMcpServer.class, args)
            .startStdioServer(McpServerInfo.builder()
                .name("my-first-mcp-server")
                .version("1.0.0")
                .build());
    }
}

Step 3: Define MCP Resources (if needed)

public class MyResources {
    @McpResource(uri = "system://info", description = "System information")
    public Map<String, String> getSystemInfo() {
        Map<String, String> info = new HashMap<>();
        info.put("os", System.getProperty("os.name"));
        info.put("java", System.getProperty("java.version"));
        info.put("cores", String.valueOf(Runtime.getRuntime().availableProcessors()));
        return info;
    }
}

Step 4: Define MCP Tools

public class MyTools {
    @McpTool(description = "Calculate the sum of two numbers")
    public int add(
        @McpToolParam(name = "a", description = "First number", required = true) int a,
        @McpToolParam(name = "b", description = "Second number", required = true) int b
    ) {
        return a + b;
    }
}

Step 5: Define MCP Prompts (if needed)

public class MyPrompts {
    @McpPrompt(description = "Generate code for a given task")
    public String generateCode(
        @McpPromptParam(name = "language", description = "Programming language", required = true) String language,
        @McpPromptParam(name = "task", description = "Task description", required = true) String task
    ) {
        return String.format("Write %s code to: %s", language, task);
    }
}

Step 6: Run Your Server

# Compile and run
mvn clean package
java -jar target/your-app.jar

That's it! Your MCP server is now ready to serve resources, tools, and prompts!

📚 Core Concepts

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol for building servers that expose data and functionality to LLM applications. Think of it like a web API, but specifically designed for LLM interactions.

MCP Components

Component	Purpose	Analogy
Resources	Expose data to LLM	GET endpoints
Tools	Execute actions	POST endpoints
Prompts	Reusable templates	Form templates

Supported Server Modes

This SDK supports three MCP server modes:

1. STDIO - Standard input/output communication (default for CLI tools)
2. SSE (Server-Sent Events) - HTTP-based real-time communication
3. Streamable HTTP - HTTP streaming for web applications

🔧 Advanced Usage

Configuration File

Create mcp-server.yml in your classpath:

enabled: true
mode: STREAMABLE
name: my-mcp-server
version: 1.0.0
type: SYNC
request-timeout: 20000
capabilities:
  resource: true
  prompt: true
  tool: true
change-notification:
  resource: true
  prompt: true
  tool: true
streamable:
  mcp-endpoint: /mcp/message
  disallow-delete: true
  keep-alive-interval: 30000
  port: 8080

Then start your server:

McpServers servers = McpServers.run(MyMcpServer.class, args);
servers.startServer();  // Uses default mcp-server.yml
// or
servers.startServer("custom-config.yml");

Multilingual Support

Enable i18n for your MCP components:

@McpServerApplication
@McpI18nEnabled(resourceBundleBaseName = "messages")
public class I18nMcpServer {
    public static void main(String[] args) {
        McpServers.run(I18nMcpServer.class, args)
            .startStdioServer(McpServerInfo.builder()
                .name("i18n-server")
                .version("1.0.0")
                .build());
    }
}

// Create messages.properties
# messages.properties
tool.calculate.description=Calculate the sum of two numbers
tool.calculate.param.a.description=First number
tool.calculate.param.b.description=Second number

// Create messages_zh_CN.properties
# messages_zh_CN.properties
tool.calculate.description=计算两个数字的和
tool.calculate.param.a.description=第一个数字
tool.calculate.param.b.description=第二个数字

// Then use the i18n messages in your MCP components, like this:
@McpTool(description = "tool.calculate.description")
public int add(
    @McpToolParam(name = "a", description = "tool.calculate.param.a.description") int a,
    @McpToolParam(name = "b", description = "tool.calculate.param.b.description") int b
) {
    return a + b;
}

🏗️ Project Structure

A typical project structure:

your-mcp-project/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           ├── MyMcpServer.java          # Main entry point
│   │   │           ├── components/
│   │   │           │   ├── MyResources.java     # MCP Resources
│   │   │           │   ├── MyTools.java         # MCP Tools
│   │   │           │   └── MyPrompts.java       # MCP Prompts
│   │   │           └── service/
│   │   │               └── BusinessLogic.java    # Your business logic
│   │   └── resources/
│   │       ├── mcp-server.yml                    # MCP configuration
│   │       └── messages.properties               # i18n messages
│   └── test/
│       └── java/
│           └── com/
│               └── example/
│                   └── McpServerTest.java         # Unit tests

🧪 Testing

Run the test suite:

mvn test

Run tests with coverage:

mvn clean test jacoco:report

❓ FAQ

Q: Do I need Spring Framework?

A: No! This SDK is completely independent of Spring Framework. However, the configuration file format is compatible with Spring AI if you want to migrate.

Q: Can I use this in production?

A: This project is currently in active development. While it's stable for development and testing, we recommend thorough testing before production use.

Q: What Java version is required?

A: Java 17 or later is required, as this is a constraint of the underlying MCP Java SDK.

Q: How do I debug my MCP server?

A: You can use the inspector and set Java breakpoint to debug your MCP server.

🤝 Contributing

We welcome and appreciate contributions! Please follow these steps to contribute:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Submit a pull request with a clear description of your changes

Development Setup

# Clone the repository
git clone https://github.com/codeboyzhou/mcp-declarative-java-sdk.git
cd mcp-declarative-java-sdk

# Build the project
mvn clean install

# Run tests
mvn test

📖 Documentation

• Official Documentation
• Examples Repository
• MCP Official Site

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• MCP Java SDK - The underlying MCP implementation
• Model Context Protocol - The protocol specification

Note

This project is under active development. We appreciate your feedback and contributions!