A comprehensive Java tutorial demonstrating Model Context Protocol (MCP) implementation with Quarkus server and LangChain4j client, featuring a monkey species dataset for hands-on learning.
This project showcases a complete MCP ecosystem built in Java, including:
- MCP Server: Quarkus-based HTTP SSE server with monkey species data tools
- MCP Client: Interactive CLI client using LangChain4j and Ollama integration
- Step-by-step Documentation: Complete guides for building MCP applications with GitHub Copilot
- Java 21+
- Maven 3.8+
- VS Code with Java Extension Pack
- Ollama (for LLM integration)
-
Clone the repository
git clone https://github.com/brunoborges/monkey-mcp-java.git cd monkey-mcp-java -
Start the MCP Server
cd monkey-mcp-server ./mvnw quarkus:dev -
Run the MCP Client
cd monkey-mcp-client ./mvnw package java -jar target/monkey-mcp-client.jar
This tutorial is organized into sequential parts:
| Part | Title | Description |
|---|---|---|
| Part 1: Prerequisites and Setup | Project Setup | Install tools, understand MCP, and prepare your environment |
| Part 2: Building the MCP Server | MCP Server | Build a Quarkus-based MCP server with monkey species tools |
| Part 3: Building the MCP Client | MCP Client | Create an interactive CLI client using LangChain4j |
┌─────────────────┐ MCP Protocol ┌──────────────────┐
│ AI Assistant │ ◄─────────────────►│ MCP Server │
│ (VS Code, etc.) │ (HTTP SSE) │ (Java/Quarkus) │
└─────────────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ Monkey Services │
│ (Business Logic) │
└──────────────────┘
The MCP server provides these monkey species tools:
- List Species: Get all available monkey species
- Species Details: Retrieve detailed information about specific species
- Random Species: Get a random monkey species
- Statistics: View dataset statistics and access counts
- Java 21: Modern Java features and performance
- Quarkus: Supersonic Subatomic Java Framework
- LangChain4j: Java framework for building LLM applications
- Ollama: Local LLM runtime
- Maven: Build and dependency management
- PicoCLI: Command-line interface framework
By completing this tutorial, you will:
- Understand MCP protocol and its benefits
- Build production-ready MCP servers with Quarkus
- Create MCP clients using LangChain4j
- Integrate with local LLMs using Ollama
- Apply AI-assisted development with GitHub Copilot
monkey-mcp-java/
├── 00_PROJECT_SETUP.md # Prerequisites and environment setup
├── 01_MCP_SERVER.md # MCP Server implementation guide
├── 02_MCP_CLIENT.md # MCP Client implementation guide
├── monkey-mcp-server/ # Quarkus MCP server project
│ ├── src/main/java/ # Java source code
│ └── pom.xml # Maven dependencies
└── monkey-mcp-client/ # LangChain4j MCP client project
├── src/main/java/ # Java source code
└── pom.xml # Maven dependencies
This is an educational project designed to teach MCP implementation in Java. Contributions, suggestions, and improvements are welcome!
This project is licensed under the MIT License - see the LICENSE file for details.
Start your MCP journey: Part 1 - Prerequisites and Setup →