---
slug: "carsmcpserver"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/amarpreetbhatia/carsmcpserver@master/README.md"
repo: "https://github.com/amarpreetbhatia/carsmcpserver"
source_file: "README.md"
branch: "master"
---
# Cars MCP Server

This is an MCP (Model Context Protocol) server built using **Spring AI**. The project demonstrates the use of Spring AI's `ToolCallback` API to expose tools for interacting with a list of cars, which represents Amarpreet's wishlist.

## Demo

[Demo Video](https://vimeo.com/1072438044/487e869ed4?ts=0&share=copy)

## Project Structure

The project is organized as follows:

- **`src/main/java/com/amarpreet/carsmcpserver/`**

  - `CarsmcpserverApplication.java`: The main entry point of the Spring Boot application. It initializes the application and registers the `ToolCallback` beans using the `CarService` class.
  - `Car.java`: A simple `record` class representing a car with two fields: `modelName` and `buildYear`.
  - `CarService.java`: A service class that provides methods to interact with the list of cars. These methods are exposed as tools using the `ToolCallback` API.

- **`src/main/resources/application.properties`**: Contains configuration properties for the Spring Boot application.

- **`src/test/java/com/amarpreet/carsmcpserver/`**
  - `CarsmcpserverApplicationTests.java`: Contains a basic test to ensure the application context loads correctly.

## ToolCallback API

The `ToolCallback` API is used to expose methods from the `CarService` class as tools. These tools can be invoked programmatically or through an AI-driven interface. The `CarsmcpserverApplication` class registers these tools using the `ToolCallbacks.from()` method.

### Tool Registration

In `CarsmcpserverApplication.java`:

```java
@Bean
public List<ToolCallback> amarpreetTools(CarService carService) {
    return List.of(ToolCallbacks.from(carService));
}
```

This registers all methods annotated with `@Tool` in the `CarService` class as `ToolCallback` instances.

## CarService

The `CarService` class is the core of this application. It manages a list of cars and provides the following methods:

### Methods in CarService

#### `getCars()`

- **Tool Name**: `get_cars`
- **Description**: Retrieves the list of cars in Amarpreet's wishlist.
- **Return Type**: `List<Car>`

#### `getCar(String name)`

- **Tool Name**: `get_car_by_name`
- **Description**: Finds a car by its model name.
- **Parameters**:
  - `name` - The model name to search for.
- **Return Type**: `Car` (or `null` if not found)

#### `getCarByYear(Integer year)`

- **Tool Name**: `get_car_by_years`
- **Description**: Finds a car by its build year.
- **Parameters**:
  - `year` - The build year to search for.
- **Return Type**: `Car` (or `null` if not found)

## Initialization

The `CarService` class initializes a list of cars during application startup using the `@PostConstruct` annotation:

```@PostConstruct
public void init() {
    log.info("Initializing cars MCP server...");
    cars.addAll(List.of(
        new Car("BMW Neue Klasse", 2025),
        new Car("Ferrari EV", 2025),
        new Car("Mercedes AMG 4dr EV", 2025),
        new Car("Porsche 718 Boxster", 2025)
    ));
}
```

## How to Run

### Build the project using Maven:

```bash
mvn clean install
```

### Run the application:

```bash
java -jar target/carsmcpserver-0.0.1-SNAPSHOT.jar
```

## Configuration

The application can be configured using the `application.properties` file located in `src/main/resources`. Key properties include:

- `spring.application.name`: The name of the application.
- `spring.main.web-application-type`: Set to `none` for a non-web application.
- `spring.ai.mcp.server`: The name of the MCP server.
- `spring.ai.mcp.version`: The version of the MCP server.