### Setup and Configuration Commands

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/brave/README.md

Commands for setting up the project, including installing npx, cloning the repository, setting API keys, and building the application.

```bash
npm install -g npx
git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/brave
export OPENAI_API_KEY='your-openai-api-key-here'
export BRAVE_API_KEY='your-brave-api-key-here'
./mvnw clean install
```

--------------------------------

### JBang Installation and Environment Setup

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Instructions for installing JBang and setting essential environment variables like API keys for services such as OpenAI and Brave.

```shell
# Install JBang
curl -Ls https://sh.jbang.dev | bash -s - app setup
# Add to PATH
echo 'export PATH="$HOME/.jbang/bin:$PATH"' >> ~/.bashrc
```

```shell
# Set required API keys
export OPENAI_API_KEY="your-key-here"
export BRAVE_API_KEY="your-brave-key"  # if using Brave examples
```

--------------------------------

### SQLite Example Dependencies and Setup

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/integration-testing-plan-v3.1.md

Details on handling database setup requirements and configuring environment dependencies, such as uvx and SQLite MCP server, for the simple SQLite example.

```bash
# Ensure uvx is installed and running
# uvx start

# Ensure SQLite MCP server is running
# sqlite-mcp-server start

# Install necessary Java dependencies (example using Maven)
# mvn install:install-file -Dfile=path/to/sqlite-jdbc.jar -DgroupId=org.xerial -DartifactId=sqlite-jdbc -Dversion=3.36.0

# Run the example (assuming a JBang script or similar)
# jbang scripts/run_sqlite_example.java
```

--------------------------------

### Setup Brave Search Chatbot Environment

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/web-search/brave-chatbot/README.md

Provides bash commands for setting up the Brave Search Chatbot example, including installing npx, cloning the repository, setting API keys, and building the application.

```bash
npm install -g npx
git clone https://github.com/spring-projects/spring-ai-examples.git
cd spring-ai-examples/model-context-protocol/web-search/brave-chatbot
export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
export BRAVE_API_KEY='your-brave-api-key-here'
./mvnw clean install
```

--------------------------------

### Kotlin Spring AI Example: Hello World

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/CLAUDE.md

A basic 'Hello World' example demonstrating the setup and usage of Spring AI in a Kotlin application.

```kotlin
package com.example.springaiapp

import org.springframework.ai.chat.client.ChatClient
import org.springframework.boot.ApplicationRunner
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.context.annotation.Bean

@SpringBootApplication
class AiKotlinApplication {

    @Bean
    fun runner(chatClient: ChatClient): ApplicationRunner {
        return ApplicationRunner {
            val prompt = "Hello AI!"
            val response = chatClient.prompt().client("$prompt").call().content().toString()
            println(response)
        }
    }

}

fun main(args: Array<String>) {
    runApplication<AiKotlinApplication>(*args)
}
```

--------------------------------

### Setup Brave Search Example

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/web-search/brave-starter/README.md

This section provides bash commands for setting up the Spring AI MCP Brave Search example. It includes cloning the repository, navigating to the project directory, setting environment variables for API keys, and building the application using Maven.

```bash
npm install -g npx

git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/brave-starter

export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
export BRAVE_API_KEY='your-brave-api-key-here'

./mvnw clean install
```

--------------------------------

### ExampleInfo.json: MCP SQLite Example Configuration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/integration-testing-plan-v3.1.md

A sample `ExampleInfo.json` configuration for an MCP SQLite example, including setup commands for database creation.

```json
{
  "timeoutSec": 300,
  "successRegex": ["Connected to database", "Query results:", "products available"],
  "requiredEnv": ["OPENAI_API_KEY"],
  "setupCommands": ["./create-database.sh"]
}
```

--------------------------------

### Running the Example (Bash)

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/dynamic-tool-update/README.md

Instructions for running the Spring AI dynamic tool update example. It requires starting the server application first, followed by the client application in a separate terminal.

```bash
# Start the server application:
cd server
./mvnw spring-boot:run

# In a separate terminal, start the client application:
cd client
./mvnw spring-boot:run
```

--------------------------------

### Environment Variable Setup

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/client-starter/starter-default-client/README.md

Sets the necessary environment variables for the application to connect to external services like Anthropic and Brave Search.

```bash
export ANTHROPIC_API_KEY=your-api-key

# For the Brave Search MCP server
export BRAVE_API_KEY=your-brave-api-key
```

--------------------------------

### Starting MCP Annotations Server (Bash)

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/mcp-annotations-server/README.md

Command to start the MCP annotations server, which is a prerequisite for the SSE client connection example.

```bash
java -jar mcp-annotations-server-0.0.1-SNAPSHOT.jar
```

--------------------------------

### Developer Workflow Steps

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/integration-testing-plan-v3.1.md

A guide for developers on how to add new examples, write tests, and integrate them into the project. It covers the process from creating a new example to adding unit and integration tests, and finally verifying CI integration.

```markdown
1. **Create new example**: Follow standard Spring Boot conventions
2. **Add unit tests**: Place in `src/test/java/` for simple functionality testing
3. **Determine complexity**: Does it need external services, long timeouts, or complex verification?
4. **Add integration test** (if complex):
   - Create `integration-tests/` directory
   - Add `ExampleInfo.json` with appropriate configuration
   - Create `Run*.java` JBang launcher
   - Test locally: `jbang integration-tests/Run*.java`
5. **Verify CI integration**: Push and check GitHub Actions results

```

--------------------------------

### Running Multiple Integration Tests

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Bash commands to run integration tests for multiple examples, using a filter to specify which examples to include.

```bash
# From repository root
python3 scripts/run_integration_tests.py --filter="kotlin"
python3 scripts/run_integration_tests.py --filter="agentic-patterns"
```

--------------------------------

### Running Single Integration Test

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Commands to run a single integration test for a specific example, including navigating to the example directory and executing the test using JBang or Maven.

```bash
# Navigate to example directory  
cd kotlin/kotlin-hello-world

# Run integration test directly
jbang integration-tests/RunKotlinHelloWorld.java

# Or run unit tests
./mvnw test
```

--------------------------------

### JBang Setup using GitHub Action

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/learnings/phase-3b-workflow-optimization.md

Replaces manual JBang installation with the official `jbangdev/setup-jbang` action for cleaner and more reliable setup in GitHub Actions workflows.

```yaml
      - name: Setup JBang
        uses: jbangdev/setup-jbang@v0.119.0
```

--------------------------------

### Build the Spring AI Application

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/client-starter/starter-webflux-client/README.md

Builds the Spring AI application using the Maven Wrapper. This command cleans the project and installs the artifacts.

```bash
./mvnw clean install
```

--------------------------------

### Set up JBang Action

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/github-actions-ci-plan.md

Configures the JBang environment using the official jbangdev/setup-jbang GitHub Action. This replaces manual installation steps.

```yaml
- name: Set up JBang
    uses: jbangdev/setup-jbang@v0.119.0
```

--------------------------------

### Manual Integration Test Creation

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Steps to manually create an integration test, including directory structure, configuration file (ExampleInfo.json), and a JBang launcher.

```bash
# Create integration-tests directory
mkdir your-example/integration-tests
```

--------------------------------

### Scaffolding Integration Tests with AI Validation

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Bash commands to scaffold integration tests for Spring AI examples, demonstrating how to enable AI validation with different modes and complexities.

```bash
# Enable AI validation by default (hybrid mode)
python3 scripts/scaffold_integration_test.py kotlin/kotlin-hello-world

# Complex workflow with primary AI validation
python3 scripts/scaffold_integration_test.py agentic-patterns/chain-workflow --complexity complex --ai-mode primary

# MCP example with client-server validation
python3 scripts/scaffold_integration_test.py model-context-protocol/weather/server --complexity mcp

# Disable AI validation (regex only)
python3 scripts/scaffold_integration_test.py simple-example --no-ai-validation
```

--------------------------------

### Live Progress Streaming

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Enable real-time output and progress indicators for long-running integration tests by using the `--stream` flag.

```bash
# Stream live output with progress indicators
python3 scripts/run_integration_tests.py --stream --filter="helloworld"
```

--------------------------------

### Build and Run Spring AI Examples

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/CLAUDE.md

Commands for building the entire project, running specific examples, and building/running individual modules using Maven Wrapper.

```bash
./mvnw clean package
./run-example.sh <project-directory-name>
cd <module-directory>
./mvnw clean package
./mvnw spring-boot:run
mvn clean package
```

--------------------------------

### Install AI Validator Dependencies

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

Command to install the necessary Python dependencies for the AI validator script, typically used when encountering 'No such file or directory' errors.

```bash
pip3 install -r integration-testing/ai-validator/requirements.txt
```

--------------------------------

### Claude Code CLI Installation

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/GITHUB_ACTIONS_SETUP.md

This JavaScript snippet (used in npm command) shows how to install the Claude Code CLI globally, which is required for AI validation in the CI process.

```shell
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Start Docker Services

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/brave-docker-agents-gateway/README.md

Starts the necessary Docker services for the Brave Search MCP Server. Ensure Docker Desktop or Docker Engine with Docker Compose CLI is installed and running.

```bash
docker compose up
```

--------------------------------

### Scaffold Integration Tests

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Create new integration test structures using the scaffolding script. Supports different complexity levels like 'complex' and 'mcp' for specific setups.

```bash
# Simple example
python3 scripts/scaffold_integration_test.py kotlin/kotlin-hello-world

# Complex example with longer timeout
python3 scripts/scaffold_integration_test.py agentic-patterns/chain-workflow --complexity complex

# MCP example with database setup
python3 scripts/scaffold_integration_test.py model-context-protocol/sqlite/simple --complexity mcp
```

--------------------------------

### Manual STDIO Client Setup (Java)

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-webmvc-server/README.md

Demonstrates how to manually set up a Spring AI client using the STDIO transport. This involves building server parameters and creating a synchronous MCP client.

```java
var stdioParams = ServerParameters.builder("java")
    .args("-Dspring.ai.mcp.server.stdio=true",
          "-Dspring.main.web-application-type=none",
          "-Dspring.main.banner-mode=off",
          "-Dlogging.pattern.console=",
          "-jar",
          "target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar")
    .build();

var transport = new StdioClientTransport(stdioParams);
var client = McpClient.sync(transport).build();
```

--------------------------------

### Docker Compose Setup and Cleanup Commands

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/TROUBLESHOOTING.md

Defines shell commands to start Docker Compose services in detached mode and later stop them, commonly used for managing external dependencies in integration tests.

```json
{
  "setupCommands": [
    "docker-compose up -d",
    "sleep 10"
  ],
  "cleanupCommands": [
    "docker-compose down"
  ]
}
```

--------------------------------

### Create Learnings Document

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/github-actions-ci-plan.md

This command creates a markdown file to document learnings from Phase 1 of the CI/CD implementation.

```bash
touch integration-testing/learnings/phase-1-script-renaming.md
```

--------------------------------

### Clone Repository and Set Up Environment

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/sqlite/simple/README.md

Steps to clone the Spring AI examples repository and navigate to the specific demo application directory. It also includes setting the OpenAI API key as an environment variable.

```bash
git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/sqlite/simple
export OPENAI_API_KEY='your-api-key-here'
```

--------------------------------

### Example MCP Servers Configuration JSON

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/client-starter/starter-default-client/README.md

An example JSON file defining MCP server configurations for STDIO transport, including command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
      }
    }
  }
}
```

--------------------------------

### Build Application with Maven Wrapper

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/client-starter/starter-default-client/README.md

Builds the Spring AI application using the Maven Wrapper script.

```bash
./mvnw clean install
```

--------------------------------

### JBang Script Execution Example

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

A simple example of how to execute a JBang script from the command line. This assumes the script is saved as `RunExample.java` and is executable.

```bash
jbang RunExample.java
```

--------------------------------

### Success Pattern Examples

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Illustrates different success patterns to be used in `ExampleInfo.json` for various types of Spring AI examples, such as basic chat, MCP SQLite, and Agentic Workflows.

```json
{
  "Basic Chat": ["Joke:", "Setup:", "Punchline:"]
}
{
  "MCP SQLite": ["Connected to database", "Query results:", "products available"]
}
{
  "Agentic Workflow": ["EVALUATION:\\s+PASS", "Chain completed", "Final metrics"]
}
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/filesystem/README.md

Clones the spring-ai-examples repository from GitHub and navigates into the specific filesystem demo directory. This is a prerequisite for building and running the application.

```bash
git clone https://github.com/spring-projects/spring-ai-examples.git
cd model-context-protocol/filesystem
```

--------------------------------

### Troubleshooting JBang Installation

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/integration-testing-plan-v3.1.md

Provides commands to install JBang on macOS and Windows, addressing the 'JBang not found' error.

```bash
# Install JBang
curl -Ls https://sh.jbang.dev | bash -s - app setup
# Or use package manager
brew install jbang  # macOS
choco install jbang  # Windows
```

--------------------------------

### Simple Chat Example Integration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

An example configuration for integrating Spring AI into a simple chat application, specifying timeout, success regex, required environment variables, and AI validation settings.

```json
{
  "timeoutSec": 120,
  "successRegex": ["Spring AI Hello World!"],
  "requiredEnv": ["OPENAI_API_KEY"],
  "aiValidation": {
    "enabled": true,
    "validationMode": "primary",
    "expectedBehavior": "Application should accept user input 'tell me a joke' and return a coherent joke response with setup and punchline",
    "promptTemplate": "chat_example_validation"
  }
}
```

--------------------------------

### Run MCP Client with Boot Starter

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/README.md

Shows how to run an MCP client application using the Spring Boot starter. This example specifies the server connection details and user input via system properties.

```bash
java -Dspring.ai.mcp.client.stdio.connections.server1.command=java \
     -Dspring.ai.mcp.client.stdio.connections.server1.args=-jar,/Users/christiantzolov/Dev/projects/spring-ai-examples/model-context-protocol/weather/starter-stdio-server/target/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar \
     -Dai.user.input='What is the weather in NY?' \
     -Dlogging.pattern.console= \
     -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar
```

--------------------------------

### Python Setup using GitHub Action

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/learnings/phase-3b-workflow-optimization.md

Configures Python 3.11 using the `actions/setup-python` action, preparing the environment for any Python-based tooling needs within the workflow.

```yaml
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
```

--------------------------------

### Complex Workflow Example Integration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

An example configuration for integrating Spring AI into a complex workflow, detailing timeout, success regex, required environment variables, and AI validation with specific success criteria.

```json
{
  "timeoutSec": 300,
  "successRegex": ["EVALUATION: PASS", "Chain completed"],
  "requiredEnv": ["OPENAI_API_KEY"],
  "aiValidation": {
    "enabled": true,
    "validationMode": "hybrid",
    "readmeFile": "../README.md",
    "expectedBehavior": "Execute 4-step data transformation pipeline: extract values, standardize format, sort data, create markdown table",
    "promptTemplate": "workflow_validation",
    "successCriteria": {
      "expectedSteps": 4,
      "outputFormat": "markdown_table",
      "evaluationRequired": true
    }
  }
}
```

--------------------------------

### Running Client with STDIO Configuration (Bash)

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/mcp-annotations-server/README.md

Demonstrates how to run the MCP client starter using a JSON configuration file for STDIO transport. It includes setting the server configuration path, user input, and logging pattern.

```bash
java -Dspring.ai.mcp.client.stdio.servers-configuration=file:mcp-servers-config.json \
 -Dai.user.input='What is the weather in NY?' \
 -Dlogging.pattern.console= \
 -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar
```

--------------------------------

### Build Project with Maven

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-webflux-server/README.md

Command to build the project using Maven, cleaning the project and installing artifacts while skipping tests.

```bash
./mvnw clean install -DskipTests
```

--------------------------------

### GitHub Actions Workflow Setup

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/GITHUB_ACTIONS_SETUP.md

This snippet outlines the core structure of the GitHub Actions workflow file, including triggers, environment setup for Java, JBang, and Python, and caching strategies for dependencies.

```yaml
name: Integration Tests (Manual)

on:
  workflow_dispatch:
    inputs:
      spring_ai_version:
        description: 'Spring AI version to test'
        required: true
        default: '1.0.1'
      test_filter:
        description: 'Optional test filter'
        required: false

jobs:
  integration_tests:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: maven

    - name: Set up JBang
      uses: jbangdev/setup-jbang@v0.119.0

    - name: Set up Python 3.11
      uses: actions/setup-python@v5
      with:
        python-version: '3.11'

    - name: Cache JBang
      uses: actions/cache@v4
      with:
        path: ~/.jbang/cache
        key: ${{ runner.os }}-jbang-${{ hashFiles('**/jbang-config.json') }}
        restore-keys: |
          ${{ runner.os }}-jbang-

    - name: Install Claude Code CLI
      run: npm install -g @anthropic-ai/claude-code

    - name: Update Spring AI Version
      run: | 
        ./scripts/update-spring-ai-version.sh ${{ inputs.spring_ai_version }}

    - name: Run Integration Tests
      run: | 
        ./scripts/run-integration-tests.sh ${{ inputs.test_filter }}

```

--------------------------------

### Build the Demo Application

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/filesystem/README.md

Builds the demo application using Maven. This command compiles the code, runs tests, and packages the application for execution.

```bash
./mvnw clean install
```

--------------------------------

### Install uvx Package Manager

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/sqlite/simple/README.md

Instructions for installing the uvx package manager, a prerequisite for running the application. Follow the official documentation for detailed steps.

```bash
# Follow installation instructions at:
https://docs.astral.sh/uv/getting-started/installation/
```

--------------------------------

### MCP Client-Server Configuration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

Configuration details for the MCP Client-Server example, including timeout, success regex, required environment variables, and AI validation settings.

```json
{
  "timeoutSec": 300,
  "successRegex": ["Connected", "Tools discovered"],
  "requiredEnv": ["OPENAI_API_KEY", "BRAVE_API_KEY"],
  "aiValidation": {
    "enabled": true,
    "validationMode": "hybrid",
    "readmeFile": "../README.md",
    "expectedBehavior": "MCP client should connect to servers, discover available tools (like Brave Search), handle user questions, and demonstrate tool usage through AI responses",
    "promptTemplate": "client_server_validation",
    "components": ["client", "mcp-servers"],
    "successCriteria": {
      "requiresUserInteraction": false,
      "expectedOutputTypes": ["tool_discovery", "ai_response", "tool_usage"]
    }
  }
}
```

--------------------------------

### RAG with Kotlin

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/plans/integration-testing-plan-v3.1.md

Demonstrates Retrieval-Augmented Generation (RAG) using Kotlin, including complexities related to database setup. This example is crucial for understanding data-intensive AI applications.

```kotlin
/*
 * Example for kotlin/rag-with-kotlin
 * Database setup complexity for RAG with Kotlin.
 */
// Placeholder for actual Kotlin code demonstrating the pattern.
```

--------------------------------

### AI Validation Configuration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Configuration for enabling and customizing AI validation within an example. It includes settings for timeout, success criteria, prompt templates, and validation modes.

```json
{
  "timeoutSec": 300,
  "successRegex": ["BUILD SUCCESS", "Started.*Application"],
  "requiredEnv": ["OPENAI_API_KEY"],
  "aiValidation": {
    "enabled": true,
    "validationMode": "hybrid",
    "readmeFile": "../README.md",
    "expectedBehavior": "Application should demonstrate chat functionality with coherent AI responses",
    "promptTemplate": "chat_example_validation",
    "components": ["client", "server"],
    "successCriteria": {
      "requiresUserInteraction": false,
      "expectedOutputTypes": ["conversation", "tool_usage"]
    }
  }
}
```

--------------------------------

### Get Weather Alerts Tool

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/README.md

Java code for the 'getAlerts' tool, which retrieves weather alerts for a given US state. Includes example usage with a client.

```java
@Tool(description = "Get weather alerts for a US state")
public String getAlerts(
    String state  // Two-letter US state code (e.g., CA, NY)
) {
    // Returns active alerts including:
    // - Event type
    // - Affected area
    // - Severity
    // - Description
    // - Safety instructions
}

// Example usage:
CallToolResult alerts = client.callTool(
    new CallToolRequest("getAlerts",
        Map.of("state", "NY")
    )
);
```

--------------------------------

### Build and Run Project

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/agentic-patterns/chain-workflow/README.md

Commands to build and run the Spring Boot application using Maven wrapper.

```bash
./mvnw clean install
./mvnw spring-boot:run
```

--------------------------------

### Get Weather Forecast Tool

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/README.md

Java code for the 'getWeatherForecastByLocation' tool, which retrieves weather forecasts based on latitude and longitude. Includes example usage with a client.

```java
@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastByLocation(
    double latitude,   // Latitude coordinate
    double longitude   // Longitude coordinate
) {
    // Returns detailed forecast including:
    // - Temperature and unit
    // - Wind speed and direction
    // - Detailed forecast description
}

// Example usage:
CallToolResult forecast = client.callTool(
    new CallToolRequest("getWeatherForecastByLocation",
        Map.of(
            "latitude", 47.6062,    // Seattle coordinates
            "longitude", -122.3321
        )
    )
);
```

--------------------------------

### Running STDIO Client with Configuration (Bash)

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-webmvc-server/README.md

Command to run the Spring AI starter default client using a configuration file for STDIO transport. It includes setting the server configuration path and user input.

```bash
java -Dspring.ai.mcp.client.stdio.servers-configuration=file:mcp-servers-config.json \
 -Dai.user.input='What is the weather in NY?' \
 -Dlogging.pattern.console= \
 -jar mcp-starter-default-client-0.0.1-SNAPSHOT.jar
```

--------------------------------

### Spring Boot Application Setup for MCP Server

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-webmvc-server/README.md

Java code demonstrating the main Spring Boot application class for the MCP Weather Server. It includes the main method to run the application and a bean definition for registering the weather tools using `MethodToolCallbackProvider`.

```java
@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService){
      return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
    }
}
```

--------------------------------

### Environment-Specific AI Validation Configuration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

Example JSON showing how to configure AI validation differently for various environments (e.g., development, CI) by specifying environment-specific prompt templates.

```json
{
  "requiredEnv": ["OPENAI_API_KEY", "BRAVE_API_KEY", "DATABASE_URL"],
  "aiValidation": {
    "enabled": true,
    "validationMode": "hybrid",
    "environmentSpecific": {
      "development": { "promptTemplate": "detailed_validation" },
      "ci": { "promptTemplate": "quick_validation" }
    }
  }
}
```

--------------------------------

### Build Server Jar

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/README.md

Command to build the server JAR file, skipping tests.

```bash
./mvnw clean install -DskipTests
```

--------------------------------

### ExampleInfo.json Configuration Fields

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

Details the fields available in the ExampleInfo.json schema for configuring AI validation. It specifies whether each field is required, provides a description, and includes an example value.

```APIDOC
ExampleInfo.json Schema Fields:

- timeoutSec: (Required) Integer. Timeout in seconds for the validation process.
  Example: 300

- successRegex: (Optional) Array of Strings. Regex patterns to match for basic success.
  Example: ["BUILD SUCCESS", "Started.*Application"]

- requiredEnv: (Optional) Array of Strings. Environment variables required for the example to run.
  Example: ["OPENAI_API_KEY"]

- aiValidation: (Required) Object. Configuration for AI-powered validation.
  - enabled: (Required) Boolean. Enables or disables AI validation.
    Example: true
  - validationMode: (Required) String. Mode for AI validation ('primary' or 'hybrid').
    Example: "hybrid"
  - readmeFile: (Optional) String. Path to the README file for context.
    Example: "../README.md"
  - expectedBehavior: (Required) String. Detailed description of the expected outcome.
    Example: "Chat with coherent responses"
  - promptTemplate: (Required) String. The AI prompt template to use for validation.
    Example: "chat_example_validation"
  - components: (Optional) Array of Strings. System components to validate (e.g., 'client', 'server').
    Example: ["client", "server"]
  - successCriteria: (Optional) Object. Additional criteria for success.
    - requiresUserInteraction: (Optional) Boolean. Whether user interaction is expected.
      Example: false
    - expectedOutputTypes: (Optional) Array of Strings. Types of expected outputs (e.g., 'conversation', 'tool_usage').
      Example: ["conversation", "tool_usage"]
    - expectedSteps: (Optional) Integer. The number of expected steps in the process.
      Example: 3
    - evaluationRequired: (Optional) Boolean. Whether explicit evaluation is needed.
      Example: true
```

--------------------------------

### Recommended Integration Test Commands

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Presents a curated list of commonly used commands for various development and testing scenarios, including fast feedback during development, monitoring long-running tests, debugging failures, CI execution, and log management.

```bash
# For development (fast feedback)
python3 scripts/run_integration_tests.py --stream --filter="helloworld"
```

```bash
# For long-running tests (see progress)  
python3 scripts/run_integration_tests.py --stream --filter="prompt-engineering"
```

```bash
# For debugging failures
python3 scripts/run_integration_tests.py --verbose --fail-fast
```

```bash
# For CI/comprehensive testing
python3 scripts/run_integration_tests.py --report=integration-results.md
```

```bash
# For log management
python3 scripts/run_integration_tests.py --clean-logs  # Clean up old logs
python3 scripts/run_integration_tests.py --structured-logs --filter="failing-test"  # Organized debugging
```

--------------------------------

### Start MCP Weather Server

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/sampling/mcp-sampling-client/README.md

Commands to navigate to the server directory, build the project, and run the MCP Weather Server.

```bash
cd ../mcp-weather-webmvc-server
./mvnw clean install -DskipTests
java -jar target/mcp-sampling-weather-server-0.0.1-SNAPSHOT.jar
```

--------------------------------

### AI Validation Output Structure

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/README.md

Example of the JSON output structure from an AI validation process, detailing success status, confidence score, reasoning, demonstrated functionality, and cost information.

```json
{
  "success": true,
  "confidence": 0.95,
  "reasoning": "Application successfully demonstrated chat functionality with coherent responses",
  "functionality_demonstrated": [
    "Spring Boot started correctly",
    "AI model generated appropriate joke response",
    "User interaction flow worked as expected"
  ],
  "cost_info": {
    "total_tokens": 420,
    "duration_seconds": 12.5
  }
}
```

--------------------------------

### Custom Success Criteria Configuration

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

Example JSON configuration for defining custom success criteria in AI validation, including interaction requirements, expected output types, and response metrics.

```json
{
  "successCriteria": {
    "requiresUserInteraction": false,
    "expectedOutputTypes": ["conversation", "tool_usage", "api_response"],
    "expectedSteps": 3,
    "evaluationRequired": true,
    "outputFormat": "markdown_table",
    "minimumResponseLength": 100
  }
}
```

--------------------------------

### Generate Integration Tests with AI Validation

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/integration-testing/docs/AI_VALIDATION.md

Examples of using the scaffolding tool to generate integration tests with different AI validation configurations, including simple, complex, and MCP-specific scenarios.

```bash
# Simple example with hybrid AI validation
python3 scripts/scaffold_integration_test.py kotlin/kotlin-hello-world

# Complex workflow with primary AI validation
python3 scripts/scaffold_integration_test.py agentic-patterns/chain-workflow --complexity complex --ai-mode primary

# MCP example with client-server validation
python3 scripts/scaffold_integration_test.py model-context-protocol/weather/server --complexity mcp
```

--------------------------------

### Running STDIO Client with Configuration (Bash)

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-webflux-server/README.md

Illustrates how to run an MCP client application using a JSON configuration file for STDIO transport. It includes setting the server configuration path and user input.

```bash
java -Dspring.ai.mcp.client.stdio.servers-configuration=file:mcp-servers-config.json \
 -Dai.user.input='What is the weather in NY?' \
 -Dlogging.pattern.console= \
 -jar mcp-starter-webflux-client-0.0.1-SNAPSHOT.jar
```

--------------------------------

### Java Routing Workflow Example

Source: https://github.com/spring-projects/spring-ai-examples/blob/main/agentic-patterns/routing-workflow/README.md

Demonstrates how to create and use a RoutingWorkflow in Java. It initializes the workflow with a ChatClient, defines routes with specialized prompts, and processes user input to get a routed response.

```java
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import java.util.Map;

// Assuming RoutingWorkflow and RouteResponse are defined elsewhere
// import com.example.RoutingWorkflow;
// import com.example.RouteResponse;

public class RoutingExample {

    @Autowired
    private ChatClient chatClient;

    public void runExample() {
        // Create the workflow
        RoutingWorkflow workflow = new RoutingWorkflow(chatClient);

        // Define specialized prompts for different types of input
        Map<String, String> routes = Map.of(
            "billing", "You are a billing specialist. Help resolve billing issues...",
            "technical", "You are a technical support engineer. Help solve technical problems...",
            "general", "You are a customer service representative. Help with general inquiries..."
        );

        // Process input
        String input = "My account was charged twice last week";
        String response = workflow.route(input, routes);

        System.out.println("Response: " + response);
    }

    // Placeholder for RoutingWorkflow class definition
    static class RoutingWorkflow {
        private ChatClient chatClient;

        public RoutingWorkflow(ChatClient chatClient) {
            this.chatClient = chatClient;
        }

        public String route(String input, Map<String, String> routes) {
            // Placeholder for routing logic
            // In a real implementation, this would involve LLM calls to classify and select a route
            System.out.println("Routing input: " + input);
            // Simulate finding a route and generating a response
            if (input.toLowerCase().contains("billing") || input.toLowerCase().contains("charged")) {
                return "Billing specialist response for: " + input;
            } else if (input.toLowerCase().contains("technical") || input.toLowerCase().contains("problem")) {
                return "Technical support response for: " + input;
            } else {
                return "General inquiry response for: " + input;
            }
        }
    }
}

```