Spring AI Examples

The mcp-starter-webflux-client is a command-line Spring Boot application that demonstrates the use of the MCP Client Boot Starter using WebFlux (reactive) transport.

It performs the following workflow:

1. Connects to MCP servers using either STDIO or SSE transports.
2. Automatically registers all discovered MCP tools with a ChatClient.
3. Sends a user-provided question (via the ai.user.input property) to Claude.
4. Outputs the response to the console and exits.

Stack Requirements:

• Spring Boot 4.0.7
• Spring AI 2.0.0
• Java 17+

The AI Validator is an intelligent validation system designed for Spring AI integration tests. It leverages Claude Code to analyze application logs and verify that example applications have successfully demonstrated their intended functionality. It specifically checks for three criteria:

1. The application ran without exceptions.
2. The application demonstrated its intended functionality.
3. Multi-component examples worked correctly.

The Spring AI MCP Annotations Server demonstrates how to implement the four core MCP capabilities using a declarative, annotation-driven approach.

Tools

Tools allow the model to perform actions. They are implemented using @Tool (via SpringAiToolProvider) or @McpTool (via McpToolProvider, DocumentProvider, or ToolProvider2).

Resources

Resources provide data to the model via URIs. Examples include:

• user-profile://{username}
• docs://documents/{docId}
• static://hello

Prompts

Prompts are pre-defined templates for interactions, such as greeting, personalized-message, or conversation-starter.

Completions

Completions provide suggestions for text input, implemented using the @McpComplete annotation (e.g., for username or country name suggestions).

The Integration Test Status Report provides a snapshot of the testing coverage for the Spring AI examples. As of December 2024, approximately 73% of the total examples (24 out of 33 modules) have integration tests implemented, with 17 modules passing in the Continuous Integration (CI) environment.

Key Metrics:

• Total Modules: ~33
• Modules with Integration Tests: 24 (73% coverage)
• Tests Passing in CI: 17 (71% of existing tests)
• AI Validation: All 24 modules with integration tests utilize AI validation.

The Parallelization Workflow pattern enables efficient concurrent processing of multiple Large Language Model (LLM) operations. It is implemented via the ParallelizationlWorkflow class and supports two primary variations:

1. Sectioning: Decomposing complex tasks into independent subtasks for concurrent processing.
2. Voting: Executing identical prompts multiple times in parallel to gather diverse perspectives or perform majority voting.

This pattern improves throughput, optimizes LLM API resource utilization, and reduces overall processing time for batch operations.

The workflow is implemented using two primary components:

• ChainWorkflow.java: Manages the core logic of the pattern. It contains the system prompts for every transformation step, the logic to execute the chain, and the gate validation logic between steps.
• Application.java: Handles the Spring Boot application lifecycle, provides the sample input data, configures Spring AI, and includes a command-line runner to demonstrate the workflow.

The integration-testing/CURRENT-TEST-STATUS.md file provides a real-time tracking of the integration test coverage and health for the Spring AI examples. It categorizes tests into four main states:

• PASSING in CI: Tests that are fully functional and running in the Continuous Integration pipeline.
• FIXED but NOT in CI: Tests that pass locally (e.g., after increasing timeouts) but have not yet been integrated into the CI pipeline.
• FAILING/INCOMPLETE: Tests that are currently broken or lack sufficient validation (e.g., only checking content-type instead of protocol logic).
• No Tests Created: Examples that currently lack any integration test coverage.

Use this file to determine which examples are verified and reliable for use, and to identify which examples may require local troubleshooting or manual verification.

The Orchestrator-Workers pattern is a design for LLM-based systems used to handle complex tasks through dynamic decomposition. It consists of three core components:

1. Orchestrator: A central LLM that analyzes the initial task and determines the necessary subtasks.
2. Workers: Specialized LLMs that execute the specific subtasks identified by the orchestrator.
3. Synthesizer: A component that aggregates the individual worker outputs into a single, cohesive final result.

This pattern is ideal for tasks where subtasks cannot be predicted upfront, require different perspectives, or benefit from adaptive problem-solving.

The Evaluator-Optimizer pattern is a dual-LLM iterative process used to build effective agents. It mimics a human writer's refinement process by using two distinct roles:

1. Generator LLM: Produces the initial response and subsequently refines it based on received feedback.
2. Evaluator LLM: Analyzes the generated response against specific quality criteria and provides detailed feedback.

The workflow follows a loop: Task Input $\rightarrow$ Generator $\rightarrow$ Evaluator. If the evaluator returns a PASS, the process ends. If it returns NEEDS_IMPROVEMENT, the feedback is fed back into the Generator for a new cycle. This pattern is ideal for tasks with clear evaluation criteria, such as literary translation, complex search, code generation, or content creation.