Content
# Annotation-driven MCP Java SDK
[](https://central.sonatype.com/artifact/io.github.thought2code/mcp-annotated-java-sdk)
[](https://github.com/thought2code/mcp-annotated-java-sdk/graphs/commit-activity)
[](https://app.codecov.io/github/thought2code/mcp-annotated-java-sdk)
[](https://github.com/thought2code/mcp-annotated-java-sdk/actions/workflows/maven-build.yml)
> 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](https://thought2code.github.io/mcp-annotated-java-sdk-docs) | [💡 Examples](https://github.com/thought2code/mcp-java-sdk-examples/tree/main/mcp-server-filesystem/mcp-server-filesystem-annotated-sdk-implementation) | [🐛 Report Issues](https://github.com/thought2code/mcp-annotated-java-sdk/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](https://github.com/modelcontextprotocol/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:**
```xml
<dependency>
<groupId>io.github.thought2code</groupId>
<artifactId>mcp-annotated-java-sdk</artifactId>
<version>0.13.0</version>
</dependency>
```
**Gradle:**
```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`:
```yaml
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
```java
@McpServerApplication
public class MyFirstMcpServer {
public static void main(String[] args) {
McpApplication.run(MyFirstMcpServer.class, args);
}
}
```
#### Step 4: Define MCP Resources (if needed)
```java
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
```java
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)
```java
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
```bash
# 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)](https://modelcontextprotocol.io) 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:
```yaml
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:
```yaml
# mcp-server.yml (base configuration)
enabled: true
mode: STREAMABLE
name: my-mcp-server
version: 1.0.0
profile: dev
```
```yaml
# mcp-server-dev.yml (profile-specific configuration)
streamable:
port: 8080
```
### Multilingual Support (i18n)
Enable i18n for your MCP components:
```java
@McpServerApplication
@McpI18nEnabled(resourceBundleBaseName = "messages")
public class I18nMcpServer {
public static void main(String[] args) {
McpApplication.run(I18nMcpServer.class, args);
}
}
```
Create resource bundles:
```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
```
```properties
# messages_zh_CN.properties
tool.calculate.description=计算两个数字的和
tool.calculate.param.a.description=第一个数字
tool.calculate.param.b.description=第二个数字
```
Use i18n keys in your MCP components:
```java
@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:
```bash
./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](https://github.com/modelcontextprotocol/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:
1. **Fork the repository**
2. **Create a new branch** for your feature or bug fix
3. **Add tests** for your changes
4. **Update documentation** if necessary
5. **Ensure all tests pass**
6. **Submit a pull request** with a clear description of your changes
### Development Setup
```bash
# 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
- [Official Documentation](https://thought2code.github.io/mcp-annotated-java-sdk-docs)
- [Examples Repository](https://github.com/thought2code/mcp-java-sdk-examples/tree/main/mcp-server-filesystem/mcp-server-filesystem-annotated-sdk-implementation)
- [MCP Official Site](https://modelcontextprotocol.io)
## 📄 License
This project is licensed under the [MIT License](LICENSE).
## 🙏 Acknowledgments
- [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk) - The underlying MCP implementation
- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol specification
> [!NOTE]
> This project is under active development. We appreciate your feedback and contributions!
