mcp-annotated-java-sdk

> mcp-annotated-java-sdk: Spring-free annotation layer for building lightweight Model Context Protocol servers in plain Java.

## What is this?

A lightweight, annotation-based Java framework for building MCP (Model Context Protocol) servers without Spring. It sits on top of the official MCP Java SDK, generates low-level component bindings from annotated Java methods, and targets CLI tools, embedded servers, local automation, and small service processes.

Spring AI MCP is the standard choice for Spring applications. This SDK is for lightweight Java MCP servers where a Spring runtime is unnecessary or undesirable.

## Positioning

| Project | Best fit | Role |
|---------|----------|------|
| Official MCP Java SDK | Library authors and low-level protocol integration | Foundation |
| Spring AI MCP | Spring Boot / Spring Framework applications | Spring ecosystem standard |
| mcp-annotated-java-sdk | Plain Java, CLI, embedded, and lightweight MCP servers | Spring-free annotation layer |

## Key Features

- No Spring Framework Required - Pure Java, lightweight and fast
- Instant MCP Server - Start server with just 1 line of code
- Low Boilerplate - No need to write repetitive low-level MCP SDK registration code
- Generated JSON Schema - Derive schemas from annotated Java signatures and metadata
- Compile-Time Binding Generation - Annotation processing creates deterministic MCP component providers
- Type-Aware - Leverage Java signatures and compile-time checks for safer MCP components

## Roadmap Focus

- Stay compatible with the official MCP Java SDK.
- Make plain Java MCP servers faster to write, test, and ship.
- Improve compile-time validation, generated bindings, schema support, and examples.
- Avoid competing with Spring AI on Boot auto-configuration, WebMVC/WebFlux integration, enterprise security, or observability.

## Requirements

- Java 17 or later

## Packaging

For deployment with `java -jar`, build an executable fat JAR and configure the JAR manifest main class. `mcp-server.yml` should be packaged from `src/main/resources`.

## Quick Start

### Maven Dependency

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

### Gradle Dependency

```gradle
implementation 'io.github.thought2code:mcp-annotated-java-sdk:0.21.0'
```

### Create MCP Server

```java
@McpServerApplication
public class MyFirstMcpServer {
    public static void main(String[] args) {
        McpApplication.run(MyFirstMcpServer.class, args);
    }
}
```

### Define Tools

```java
@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;
}
```

### Define Resources

```java
@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"));
    return info;
}
```

### Define Prompts

```java
@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);
}
```

## Core Annotations

| Annotation | Purpose |
|------------|---------|
| `@McpServerApplication` | Marks the main class as an MCP server application |
| `@McpTool` | Marks a method as an MCP tool |
| `@McpToolParam` | Marks a parameter as a tool parameter |
| `@McpResource` | Marks a method as an MCP resource |
| `@McpPrompt` | Marks a method as an MCP prompt |
| `@McpPromptParam` | Marks a parameter as a prompt parameter |
| `@McpResourceCompletion` | Marks a method as a resource URI completion handler |
| `@McpPromptCompletion` | Marks a method as a prompt-argument completion handler |
| `@McpJsonSchemaDefinition` | Marks a type as a custom JSON Schema definition |
| `@McpJsonSchemaProperty` | Describes a field in a JSON Schema definition |

## Completions

When `capabilities.completion: true`, handlers return `CompletionResult` and accept one `McpSchema.CompleteRequest.CompleteArgument` parameter.

- `@McpResourceCompletion.uri` must match the paired `@McpResource.uri` exactly (including templates like `file://{path}`).
- `@McpPromptCompletion.name` must match the registered prompt name (`@McpPrompt.name`, or else the `@McpPrompt` method name). Filter with `argument.name()` for multi-parameter prompts.

## Server Modes

If `mode` is omitted in `mcp-server.yml`, the server defaults to **STREAMABLE**.

| Mode | Description | Use Case |
|------|-------------|----------|
| STDIO | Standard input/output | CLI tools, local development |
| STREAMABLE | HTTP streaming | Web applications, production (recommended) |

## Configuration (mcp-server.yml)

```yaml
enabled: true
mode: STDIO
name: my-mcp-server
version: 1.0.0
type: SYNC
instructions: You are a helpful AI assistant
request-timeout: 20000
capabilities:
  resource: true
  subscribe-resource: true
  prompt: true
  tool: true
  completion: true
change-notification:
  resource: true
  prompt: true
  tool: true
```

## Important Notes

- Use `McpApplication.run()` as the server entry point; optional third argument overrides the config file name (default `mcp-server.yml`)
- Component registration scope: `basePackageClass` → `basePackage` → main class package; one instance per component class (public no-arg constructor)
- `instructions` must be a non-blank string in `mcp-server.yml` (validated at startup)
- `type: ASYNC` uses the async MCP server API; annotated methods stay blocking Java wrapped in `Mono.fromCallable(...)` — not Project Reactor
- One instance per component class is created and shared across concurrent requests — keep components stateless or thread-safe
- Components are auto-registered when they are within the resolved registration scope

## Links

- GitHub: https://github.com/thought2code/mcp-annotated-java-sdk
- Documentation: https://thought2code.github.io/mcp-annotated-java-sdk
- Examples: https://github.com/thought2code/mcp-java-sdk-examples
- MCP Protocol: https://modelcontextprotocol.io