A Java application that demonstrates how to use LangChain4j to connect to an MCP (Model Context Protocol) calculator service with GitHub Models integration.

Prerequisites

Java 21 or higher
Maven 3.6+ (or use the included Maven wrapper)
A GitHub account with access to GitHub Models
An MCP calculator service running on http://localhost:8080

Getting the GitHub Token

This application uses GitHub Models which requires a GitHub personal access token. Follow these steps to get your token:

1. Access GitHub Models

Go to GitHub Models
Sign in with your GitHub account
Request access to GitHub Models if you haven't already

2. Create a Personal Access Token

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Click "Generate new token" → "Generate new token (classic)"
Give your token a descriptive name (e.g., "MCP Calculator Client")
Set expiration as needed
Select the following scopes:
- repo (if accessing private repositories)
- user:email
Click "Generate token"
Important: Copy the token immediately - you won't be able to see it again!

3. Set the Environment Variable

On Windows (Command Prompt):

set GITHUB_TOKEN=your_github_token_here

On Windows (PowerShell):

$env:GITHUB_TOKEN="your_github_token_here"

On macOS/Linux:

export GITHUB_TOKEN=your_github_token_here

Setup and Installation

Clone or navigate to the project directory
Install dependencies:
```
mvnw clean install
```
Or if you have Maven installed globally:
```
mvn clean install
```
Set up the environment variable (see "Getting the GitHub Token" section above)
Start the MCP Calculator Service: Make sure you have chapter 1's MCP calculator service running on http://localhost:8080/sse. This should be running before you start the client.

Running the Application

mvnw clean package
java -jar target\calculator-llm-client-0.0.1-SNAPSHOT.jar

What the Application Does

The application demonstrates three main interactions with the calculator service:

Addition: Calculates the sum of 24.5 and 17.3
Square Root: Calculates the square root of 144
Help: Shows available calculator functions

Expected Output

When running successfully, you should see output similar to:

The sum of 24.5 and 17.3 is 41.8.
The square root of 144 is 12.
The calculator service provides the following functions: add, subtract, multiply, divide, sqrt, power...

Troubleshooting

Common Issues

"GITHUB_TOKEN environment variable not set"
- Make sure you've set the GITHUB_TOKEN environment variable
- Restart your terminal/command prompt after setting the variable
"Connection refused to localhost:8080"
- Ensure the MCP calculator service is running on port 8080
- Check if another service is using port 8080
"Authentication failed"
- Verify your GitHub token is valid and has the correct permissions
- Check if you have access to GitHub Models
Maven build errors
- Ensure you're using Java 21 or higher: java -version
- Try cleaning the build: mvnw clean

Debugging

To enable debug logging, add the following JVM argument when running:

java -Dlogging.level.dev.langchain4j=DEBUG -jar target\calculator-llm-client-0.0.1-SNAPSHOT.jar

Configuration

The application is configured to:

Use GitHub Models with the gpt-4.1-nano model
Connect to MCP service at http://localhost:8080/sse
Use a 60-second timeout for requests
Enable request/response logging for debugging

Dependencies

Key dependencies used in this project:

LangChain4j: For AI integration and tool management
LangChain4j MCP: For Model Context Protocol support
LangChain4j GitHub Models: For GitHub Models integration
Spring Boot: For application framework and dependency injection

License

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