mcp-annotated-java-sdk

The Annotation-driven MCP Java SDK provides a lightweight framework to build MCP servers in pure Java without Spring or boilerplate. It uses Java annotations to declare MCP resources, tools, and prompts, so you can implement your MCP server with just a few annotated methods and a small main entry that boots the server. The typical workflow is to add the dependency to your Maven/Gradle project, create a small server class annotated with @McpServerApplication, and then start the server via McpServers.run(...). You can expose resources (GET-like data), tools (actions you can invoke), and prompts (reusable templates) in a type-safe way, with optional multilingual support via i18n configuration. The SDK emphasizes instant server setup with minimal code and no reliance on Spring, while still being compatible with SpringAI-style configuration files if needed.

In practice, you create a server class, define resources with @McpResource, tools with @McpTool, and optionally prompts with @McpPrompt. Then start the server using the provided bootstrapping code, for example by building a McpServerConfiguration and calling McpServers.run(YourServer.class, args). The framework supports multiple MCP server modes (STDIO, SSE, and Streamable HTTP) and can be configured through a YAML configuration file or programmatic configuration. This makes it easy to iterate on your MCP server logic, test locally, and deploy to your preferred runtime environment.

What you’ll typically do with the SDK:

• Add dependencies to your build tool (Maven or Gradle).
• Annotate your server class with @McpServerApplication and implement resources, tools, and prompts.
• Start the server from a main method and pass a configuration (name, version, etc.).
• Optionally enable multilingual support and i18n resources for your components.

Prerequisites:

• Java 17 or later
• Maven 3.6+ or Gradle 7+

1. Create a new Java project (Maven or Gradle).

2. Add the MCP Annotated Java SDK dependency.

Maven:

<dependency>
  <groupId>io.github.thought2code</groupId>
  <artifactId>mcp-annotated-java-sdk</artifactId>
  <version>0.12.1</version>
</dependency>

Gradle:

implementation 'io.github.thought2code:mcp-annotated-java-sdk:0.12.1'

3. Build the project to fetch dependencies.

4. Create your MCP server class and run it as described in the usage section.

Tips and common questions:

• The SDK is annotation-driven and does not require Spring; you can still integrate with Spring AI configuration if desired.
• If you enable i18n, supply messages.properties and localized variants (e.g., messages_zh_CN.properties) and reference labels and descriptions via the i18n keys.
• You can run servers in different modes (STDIO, SSE, or Streamable HTTP) depending on how you bootstrap McpServers and your configuration.
• For rapid iterations, start with a minimal @McpServerApplication class and gradually add resources (@McpResource), tools (@McpTool), and prompts (@McpPrompt).
• Ensure your Java version and project language level match the SDK expectations (Java 17+).