Content
<div align="left">
# MCP Facade Generator
[](https://www.apache.org/licenses/LICENSE-2.0.html)
[](https://search.maven.org/search?q=g:com.unionhole.mcp:mcp-facade-generator)
[](https://openjdk.java.net/)
[](https://github.com/james-zou/mcp-facade-generator/releases)
- 🚀**A powerful MCP protocol Facade generator that supports automatic generation of MCP protocol interface implementations**
- 🔌**No need to worry about the development process of the MCP server, quickly integrate existing business interfaces with the MCP protocol**
- 🚀**Supports one-click generation of springboot+MCP demo projects**
## Table of Contents
- [Features](#features)
- [Quick Start](#quick-start)
- [Usage Instructions](#usage-instructions)
- [Configuration Options](#configuration-options)
- [Examples](#examples)
- [API Documentation](#api-documentation)
- [Contribution Guidelines](#contribution-guidelines)
- [Version History](#version-history)
- [License](#license)
## ✨ Features
- 🛠️ **Automatic Generation** - Automatically generates MCP Facade implementations at compile time
- 🎯 **Simple Integration** - Just add dependencies and annotations to use
- 🔌 **Flexible Extension** - Supports custom package names and method descriptions
- 📝 **Comment Inheritance** - Automatically inherits method comments from the original service
- 🛡️ **Exception Handling** - Unified exception handling mechanism
- 🔄 **Type Conversion** - Complete support for parameter type conversion
## Quick Start
### 1. Add Maven Dependency
``` java
<dependency>
<groupId>com.unionhole</groupId>
<artifactId>mcp-facade-generator</artifactId>
<version>1.0.1</version>
<scope>provided</scope>
</dependency>
```
### 2. Add Compiler Plugin
``` java
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>8</source>
<target>8</target>
<annotationProcessors>
<annotationProcessor>com.unionhole.mcp.processor.MCPFacadeProcessor</annotationProcessor>
</annotationProcessors>
</configuration>
</plugin>
```
### 3. Add Annotation to Service Class
``` java
@MCPService(packageName = "com.example.demo.mcp")
```
### 4. Add Comments to Service Methods
``` java
For example, the comment "Get weather information by city name"
/**
* Get weather information by city name
* @return
*/
public String getWeather(String cityName) {
// Implementation
return null;
}
```
### 5. Annotation Description
``` xml
#### @MCPService
Used to mark service classes that need to generate Facade.
Parameters:
- `value`: Service name (optional)
- `packageName`: Package name of the generated Facade class (optional)
#### @Tool
Used to mark the description information of Facade methods.
Parameters:
- `description`: Method description
#### @MCPMethod
Used to mark methods that need to be generated in the Facade. If a method in the service class does not have this annotation, it will not be generated in the Facade after version 1.0.1.
Parameters:
- `description`: Method description, used to generate the description of the @Tool annotation (optional, defaults to using the method's JavaDoc)
```
### Demo Project Generation
Starting from version 1.0.1, it supports automatically generating a complete demo project at compile time. By default, the demo project generation feature is disabled. You can enable demo project generation in the following two ways:
#### Method 1: Maven Compiler Parameter Configuration (Recommended)
Add the following configuration to the pom.xml of the project using mcp-facade-generator:
```xml
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<annotationProcessorPaths>
<path>
<groupId>com.unionhole</groupId>
<artifactId>mcp-facade-generator</artifactId>
<version>1.0.1</version>
</path>
</annotationProcessorPaths>
<compilerArgs>
<arg>-Amcp.demo.output=true</arg>
</compilerArgs>
</configuration>
</plugin>
</plugins>
</build>
```
#### Method 2: Spring Boot Configuration File + Maven Configuration (Not Recommended)
1. Add configuration in `application.properties`:
```properties
# Set to true to enable demo project generation
mcp.demo.output=true
```
Or in `application.yml`:
```yaml
mcp:
demo:
output: true
```
2. Add configuration in pom.xml (required):
```xml
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<annotationProcessorPaths>
<path>
<groupId>com.unionhole</groupId>
<artifactId>mcp-facade-generator</artifactId>
<version>1.0.1</version>
</path>
</annotationProcessorPaths>
<compilerArgs>
<arg>-AmcpConfigFile=${project.basedir}/src/main/resources/application.properties</arg>
</compilerArgs>
</configuration>
</plugin>
</plugins>
</build>
```
> **Important Notes:**
> 1. You must configure `annotationProcessorPaths` in the Maven compiler plugin; otherwise, the annotation processor will not be activated.
> 2. When using Method 2, the configuration file must exist at compile time, and the path must be correct.
> 3. It is recommended to use Method 1, which directly specifies the configuration through compiler parameters, making it more reliable.
> 4. If both configuration methods are used, the priority of the compiler parameters is higher.
> 5. When demo project generation is enabled, the project will be automatically generated in the `demo` directory of the current project.
The generated Demo project includes:
- Complete project structure
- Spring Boot + Spring AI MCP configuration
- Example service and Facade classes
- Runnable test cases
### Verification of the Generated Demo Project
After generation, you can:
1. Enter the generated demo project directory
2. Execute Maven commands for testing:
```bash
cd /path/to/demo/project
mvn clean test
```
If the tests pass, it indicates that the demo project was generated successfully.
### Generation Rules
- Corresponding Facade methods will be generated for all public methods
- Method parameters will be converted to MCPRequest
- Return values will be wrapped in MCPResponse
- Exceptions will be uniformly handled and converted to error responses
### Demo Example
``` java
package com.example.demo.service;
import com.unionhole.mcp.annotation.MCPService;
import org.springframework.stereotype.Service;
/**
* @author roderick.zou
* @Description:
* @date 2025/3/19 5:05 PM
*/
@MCPService(packageName = "com.example.demo.mcp")
@Service
public class WeatherService {
/**
* Get weather information by city name
* @return
*/
public String getWeather(String cityName) {
// Implementation
return null;
}
/**
* Get weather information by city name1
* @return
*/
public String getWeather1(String cityName) {
// Implementation
return null;
}
}
```
### Generated Example
``` java
package com.example.demo.mcp;
import com.unionhole.mcp.vo.MCPRequest;
import com.unionhole.mcp.vo.MCPResponse;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;
import com.example.demo.service.WeatherService;
/**
* Auto-generated MCP Facade class for WeatherService
*
* @author James Zou
* @version 1.0.0
* @since 2025-03-19
*/
public class WeatherServiceFacade {
private final WeatherService service;
public WeatherServiceFacade(WeatherService service) {
this.service = service;
}
@Tool(description = "Get weather information by city name")
public MCPResponse getWeather(MCPRequest request) {
try {
// Parse request parameters
java.lang.String cityName = request.getParameter("cityName", java.lang.String.class);
Object result = service.getWeather(cityName);
return MCPResponse.success(result);
} catch (Exception e) {
return MCPResponse.error(e.getMessage());
}
}
@Tool(description = "Get weather information by city name1")
public MCPResponse getWeather1(MCPRequest request) {
try {
// Parse request parameters
java.lang.String cityName = request.getParameter("cityName", java.lang.String.class);
Object result = service.getWeather1(cityName);
return MCPResponse.success(result);
} catch (Exception e) {
return MCPResponse.error(e.getMessage());
}
}
}
```
## 🔄 Version History
### v1.0.1 (2024-03-28)
- Optimized Facade generation logic, removed MCPRequest/MCPResponse wrapping
- Added support for @MCPMethod annotation, enabling method-level generation control
- Introduced demo project generation feature, supporting automatic generation of example projects through configuration
- Improved exception handling mechanism, directly throwing original exceptions
- Enhanced documentation and comment generation
### v1.0.0 (2024-03-19)
- ✨ Initial version release
- 🎉 Supported basic Facade generation functionality
- 💪 Supported JDK 17
## 🤝 Contribution Guidelines
1. Fork this repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -am 'Add amazing feature'`
4. Push the branch: `git push origin feature/amazing-feature`
5. Submit a Pull Request
## 📄 License
This project is licensed under the [Apache License 2.0](LICENSE).
## 👥 Maintainers
- James Zou ([@james-zou](https://github.com/james-zou))
## 🙏 Acknowledgments
Thanks to all the developers who contributed to this project!
---
## Environment Requirements
### Java Version Requirements
- JDK 17 or higher
- Ensure the JAVA_HOME environment variable is set correctly
- Ensure Maven uses the correct JDK version
### Version Check
1. Check Java version:
```bash
java -version
```
Should display version 17 or higher
2. Check the Java version used by Maven:
```bash
mvn -v
```
Ensure the displayed Java version is 17 or higher
### Common Issues Resolution
1. If you encounter the "Invalid target release: 17.x.x" error:
a. Check and set JAVA_HOME:
```bash
# Windows
echo %JAVA_HOME%
# Linux/Mac
echo $JAVA_HOME
```
b. Ensure JAVA_HOME points to the JDK 17 installation directory
c. Explicitly specify the compiler version in the project's pom.xml:
```xml
<properties>
<java.version>17</java.version>
<maven.compiler.source>${java.version}</maven.compiler.source>
<maven.compiler.target>${java.version}</maven.compiler.target>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
<encoding>UTF-8</encoding>
<annotationProcessors>
<annotationProcessor>com.unionhole.mcp.processor.MCPFacadeProcessor</annotationProcessor>
</annotationProcessors>
</configuration>
</plugin>
</plugins>
</build>
```
2. If using an IDE (like IntelliJ IDEA):
- Ensure the JDK version in Project Structure is set to 17
- Ensure the JDK version used in Maven settings is set to 17
- Refresh Maven project configuration
3. For Windows users:
- Check if JAVA_HOME is correctly set in system environment variables
- Ensure the Path variable includes %JAVA_HOME%\bin
4. For Linux/Mac users:
- You can use sdkman to manage Java versions:
```bash
# Install sdkman
curl -s "https://get.sdkman.io" | bash
# Install JDK 17
sdk install java 17.0.x-zulu
# Set default version
sdk default java 17.0.x-zulu
```
**[⬆ Back to Top](#mcp-facade-generator)**
If this project helps you, please give it a ⭐️!
</div>
