Add fastMCP4J: Annotation-Driven Java MCP Server Library

[tersePrompts]

Summary

fastMCP4J is a Java 17+ library for building MCP servers using annotations. It dramatically reduces the boilerplate required to create AI-callable tools from ~35 lines per tool (official SDK) to ~5 lines. Lightweight, production-ready, and framework-agnostic.

Project Details

• Name: fastMCP4J
• GitHub Repository: https://github.com/tersePrompts/fastMCP4J
• Maven Central: https://central.sonatype.com/artifact/io.github.terseprompts.fastmcp/fastmcp-java
• License: MIT
• Language: Java 17+
• Current Version: 0.3.1-beta

Installation

Maven

```xml

io.github.terseprompts.fastmcp
fastmcp-java
0.3.1-beta

```

Gradle

```groovy
dependencies {
implementation 'io.github.terseprompts.fastmcp:fastmcp-java:0.3.1-beta'
}
```

Quick Start

```java
import com.ultrathink.fastmcp.*;

@MCPSERVER(name = "MyAssistant", version = "1.0")
public class MyAssistant {

@McpTool(description = "Add two numbers")
public int add(int a, int b) {
    return a + b;
}

@McpTool(description = "Summarize text to max 100 chars")
public String summarize(@McpParam(description = "Text to summarize") String text) {
    return text.substring(0, Math.min(100, text.length()));
}

public static void main(String[] args) {
    FastMCP.server(MyAssistant.class)
        .stdio()           // or .sse() or .streamable()
        .run();
}

}
```

MCP Configuration (Claude Desktop)

```json
{
"mcpServers": {
"myAssistant": {
"command": "java",
"args": ["-cp", "your-classpath", "com.example.MyAssistant"]
}
}
}
```

Key Features

Annotation-Driven Development

Annotation	Purpose
`@McpServer`	Define MCP server metadata
`@McpTool`	Expose any method as an AI tool
`@McpResource`	Serve data/files to AI agents via URI
`@McpPrompt`	Define reusable LLM prompt templates
`@McpParam`	Add description, examples, constraints, defaults
`@McpAsync`	Reactive tools with Project Reactor
`@McpContext`	Inject request context for progress/reporting
`@McpMemory`	Built-in persistent storage
`@McpTodo`	Built-in task management tools
`@McpPlanner`	Built-in task decomposition tools
`@McpFileRead`	Built-in file reading tools
`@McpFileWrite`	Built-in file writing tools
`@McpBash`	Built-in shell command execution
`@McpTelemetry`	Built-in metrics and tracing
`@McpPreHook` / `@McpPostHook`	Run code before/after tools

Built-in Tools (One Annotation = Full Functionality)

Annotation	Tools Provided
`@McpMemory`	list, read, create, replace, insert, delete, rename
`@McpTodo`	add, list, updateStatus, updateTask, delete, clearCompleted
`@McpPlanner`	createPlan, listPlans, getPlan, addTask, addSubtask
`@McpFileRead`	readLines, readFile, grep, getStats
`@McpFileWrite`	writeFile, appendFile, writeLines, deleteFile, createDirectory
`@McpBash`	execute_command (with OS-aware shell selection)

Three Transport Options

```java
FastMCP.server(MyServer.class)
.stdio() // For CLI tools, local agents (Claude Desktop)
.sse() // For web clients, long-lived connections
.streamable() // For bidirectional streaming (recommended)
.port(3000) // HTTP port
.requestTimeout(Duration.ofMinutes(5)) // Request timeout
.keepAliveSeconds(30) // Keep-alive interval
.run();
```

Multi-Class Tool Organization

Manual modules (fast, explicit):
```java
@MCPSERVER(
name = "MyServer",
version = "1.0",
modules = {StringTools.class, MathTools.class}
)
```

Package scanning (convenient):
```java
@MCPSERVER(
name = "MyServer",
version = "1.0",
scanBasePackage = "com.example.tools"
)
```

Comparison: FastMCP4J vs Alternatives

vs Official MCP Java SDK

Aspect	Official SDK	FastMCP4J
Code per tool	~35 lines	~5 lines
JSON Schema	Manual	Auto-generated
Type safety	Manual parsing	Automatic binding
Built-in tools	None	6 modules included
Dependencies	SDK only	SDK + 11 lightweight

vs Spring AI MCP

Aspect	Spring AI MCP	FastMCP4J
Spring required?	Yes	No
Framework lock-in	Yes	No
Startup time	~2-5s	<500ms
Dependencies	50+ jars	12 jars
Best for	Spring Boot apps	Any Java app

Performance

Metric	Value
Cold start	<500ms
Tool invocation	<5ms
Memory footprint	~64MB
Dependencies	12 jars
Test coverage	197 passing tests

Perfect For

• Java developers integrating with Claude Desktop, Cursor, Windsurf
• Backend engineers exposing business logic to AI agents
• Enterprise teams building LLM-powered microservices
• Anyone building AI tools in Java without learning a new framework

Real-World Example

```java
@MCPSERVER(name = "DatabaseTools", version = "1.0")
@McpMemory // AI remembers across sessions
@McpTodo // AI manages tasks
public class DatabaseTools {

@McpTool(description = "Query user by ID")
public User getUserById(@McpParam(description = "User ID") int userId) {
    return userRepository.findById(userId);
}

@McpTool(description = "Search users by name")
public List<User> searchUsers(@McpParam(description = "Name to search") String name) {
    return userRepository.findByNameContaining(name);
}

}
```

Documentation

• Architecture
• Roadmap
• Contributing
• Changelog
• Working Example

---

Use case: Java developers who want the fastest way to build MCP servers and expose existing Java business logic to AI agents, without framework lock-in or heavy dependencies.

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com