Content
<p align="center">
<h1 align="center">Java MCP Server</h1>
<p align="center">
<b>Language:</b>
<a href="README.md">中文</a> |
<a href="README_EN.md">English</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/Java-17-orange" alt="Java 17">
<img src="https://img.shields.io/badge/MCP%20Protocol-2025--03--26-blue" alt="MCP Protocol">
<img src="https://img.shields.io/badge/JSON--RPC-2.0-green" alt="JSON-RPC 2.0">
<img src="https://img.shields.io/badge/License-MIT-yellow" alt="MIT License">
</p>
</p>
---
## Tool List
| Tool | Description |
|------|------|
| `analyzeProject` | Comprehensive project audit: directory tree, code statistics, complexity, dependency analysis, engineering check → nine-stage interview-oriented report |
| `codeStats` | Language-based code statistics: number of files, total lines, code lines, comment lines, empty lines |
| `dependencyAnalysis` | Extract and categorize project dependencies from pom.xml/build.gradle |
| `complexityReport` | Java code complexity metrics: number of classes/methods, average density, maximum file |
| `engineeringCheck` | Check engineering infrastructure: CI/CD, Docker, testing, logging, multi-environment configuration |
| `readPdf` | Read PDF file content and return text |
| `analyzeResume` | Read PDF resume, perform ten-stage comprehensive audit based on 2026 internet giant standards |
## Resource List
| URI | MIME Type | Description |
|-----|-----------|------|
| `mcp://system/info` | application/json | Runtime environment: Java version, operating system, processor count, memory usage |
| `mcp://project/pom.xml` | application/xml | Maven project configuration |
| `mcp://project/README.md` | text/plain | Project documentation |
## Quick Start
### Requirements
- **Java 17+** (uses pattern matching, text blocks, switch expressions)
- **Maven 3.6+**
### Build
```bash
git clone https://github.com/kunxing/java-mcp-server.git
cd java-mcp-server
mvn clean package
```
The build product is a fat JAR: `target/java-mcp-server-1.0.0.jar`.
### Configure Claude Desktop
Edit `claude_desktop_config.json`:
```json
{
"mcpServers": {
"java-tools": {
"command": "java",
"args": ["-jar", "/path/to/java-mcp-server-1.0.0.jar"]
}
}
}
```
### Configure Cursor / VS Code
Create `.mcp.json` in the project root directory:
```json
{
"mcpServers": {
"java-mcp-server": {
"command": "java",
"args": ["-jar", "/path/to/java-mcp-server-1.0.0.jar"]
}
}
}
```
### Restart Client
Restart and tools and resources will be loaded automatically.
## Design Highlights
### Handwritten JSON-RPC 2.0 Codec
Polymorphic message decoding based on field detection:
```
method + id → JsonRpcRequest
only method → JsonRpcNotification
result / error → JsonRpcResponse
```
No external RPC library, only Jackson for JSON serialization.
### Annotation-Driven Tool System
Zero-boilerplate code defines tools:
```java
public class MyTool {
@Tool(name = "greet", description = "Returns a greeting")
public String greet(@ToolParam(name = "name") String name) {
return "Hello, " + name + "!";
}
}
```
The framework automatically handles:
- **ToolRegistry** — Scans `@Tool` annotations via reflection, builds method registry
- **ToolSchemaGenerator** — Generates JSON Schema from `@ToolParam` annotations
- **ToolInvoker** — Resolves parameters by name, type conversion, reflection invocation
### Thread-Safe State Machine
```
AtomicReference<State>: UNINITIALIZED → INITIALIZING → OPERATIONAL
```
Server rejects all tool/resource requests before MCP handshake (`initialize` + `notifications/initialized`) completion.
### Custom Exception System
```
McpException (base class, carries protocol error code)
├── JsonRpcException (-32700 parse error, -32600 invalid request, etc.)
├── ToolException (-32001 tool not found, -32002 execution failed, etc.)
└── TransportException (-32050 transport error, -32051 transport closed)
```
### Pluggable Transport Layer
`Transport` interface decouples I/O from protocol logic:
```java
public interface Transport {
void start();
void send(JsonRpcMessage message);
void onMessage(Consumer<JsonRpcMessage> handler);
void close();
}
```
`StdioTransport` is the default implementation. Can be replaced with SSE, WebSocket, or custom transport.
## Project Structure
```
src/main/java/mcp/
├── McpServer.java # Entry point — assembles all components
├── protocol/
│ ├── JsonRpcCodec.java # JSON-RPC 2.0 codec
│ ├── JsonRpcMessage.java # Message abstract base class
│ ├── JsonRpcRequest.java # Request (id, method, params)
│ ├── JsonRpcResponse.java # Response (result or error)
│ ├── JsonRpcNotification.java # One-way notification
│ ├── JsonRpcError.java # Error object (code, message, data)
│ ├── McpException.java # Base exception (carries error code)
│ └── JsonRpcException.java # Protocol layer error
├── transport/
│ ├── Transport.java # Pluggable transport interface
│ ├── StdioTransport.java # stdin/stdout implementation
│ └── TransportException.java # Transport layer error
├── server/
│ ├── McpServerHandler.java # Message dispatcher + state machine
│ ├── InitializeHandler.java # MCP handshake processor
│ └── ServerConfig.java # Server name, version, protocol version
├── tool/
│ ├── Tool.java # @Tool annotation
│ ├── ToolParam.java # @ToolParam annotation
│ ├── ToolRegistry.java # Annotation scanner + tool registry
│ ├── ToolInvoker.java # Parameter resolution and invocation based on reflection
│ ├── ToolSchemaGenerator.java # Generates JSON Schema from annotations
│ └── ToolException.java # Tool execution error
├── resource/
│ ├── McpResource.java # Resource interface
│ ├── ResourceRegistry.java # Resource management + content reading
│ └── resources/
│ ├── SystemInfoResource.java # mcp://system/info
│ └── ProjectFileResource.java # mcp://project/<file>
└── tools/
├── ProjectTool.java # 5 project analysis tools
└── ResumeTool.java # 2 PDF/resume tools
```
## Technology Stack
| Category | Technology |
|------|------|
| Language | Java 17 (pattern matching, text blocks, switch expressions) |
| JSON | Jackson 2.17.0 |
| PDF | Apache PDFBox 3.0.1 |
| Logging | SLF4J 2.0.12 + Logback 1.5.3 |
| Testing | JUnit 5.10.2 + Mockito 5.11.0 (30 tests) |
| Build | Maven 3.6+ + Shade plugin (fat JAR) |
## Tests
```bash
mvn test
```
30 tests cover all core modules:
| Test Class | Coverage |
|--------|---------|
| `JsonRpcCodecTest` | Encoding, decoding, round-trip testing, exception handling (13 tests) |
| `ToolSystemTest` | ToolRegistry, ToolSchemaGenerator, ToolInvoker (10 tests) |
| `StdioTransportTest` | Sending, receiving, multi-message, round-trip, close (7 tests) |
## Extension
### Add New Tool
1. Create a class, add `@Tool` and `@ToolParam` annotations to the method:
```java
package mcp.tools;
import mcp.tool.Tool;
import mcp.tool.ToolParam;
public class MyTool {
@Tool(name = "myFunction", description = "Do something useful")
public String myFunction(
@ToolParam(name = "input", description = "Input parameter") String input) {
return "Processing result: " + input;
}
}
```
2. Register in `McpServer.java`:
```java
toolRegistry.register(new MyTool());
```
The framework automatically generates JSON Schema and handles invocation.
### Add New Resource
Implement `McpResource` interface and register in `McpServer.java`:
```java
resourceRegistry.register(new MyCustomResource());
```
## License
[MIT](LICENSE)
// test comment
