solr-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

Project Overview

Solr MCP Server is a Spring AI Model Context Protocol (MCP) server that enables AI assistants to interact with Apache Solr. It provides tools for searching, indexing, and managing Solr collections through the MCP protocol.

• Status: Apache incubating project (v1.0.0-SNAPSHOT)
• Java: 25+ (centralized in build.gradle.kts)
• Framework: Spring Boot 4.1.1, Spring AI 2.0.1
• License: Apache 2.0

Common Commands

# Build and test
./gradlew build                    # Full build with tests
./gradlew assemble                 # Build without tests (faster)

# Testing
./gradlew test                               # Run all tests
./gradlew test --tests SearchServiceTest     # Run specific test class
./gradlew test --tests "*IntegrationTest"    # Run integration tests
./gradlew test jacocoTestReport              # Tests with coverage report

# SBOM (Software Bill of Materials)
./gradlew cyclonedxBom                       # Generate build/reports/cyclonedx/application.cdx.json

# Gradle wrapper upgrade (run twice so the new version regenerates the wrapper jar;
# wrapper settings such as retries live on tasks.wrapper in build.gradle.kts)
./gradlew wrapper --gradle-version latest

# Code formatting (REQUIRED before commit)
./gradlew spotlessApply            # Apply formatting
./gradlew spotlessCheck            # Check formatting

# Docker images
./gradlew jibDockerBuild                                  # JVM (Jib):    solr-mcp:<v>                  (both stdio + http)
./gradlew bootBuildImage -Pnative                         # Native stdio: solr-mcp:<v>-native-stdio
./gradlew bootBuildImage -Pnative -Pprofile=http          # Native http:  solr-mcp:<v>-native-http
./gradlew dockerIntegrationTest                           # Test JVM Jib (stdio + http + MCP stdio)
./gradlew dockerIntegrationTest -Pnative                  # Test native stdio
./gradlew dockerIntegrationTest -Pnative -Pprofile=http   # Test native http

# Native image (requires GraalVM JDK 25; -Pnative applies the graalvm-native plugin)
./gradlew nativeCompile -Pnative             # Compile native binary (host OS only)
./gradlew nativeTest -Pnative                # Run tests as native image

# Run locally
# STDIO disables Docker Compose auto-start (spring.docker.compose.enabled=false in
# application-stdio.properties) — run `docker compose up -d` first, same as for the
# packaged jar/Docker/native image or to start the boot-ignored `lgtm` service.
docker compose up -d && ./gradlew bootRun    # STDIO mode (default)
# HTTP mode enables it (application-http.properties), so bootRun auto-starts/stops
# compose.yaml's solr/zoo via the developmentOnly spring-boot-docker-compose starter.
PROFILES=http ./gradlew bootRun    # HTTP mode