feat: Spring Boot 4 + Spring AI 2.0 upgrade

[adityamparikh]

Upgrades the Solr MCP server to Spring Boot 4.1.1 and Spring AI 2.0.1.

This PR is scoped to the Spring Boot 4 / Spring AI 2.0 upgrade only, rebased onto current main (a84033b). Changes that had accumulated on the sb4 branch but are unrelated to the upgrade (CI Solr-version-matrix tweaks, Solr 10 /admin/metrics test skips, the docker-image-tag-suffix helper superseded by #139, and cosmetic refactors) have been intentionally excluded.

Both are current GA releases on Maven Central (verified against maven-metadata.xml), so no milestone repositories are required.

Breaking configuration change: OTLP export moves from gRPC on port 4317 to HTTP on 4318, with a separate full URL per signal. OTEL_TRACES_URL changes meaning — it was a base endpoint and is now a complete path ending in /v1/traces. A value carried over from a pre-SB4 deployment will not error; traces simply stop arriving. OTEL_METRICS_URL and OTEL_LOGS_URL are new. See docs/observability.md.

Highlights

• Jackson 3: tools.jackson.databind replaces com.fasterxml.jackson.databind (annotations stay in com.fasterxml.jackson.annotation); the MCP SDK uses mcp-json-jackson3. JacksonException replaces IOException/JsonProcessingException; JsonNode.properties()/asString() replace fields()/asText().
• MCP annotations: package moved org.springaicommunity.mcp.annotation → org.springframework.ai.mcp.annotation (now part of Spring AI core).
• Modular starters: spring-boot-starter-web → -webmvc + -json; explicit spring-ai-autoconfigure-mcp-server-common (no longer transitive after Spring AI 2.0.0-M7); modular test starters.
• Observability: spring-boot-starter-opentelemetry (SB4 idiomatic) for traces, metrics, and OTLP log export, replacing the manual OTel BOM + micrometer-tracing-bridge-otel approach; spring-boot-starter-aspectj for @Observed; OTel logback appender installed programmatically via InstallOpenTelemetryAppender; management.opentelemetry.* OTLP properties.
• Testcontainers 2.x module/package renames.
• JSpecify is built into Spring Boot 4, so the explicit dependency is dropped.
• GraalVM native: AOT NullAway exclusions, JUnit-platform build-time init, DefaultMetaProvider + Solr API model reflection hints, per-profile AOT docs; dependency-resolution alignment for opentelemetry-proto and opentelemetry-api-incubator against the SB 4.1.0 BOM.
• mcp-server-security 0.0.6 → 0.1.14 — see below.

mcp-server-security upgrade

0.0.6 is built against the Spring Boot 3 line: its POM declares spring-core 6.2.9 and spring-security-{web,config,core,oauth2-*} 6.5.2, and it predates mcp-core 2.x entirely. This branch ships Spring Framework 7.0.8 and Spring Security 7.1.0 via the Spring Boot 4.1.0 BOM, so the 0.0.6 bytecode was running against a Security major it was never compiled for.

0.1.14 is the current release of the same library on the Boot 4 line: spring-core 7.0.8, spring-security-* 7.1.0, mcp-core 2.0.0 — matching exactly what Spring Boot 4.1.0 and Spring AI 2.0.0 put on the classpath. The upgrade is a version-catalog change only; the McpServerOAuth2Configurer API used in HttpSecurityConfiguration is unchanged.

Coverage caveat, flagged for reviewers: no automated test in this repo exercises McpServerOAuth2Configurer on any version. It is wired only when OAUTH2_ISSUER_URI is set (HttpSecurityConfiguration#secured), and DockerImageHttpIntegrationTest deliberately runs without an issuer since it has no IdP. That gap is pre-existing and is not introduced by this PR, but it does mean the OAuth2 wiring path is covered by neither the old nor the new version here. Worth closing separately.

Rebase notes

Conflicts against current main were resolved to keep both sides rather than picking a winner:

File	Resolution
build.gradle.kts	Kept both NullAway blocks — main's compileTestJava disable (#179) and this branch's compileAot{,Test}Java disable. Different tasks.
SolrConfig.java	Kept main's java.net.URI (new URL validation) plus tools.jackson.databind.ObjectMapper; dropped the Jackson 2 import.
SearchService.java, CollectionService.java	Kept main's org.jspecify.annotations.Nullable plus the relocated org.springframework.ai.mcp.annotation.*.
SolrNativeHints.java	Spring AI 2.x DefaultMetaProvider coordinate registered; the legacy springaicommunity name kept as a defensive no-op.

Two breaks surfaced only on build/test, not as textual conflicts:

1. Missing static imports. main still uses import static org.junit.jupiter.api.Assertions.*, which this branch had expanded to explicit imports. Git merged the explicit list, so assertions main added since the fork point (feat(search): append remediation hints to common Solr query errors #166 assertThrows, feat(indexing): report indexed field names in tool responses #165 assertFalse) had no import. Added the two rather than reintroducing the wildcard.
2. SolrNativeHintsTest failure. The test added on main via fix(native): register DefaultMetaProvider reflection hint to unbreak nativeTest #172 asserts a hint for org.springaicommunity.mcp.context.DefaultMetaProvider. Spring AI 2.x relocated that class into Spring AI core, and registerTypeIfPresent silently no-ops for a class absent from the classpath — so the legacy coordinate registers nothing here and the assertion failed. The test now pins the coordinate Spring AI 2.x actually ships.

Upstream work landed since the fork point was verified to survive the rebase: all new package-info.java files, #166's search remediation hints, and #165's indexed-field reporting. The service-file diffs versus main are now import migrations only.

Verification

All on JDK 25 (GraalVM 25.0.2 for the native path):

Command	Result
./gradlew build	372 tests, 0 failures, 0 errors, 7 skipped
./gradlew nativeTest -Pnative	227 tests, 0 failures
./gradlew dockerIntegrationTest	49 tests, 0 failures (all three Docker classes, fresh Jib image)

References

• Spring Boot 4.1 Release Notes
• Spring AI 2.0.0 GA announcement

🤖 Generated with Claude Code

[adityamparikh]

Currently using Milestone version of Spring AI 2.0. Will make it ready for review once Spring AI 2.0 is GA.

[epugh]

Thanks for the update on this one... We will merge when we get an official Spring AI 2.0 release!

[adityamparikh]

Re-triggering CI now that ci.yml has landed on main (#117).

[epugh]

Looks like you have some conflicts.. I think you need to update from main to pick up the new ci stuff?

[adityamparikh]

Let's get 1.0 out.
This can be next minor version update.

[adityamparikh]

Rebased onto main (a84033b) and now green: 372 tests, 0 failures, 7 skipped on Spring Boot 4.1.0 + Spring AI 2.0.0 GA.

I have not force-pushed this PR's branch. Its head is adityamparikh:sb4, which is the long-lived integration branch — 9 local branches track it (chore/bump-*-sb4, feat/enable-virtual-threads-sb4, sb4-extras, …) and rewriting it would strand all of them. The rebased result is on adityamparikh:sb4-rebased-20260819 instead; say the word and I'll either retarget this PR's head to it or fast-forward sb4 deliberately.

Four conflicts, all from the Spring AI 2.0 relocation meeting upstream's jspecify work:

• CollectionService/SearchService: took the org.springframework.ai.mcp.annotation.* imports and kept org.jspecify.annotations.Nullable — the merged bodies use @Nullable throughout.
• SolrConfig: dropped the Jackson 2 ObjectMapper import (Jackson 3's tools.jackson.databind supersedes it) but kept java.net.URI, which fix: correct indexing, collection-name and service defects #176's path-normalisation fix needs.
• build.gradle.kts: kept both Error Prone blocks — upstream's compileTestJava NullAway disable and this branch's AOT-sources disable are independent.
• SolrNativeHints: kept both the SolrJ EnvUtils resource patterns and the DefaultMetaProvider registrations.

Two things the rebase broke semantically — both merged cleanly and failed only under javac/JUnit, so they are worth naming:

1. This branch had expanded the wildcard Assertions.* static import into an explicit list; upstream then added tests using assertThrows (feat(search): append remediation hints to common Solr query errors #166) and assertFalse, which were not in that list. Compile failure.
2. SolrNativeHintsTest (new upstream) asserts the DefaultMetaProvider hint under its pre-2.x name org.springaicommunity.mcp.context.DefaultMetaProvider. Spring AI 2.x relocated it to org.springframework.ai.mcp.annotation.context. Because the registration uses registerTypeIfPresent — a no-op when the class is absent — the old name passes vacuously on 1.x and fails outright here. The assertion now names the class actually on this classpath. Worth flagging to reviewers: that test is weaker than it looks on main today.

Still parked behind the 1.0 release per the earlier discussion; this is just to keep it merge-ready.

[adityamparikh]

Updated: sb4 now points at the rebased, green state (e01c7da) — this PR shows it directly, so the temporary sb4-rebased-20260819 branch is redundant.

The previous sb4 tip (cb0d94e) is preserved on adityamparikh:backup-sb4-pre-rebase-20260819 if anything needs recovering. Branches that were tracking the old sb4 (chore/bump-*-sb4, feat/enable-virtual-threads-sb4, sb4-extras, …) will need rebasing onto the new tip.

[adityamparikh]

Pushed 6364bd3 addressing review findings.

Versions bumped

4.1.0 → 4.1.1 and 2.0.0 → 2.0.1, both checked against maven-metadata.xml directly (the
Maven Central search index returns stale, unsorted results for these coordinates). The PR
description called 4.1.0/2.0.0 "the latest GA releases" — true when written, no longer.
Description updated to match.

The substantive finding: observability docs would have broken users

This PR moves OTLP export from gRPC on 4317 to HTTP on 4318, with a separate full URL per
signal. That silently redefines OTEL_TRACES_URL — it used to be a base endpoint, and is now a
complete path ending in /v1/traces.

docs/observability.md — the user-facing guide README links to — was untouched by this PR and
still documented the removed otel.exporter.otlp.* properties plus:

export OTEL_TRACES_URL=https://otel-collector.example.com:4317

Following that after this merged would not error. Traces would just stop arriving, which is
the worst way for a telemetry config to fail.

Fixed:

• docs/observability.md — real property names, corrected production example, a variable table,
  and an explicit callout that the semantics changed for anyone upgrading
• dev-docs/Observability.md — this PR adds it, so it now states its relationship to the
  user-facing guide rather than silently competing with it; the three OTLP defaults are filled in
  instead of "(auto-configured)"
• README.md — names all four OTEL variables
• AGENTS.md — version references, plus the OTEL variables in Key Configuration

Also worth flagging as breaking in the release notes, not just the docs: anyone with
OTEL_TRACES_URL already set in a deployment is affected.

Smaller items

• Broken image removed. dev-docs/Observability.md referenced images/grafana-traces.png,
  which does not exist anywhere in the repo — a broken-image icon on GitHub, introduced by this
  PR. The prose following it already describes the trace breakdown span by span, so it stands
  alone. Caught by a link check, not by reading.
• The mongodb exclude is now explained. It sat uncommented in a file where the cyclonedx pin
  above it gets fourteen lines of rationale — exactly the kind of thing someone deletes while
  tidying, and being developmentOnly it would break local bootRun without CI noticing.
• CycloneDX pin now has a tracker (build: revisit the CycloneDX 2.4.1 pin once the Gradle 9.4.1 variant conflict is fixed #186) linked from both build.gradle.kts and AGENTS.md,
  with a checklist for verifying the SBOM still lands where generateBinaryLicense expects it.

Verification

• ./gradlew build — green, 372 tests / 0 failures, matching main's count exactly
• ./gradlew nativeTest -Pnative — green, 227 passing / 0 failed, unchanged by the bump

Merge-order note

This PR and #175 both rewrite the same line in JsonResponseParser.toNamedList — this one changes
fields().forEachRemaining(...) to properties().forEach(...) for Jackson 3, #175 threads a node
path through it for the empty-facet fix. They compose (the properties() call plus the path
argument), but it is a guaranteed conflict. #175 is small and ready, so merging it first makes
this the cheaper rebase.