Spring MCP Bridge

Spring MCP Bridge is a tool that automatically converts REST endpoints from Spring Boot applications into an MCP (Message Conversation Protocol) server, allowing AI assistants like Claude, Cursor, and other MCP-compatible tools to directly interact with your APIs.

*It does not currently include authentication. If your Spring Boot API requires authentication, you will need to modify the handler code to include the appropriate headers or tokens.

📖 Overview

Integrating existing APIs with AI assistants typically requires manual coding or complex configuration. Spring MCP Bridge eliminates this complexity by automatically scanning your Spring Boot project and generating a ready-to-use MCP server.

✨ Features

- Automatic Scanning: Discovers all REST endpoints (@RestController, @GetMapping, etc.)
- Zero Configuration: No modifications needed to existing Spring Boot code
- Model Preservation: Maintains request and response models as MCP tools
- Javadoc Extraction: Uses existing documentation to enhance MCP tool descriptions
- Complete Documentation: Generates README and clear instructions for use

🚀 Installation

# Clone the repository
git clone https://github.com/brunosantos/spring-mcp-bridge.git
Enter the directory
cd spring-mcp-bridge

🛠️ Usage

1. Scan your Spring Boot project:

python spring_boot_mcp_converter.py --project /path/to/spring-project --output ./mcp_server --name MyAPI

2. Run the generated MCP server:

cd mcp_server
pip install -r requirements.txt
python main.py

3. Connect via MCP client:
- Configure your MCP client (Claude, Cursor, etc.) to use http://localhost:8000
- The MCP schema will be available at http://localhost:8000/.well-known/mcp-schema.json

📋 Arguments

| Argument | Description | Default |
|-------------|----------------------------------|--------------|
| --project | Path to Spring Boot project | (required) |
| --output | Output directory | ./mcp_server |
| --name | Application name | SpringAPI |
| --debug | Enable debug logging | False |

💻 Example

python spring_mcp_bridge.py --project ~/projects/my-spring-api --output ./mcp_server --name MyAPI

The tool will:
1. Scan the Spring Boot project for REST controllers
2. Identify model types, parameters, and return types
3. Generate a fully functional MCP server in Python/FastAPI
4. Create a compatible MCP schema that describes all endpoints

🔄 How It Works

1. Scanning: Analyzes Java source code to extract metadata from REST endpoints
2. Conversion: Converts Java types to JSON Schema types for MCP compatibility
3. Generation: Creates a FastAPI application that maps MCP calls to Spring REST calls
4. Forwarding: Routes requests from MCP client to the Spring Boot application

🔍 Spring Boot Features Supported

- REST Controllers (@RestController, @Controller)
- HTTP Methods (@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping)
- Request Parameters (@RequestParam)
- Path Variables (@PathVariable)
- Request Bodies (@RequestBody)
- Java Models and DTOs

⚙️ Configuration

The generated MCP server can be configured by editing the main.py file:

# The Spring Boot base URL - modify this to match your target API
SPRING_BASE_URL = "http://localhost:8080"

🧪 Testing

To test the MCP server:

1. Ensure your Spring Boot application is running
2. Start the MCP server
3. Visit http://localhost:8000/docs to see the FastAPI documentation
4. Check the MCP schema at http://localhost:8000/.well-known/mcp-schema.json
5. Connect with an MCP client like Claude

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Bruno Santos

🙏 Acknowledgments

- Inspired by FastAPI-MCP and the growing ecosystem of MCP-compatible tools
- Thanks to the Spring Boot and FastAPI communities29:["$","div",null,{"className":"my-8 pb-8 h-full