springboot-ai -example

This MCP server implements a Spring Boot based MCP example that demonstrates how to expose and call tools from an AI model using the MCP (Model-Controller-Prompt) architecture. The server integrates with external data sources (MongoDB and PostgreSQL) and uses @Tool annotated methods registered via ToolCallbackProvider, allowing the AI to discover available capabilities at runtime. A corresponding MCP client is included to discover capabilities, register tools with the AI model, and pass execution requests back to the server. To use it, start both the MongoDB and PostgreSQL instances, then run the server and client components. The AI model can request data, perform database lookups, or trigger tool actions, and the server will execute the tool logic and return results to the client for the final response.

Key capabilities include:

• Tool discovery and dynamic invocation via @Tool annotated methods.
• Dynamic tool registration through ToolCallbackProvider during initialization.
• Data access to MongoDB and PostgreSQL for real-time answer generation.
• End-to-end MCP workflow from user prompt to tool execution and final response delivered to the user interface.

Prerequisites:

• Docker and Docker Compose
• Java 21 and Maven (for local builds)
• OpenAI API key
• MongoDB and PostgreSQL (via Docker or external instances)

Step-by-step installation:

1. Install Docker and Docker Compose on your system.

2. Start the required databases (MongoDB and PostgreSQL) using Docker Compose as described in the project:

docker compose up -d

3. Obtain an OpenAI API key and set it in the configuration (the project references application.yml for client config). You can place your key in a .env file or pass it through environment variables as required by your setup, for example:

export OPENAI_API_KEY=your-openai-key-here

4. Build and run the MCP server and client locally (optional if you prefer Docker):

# From the mcp-server directory
cd mcp-server
./mvnw spring-boot:run

# In another terminal, from the mcp-client directory
cd ../mcp-client
./mvnw spring-boot:run

5. Alternatively, run the provided server image via Docker (as outlined in the mcp_config):

# Ensure MongoDB and PostgreSQL are accessible (through docker-compose or external instances)
# Run the server image (adjust image name if needed)
docker run -i duongminhhieu/springboot-ai-mcp-example

6. Verify the setup by sending a request to the MCP server endpoint (the README demonstrates how to test with Postman or curl).

Tips and notes:

• Ensure your OpenAI API key is valid and accessible to the MCP client/server configuration.
• The MCP workflow relies on tool discovery; make sure tools are properly annotated with @Tool and registered via ToolCallbackProvider during startup.
• For production, configure persistent MongoDB and PostgreSQL connections and consider securing endpoints behind authentication.
• If you update the server code, re-run the build and restart both server and client to refresh tool metadata on the client side.
• Common issues: mismatched API versions between Spring AI and the MCP runtime, missing environment variables, and database connection errors. Check logs for tool discovery errors and database query failures.