turkish-food-ai-agent - GitLite

KO | EN

gitlite — search

#anthropic #json #reactjs #framework #tailwindcss #shell #rag #artificial-intelligence #cloud-native #open-source

turkish-food-ai-agent

(★ 9)

Turkish Traditional Food AI Agent (Java 25, Spring Boot, Spring AI, MCP, Docker, Kubernetes, Github Actions)

File Explorer

ZIP Download

- - food-agent-api-ci-cd.yml
  - food-mcp-server-ci-cd.yml
  - README.md
- Dockerfile
- pom.xml
- Dockerfile
- pom.xml
- 00-namespace.yaml
- 01-agent-config.yaml
- 02-gemini-secret.example.yaml
- 03-food-mcp-server.yaml
- 04-food-agent-api.yaml
- kustomization.yaml
- README.md
- README.md
- Turkish-Food-AI-Agent-k8s-nodeport.postman_environment.json
- Turkish-Food-AI-Agent-local-docker.postman_environment.json
- Turkish-Food-AI-Agent.postman_collection.json
- 1.PNG
- 2.PNG
- 3.PNG
- 4.PNG
- main_image.png
.dockerignore
.gitignore
docker-compose.yml
pom.xml
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
    <img src="screenshots/main_image.png" alt="Turkish Traditional Food AI Agent with MCP and Spring AI" width="700" height="450">
</p>

## Information

This project demonstrates a small **AI Agent** architecture with **Java 25**, **Spring Boot**, **Spring AI**, **MCP**, Docker, Kubernetes, GitHub Actions, and Postman.

The domain is **Turkish traditional food recommendation**. The important point is that the agent does **not** return a raw dump of food names. Instead, it uses a curated MCP tool server to select a short, contextual answer based on the user's request.

Example user intent:

```text
I want a light vegetarian Turkish dinner from the Aegean region. Please include cultural notes.
```

The Agent API calls MCP tools, receives curated food candidates, optionally asks Gemini to format the final response, and returns a clean JSON response.

---

## Project Documents

Use these documents for details that should not make the main README too long.

| Document | Purpose |
|---|---|
| [Kubernetes README](k8s/README.md) | Minikube deployment, Kustomize usage, namespace, services, NodePort, and port-forwarding |
| [Postman README](postman/README.md) | Postman collection import, local/Docker environment, Kubernetes environment, and request list |
| [GitHub Actions README](.github/workflows/README.md) | CI/CD workflow files, Docker Hub secrets, image publishing, and trigger behavior |

---

## Core Agent Rules

| Rule | Description |
|---|---|
| No dump list | The agent must not return the full food catalog. |
| Curated output | The answer should contain only a short, relevant set of dishes. |
| MCP first | Food knowledge comes from the MCP server before the final answer is generated. |
| Bilingual support | English requests should return English answers; Turkish requests should return Turkish answers. |
| Region aliases | `Aegean` and `Ege` should map to the same curated Aegean/Ege knowledge. |
| Dessert handling | If `includeDessert=true`, the response should include a dessert when a suitable candidate exists. |
| Safe fallback | If Gemini is disabled, invalid, or quota-limited, the API returns an MCP local fallback response. |
| API key safety | The Gemini key must be passed by environment variable, Docker `.env`, or Kubernetes Secret. |

---

## Agent Process

### 1. User Request

Client sends a request to:

```http
POST /api/agents/turkish-food/ask
```

Example:

```json
{
  "question": "I want a light vegetarian Turkish dinner from the Aegean region. Please include cultural notes.",
  "region": "Aegean",
  "occasion": "summer guest dinner",
  "dietaryPreference": "vegetarian",
  "maxCookingMinutes": 90,
  "includeDessert": true
}
```

### 2. MCP Tool Selection

The Agent API decides which MCP tool should be called.

For a recommendation request, it calls:

```text
recommend_traditional_turkish_foods
```

### 3. Curated MCP Result

The MCP server scores and filters the curated Turkish food catalog by:

- region
- occasion
- dietary preference
- cooking time
- dessert preference
- requested count

### 4. Gemini Finalization

If Gemini is enabled, the Agent API sends the curated MCP result as context to Gemini.

Gemini is used to produce a natural final answer, not to invent the food catalog.

### 5. Fallback Handling

If Gemini fails, the response is still usable:

```json
{
  "source": "mcp-local-fallback",
  "fallbackUsed": true,
  "fallbackReason": "Gemini quota/rate limit exceeded. MCP local fallback was used."
}
```

---

## Architecture Overview

```mermaid
flowchart LR
    U[User / Postman] --> A[food-agent-api\nSpring Boot REST API]
    A --> M[food-mcp-server\nMCP Streamable HTTP]
    M --> C[Curated Turkish Food Catalog]
    A --> G[Gemini via Spring AI]
    G --> A
    A --> U
```

### Services

| Service | Module | Port | Responsibility |
|---|---|---:|---|
| MCP Server | `food-mcp-server` | `9090` | Exposes Turkish food tools through MCP Streamable HTTP |
| Agent API | `food-agent-api` | `8080` | Exposes REST API, calls MCP tools, optionally calls Gemini |

### Runtime URLs

| Runtime | Agent API | MCP Server |
|---|---|---|
| Maven local | `http://localhost:8080` | `http://localhost:9090/mcp` |
| Docker Compose | `http://localhost:8080` | `http://food-mcp-server:9090/mcp` inside Docker network |
| Kubernetes via Minikube | Use `minikube service food-agent-api -n turkish-food-ai --url` | Use `minikube service food-mcp-server -n turkish-food-ai --url` |

---

## Domain Model

### Food Profile

Represents a curated traditional Turkish dish.

Typical fields:

- `name`
- `category`
- `regions`
- `dietaryTags`
- `occasions`
- `cookingMinutes`
- `culturalNote`
- `whyItFits`
- `pairings`

### Food Suggestion

Represents the short result returned from an MCP recommendation tool.

Typical fields:

- `dish`
- `category`
- `reason`
- `culturalNote`
- `pairings`

### Menu Plan

Represents a small generated Turkish menu with starter, main course, and optional dessert.

---

## MCP Tools

| Tool | Description |
|---|---|
| `recommend_traditional_turkish_foods` | Returns a short curated set of food suggestions based on region, occasion, diet, cooking time, and dessert preference. |
| `explain_traditional_turkish_dish` | Explains one traditional dish with cultural context, category, dietary tags, estimated cooking time, and pairings. |
| `build_turkish_menu_plan` | Builds a small menu plan with starter, main, and optional dessert. |

The Agent API uses MCP programmatically instead of registering MCP tools as Gemini function declarations. This keeps the MCP architecture while avoiding provider-specific tool-schema issues.

---

## API Documentation

### Base URL

```text
http://localhost:8080
```

### Endpoint Table

| Module | Method | Endpoint | Description |
|---|---|---|---|
| Agent API | POST | `/api/agents/turkish-food/ask` | Ask the Turkish Food AI Agent for a curated answer. |
| Agent API | GET | `/actuator/health` | Check Agent API health. |
| MCP Server | GET | `/actuator/health` | Check MCP Server health. |
| MCP Server | POST | `/mcp` | MCP Streamable HTTP endpoint used internally by Agent API. |

### Request Body

| Field | Required | Example | Description |
|---|---:|---|---|
| `question` | Yes | `I want a light vegetarian Turkish dinner...` | Natural language user request. |
| `region` | No | `Aegean`, `Ege`, `Black Sea`, `Karadeniz` | Region/city in English or Turkish. |
| `occasion` | No | `summer guest dinner` | Occasion, mood, or meal context. |
| `dietaryPreference` | No | `vegetarian`, `vejetaryen`, `vegan` | Dietary preference. |
| `maxCookingMinutes` | No | `90` | Optional cooking time limit. Valid range: `1` to `600`. |
| `includeDessert` | No | `true` | Whether dessert should be included when available. |

### Successful Response

```json
{
  "answer": "For a light vegetarian Aegean dinner, İmam Bayıldı is a strong fit...",
  "source": "gemini",
  "fallbackUsed": false,
  "fallbackReason": null,
  "generatedAt": "2026-05-04T21:14:32.6021888"
}
```

### Fallback Response

```json
{
  "answer": "Based on your request, here is a short curated Turkish food suggestion...",
  "source": "mcp-local-fallback",
  "fallbackUsed": true,
  "fallbackReason": "Gemini is unavailable. MCP local fallback was used.",
  "generatedAt": "2026-05-04T21:14:32.6021888"
}
```

### Validation Error Response

Validation errors are localized by `Accept-Language`.

English:

```http
Accept-Language: en
```

```json
{
  "status": 400,
  "errorCode": "VALIDATION_ERROR",
  "message": "Request validation failed. Please check the fieldErrors array for details.",
  "locale": "en",
  "fieldErrors": [
    {
      "field": "question",
      "message": "question must not be blank"
    }
  ]
}
```

Turkish:

```http
Accept-Language: tr
```

```json
{
  "status": 400,
  "errorCode": "VALIDATION_ERROR",
  "message": "İstek doğrulaması başarısız oldu. Detaylar için fieldErrors alanını kontrol edin.",
  "locale": "tr",
  "fieldErrors": [
    {
      "field": "question",
      "message": "question alanı boş olmamalıdır"
    }
  ]
}
```

---

## Example Requests

### English Request

```bash
curl -X POST http://localhost:8080/api/agents/turkish-food/ask \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "question": "I want a light vegetarian Turkish dinner from the Aegean region. Please include cultural notes.",
    "region": "Aegean",
    "occasion": "summer guest dinner",
    "dietaryPreference": "vegetarian",
    "maxCookingMinutes": 90,
    "includeDessert": true
  }'
```

Expected behavior:

- Answer language: English
- Region alias: `Aegean` maps to `Ege`
- Dessert is included when a suitable dessert exists
- The result is curated, not a raw food list

### Turkish Request

```bash
curl -X POST http://localhost:8080/api/agents/turkish-food/ask \
  -H "Content-Type: application/json" \
  -H "Accept-Language: tr" \
  -d '{
    "question": "Ege bölgesinden hafif ve vejetaryen bir Türk akşam yemeği öner. Kültürel notları da ekle.",
    "region": "Ege",
    "occasion": "yaz misafir akşam yemeği",
    "dietaryPreference": "vejetaryen",
    "maxCookingMinutes": 90,
    "includeDessert": true
  }'
```

Expected behavior:

- Answer language: Turkish
- Region value: `Ege`
- Dessert is included when a suitable dessert exists
- The response explains cultural context

---

## Postman

Postman files are under:

```text
postman/
├── Turkish-Food-AI-Agent.postman_collection.json
├── Turkish-Food-AI-Agent-local-docker.postman_environment.json
├── Turkish-Food-AI-Agent-k8s-nodeport.postman_environment.json
└── README.md
```

Import the collection and one environment file into Postman.

More details: [Postman README](postman/README.md)

---

## Technologies

- Java 25
- Spring Boot 3.5.14
- Spring AI 1.1.5
- MCP Streamable HTTP
- Google Gemini through Spring AI Google GenAI
- Maven multi-module project
- Docker
- Docker Compose
- Kubernetes / Minikube
- Kustomize
- GitHub Actions
- Postman
- Jakarta Validation
- Spring Boot Actuator

---

## Environment Variables

### How to Get a Gemini API Key

You can get a Gemini API key from **Google AI Studio** and use it as `GEMINI_API_KEY` in this Spring AI project.

#### Step 1 — Open Google AI Studio

Go to Google AI Studio and sign in with your Google account.

Use this page:

```text
https://aistudio.google.com/app/apikey
```

This is the Google AI Studio API key page where you can create and manage Gemini API keys.

#### Step 2 — Accept Terms

On first login, Google may ask you to:

- accept the Terms of Service
- confirm your country/region
- create or select a Google Cloud project

For new users, Google AI Studio may create a default Google Cloud project and API key automatically after the setup process.

#### Step 3 — Create an API Key

On the API Keys page, click:

```text
Create API key
```

Then choose one of these options:

```text
Create API key in new project
```

or:

```text
Create API key in existing project
```

For a local Spring Boot demo project, using a new project is usually simpler.

#### Step 4 — Copy the Key

After creating it, copy the generated key.

It usually looks like this:

```text
AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Do not commit this key to GitHub. Keep it only in your local `.env` file, Docker environment, Kubernetes Secret, or GitHub Actions secret.

Create a local `.env` file.

```env
GEMINI_API_KEY=YOUR_REAL_GEMINI_API_KEY

SPRING_AI_MODEL_CHAT=google-genai
AGENT_GEMINI_ENABLED=true
AGENT_LOCAL_FALLBACK_ENABLED=true

GEMINI_MODEL=gemini-3.1-flash-lite-preview
GEMINI_MAX_OUTPUT_TOKENS=8192
GEMINI_THINKING_BUDGET=0
```

| Variable | Description |
|---|---|
| `GEMINI_API_KEY` | Google AI Studio Gemini API key. |
| `SPRING_AI_MODEL_CHAT` | Use `google-genai` to enable Gemini model auto-configuration. Use `none` for MCP-only mode. |
| `AGENT_GEMINI_ENABLED` | Enables/disables Gemini final answer generation. |
| `AGENT_LOCAL_FALLBACK_ENABLED` | Enables fallback answer from MCP result if Gemini fails. |
| `GEMINI_MODEL` | Gemini model id used by Spring AI. |
| `GEMINI_MAX_OUTPUT_TOKENS` | Maximum visible output token budget. |
| `GEMINI_THINKING_BUDGET` | Thinking budget for models that support it. `0` disables thinking for this simple agent. |

### MCP-only mode

Use this when Gemini quota is unavailable or you want to test MCP without external AI calls.

```env
SPRING_AI_MODEL_CHAT=none
AGENT_GEMINI_ENABLED=false
AGENT_LOCAL_FALLBACK_ENABLED=true
```

---

## Run the Application

### Maven Run

Start the MCP server:

```bash
mvn -pl food-mcp-server spring-boot:run
```

Start the Agent API in another terminal:

```bash
mvn -pl food-agent-api spring-boot:run
```

Health checks:

```bash
curl http://localhost:9090/actuator/health
curl http://localhost:8080/actuator/health
```

### Docker Compose Run

Create `.env` first, then run:

```bash
docker compose up --build
```

Services:

| Service | Container | External Port |
|---|---|---:|
| MCP Server | `food-mcp-server` | `9090` |
| Agent API | `food-agent-api` | `8080` |

Test:

```bash
curl -X POST http://localhost:8080/api/agents/turkish-food/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "I want a light vegetarian Turkish dinner from the Aegean region. Please include cultural notes.",
    "region": "Aegean",
    "occasion": "summer guest dinner",
    "dietaryPreference": "vegetarian",
    "maxCookingMinutes": 90,
    "includeDessert": true
  }'
```

Stop:

```bash
docker compose down
```

### Kubernetes / Minikube Run

Kubernetes files are under `k8s/`.

More details: [Kubernetes README](k8s/README.md)

## GitHub Actions CI/CD

Workflow files are under:

```text
.github/workflows/
├── food-mcp-server-ci-cd.yml
├── food-agent-api-ci-cd.yml
└── README.md
```

The workflows follow a service-based CI/CD approach:

- checkout source code
- set up Java 25 with Temurin
- use Maven cache
- package the selected module
- run verification
- log in to Docker Hub
- build and push Docker images

Required GitHub secrets:

| Secret | Purpose |
|---|---|
| `DOCKER_USERNAME` | Docker Hub username |
| `DOCKER_PASSWORD` | Docker Hub password or access token |
| `GEMINI_API_KEY` | Optional for build/test environments that require the property |

More details: [GitHub Actions README](.github/workflows/README.md)

---

### 📸 Screenshots

<details>
<summary>Click here to show the screenshots of project</summary>
    <p> Figure 1 </p>
    <img src ="screenshots/1.PNG">
    <p> Figure 2 </p>
    <img src ="screenshots/2.PNG">
    <p> Figure 3 </p>
    <img src ="screenshots/3.PNG">
    <p> Figure 4 </p>
    <img src ="screenshots/4.PNG">
</details>

---

### Contributors

- [Sercan Noyan Germiyanoğlu](https://github.com/Rapter1990)