MCP Declarative Java SDK
driven MCP servers development with Java, no Spring Framework Required, minimize dependencies as much as possible.
Ask AI about MCP Declarative Java SDK
Powered by Claude ยท Grounded in docs
I know everything about MCP Declarative Java SDK. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Annotation-driven MCP Java SDK
Annotation-driven MCP dev ๐ No Spring, Zero Boilerplate, Pure Java.
This 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 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)
5-Minutes Tutorial
Step 1: Add Dependency
Maven:
<dependency>
<groupId>io.github.thought2code</groupId>
<artifactId>mcp-annotated-java-sdk</artifactId>
<version>0.13.0</version>
</dependency>
Gradle:
implementation 'io.github.thought2code:mcp-annotated-java-sdk:0.13.0'
Step 2: Create Configuration File
Create mcp-server.yml in your src/main/resources:
enabled: true
mode: STDIO
name: my-first-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
Step 3: Create Your MCP Server
@McpServerApplication
public class MyFirstMcpServer {
public static void main(String[] args) {
McpApplication.run(MyFirstMcpServer.class, args);
}
}
Step 4: 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 5: Define MCP Tools
public class MyTools {
@McpTool(description = "Calculate the sum of two numbers")
public int add(
@McpToolParam(name = "a", description = "First number") int a,
@McpToolParam(name = "b", description = "Second number") int b
) {
return a + b;
}
}
Step 6: 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") String language,
@McpPromptParam(name = "task", description = "Task description") String task
) {
return String.format("Write %s code to: %s", language, task);
}
}
Step 7: Run Your Server
# Compile and run
./mvnw 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:
| Mode | Description | Use Case |
|---|---|---|
| STDIO | Standard input/output communication | CLI tools, local development |
| SSE | Server-Sent Events (HTTP-based) | Real-time web applications (deprecated) |
| STREAMABLE | HTTP streaming | Web applications, recommended for production |
๐ง 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
Configuration Properties
| Property | Description | Default |
|---|---|---|
enabled | Enable/disable MCP server | true |
mode | Server mode: STDIO, SSE, STREAMABLE | STREAMABLE |
name | Server name | mcp-server |
version | Server version | 1.0.0 |
type | Server type: SYNC, ASYNC | SYNC |
request-timeout | Request timeout in milliseconds | 20000 |
capabilities | Enable resources, prompts, tools | all true |
change-notification | Enable change notifications | all true |
Profile-based Configuration
You can use profiles for different environments:
# mcp-server.yml (base configuration)
enabled: true
mode: STREAMABLE
name: my-mcp-server
version: 1.0.0
profile: dev
# mcp-server-dev.yml (profile-specific configuration)
streamable:
port: 8080
Multilingual Support (i18n)
Enable i18n for your MCP components:
@McpServerApplication
@McpI18nEnabled(resourceBundleBaseName = "messages")
public class I18nMcpServer {
public static void main(String[] args) {
McpApplication.run(I18nMcpServer.class, args);
}
}
Create resource bundles:
# 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
# messages_zh_CN.properties
tool.calculate.description=่ฎก็ฎไธคไธชๆฐๅญ็ๅ
tool.calculate.param.a.description=็ฌฌไธไธชๆฐๅญ
tool.calculate.param.b.description=็ฌฌไบไธชๆฐๅญ
Use i18n keys in your MCP components:
@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:
./mvnw clean test
โ 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: What Maven version is required?
A: Just use the provided Maven wrapper script ./mvnw to build this project.
Q: How do I debug my MCP server?
A: You can use the MCP Inspector and set Java breakpoints to debug your MCP server.
Q: Which server mode should I use?
A:
- STDIO: For CLI tools and local development
- STREAMABLE: For web applications and production deployments (recommended)
- SSE: Deprecated, use STREAMABLE instead
๐ค Contributing
We welcome and appreciate contributions! Please follow these steps to contribute:
- Fork the repository
- Create a new branch for your feature or bug fix
- Add tests for your changes
- Update documentation if necessary
- Ensure all tests pass
- Submit a pull request with a clear description of your changes
Development Setup
# Clone the repository
git clone https://github.com/thought2code/mcp-annotated-java-sdk.git
cd mcp-annotated-java-sdk
# Build the project
./mvnw clean install
# Run tests
./mvnw clean test
๐ Documentation
๐ 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!
