ADR-0007: Maven Central Search via External MCP

Status

Accepted

Context

To support Apache Maven development workflows, we need the ability to search Maven Central for artifacts, versions, and classes. This enables use cases such as:

  • Finding the latest version of a dependency

  • Checking which artifacts contain a specific class

  • Comparing current project dependencies with latest available versions

  • Analyzing dependency health and release patterns

Options Evaluated

Option 1: Wrap mcs CLI

The Maven Central Search (mcs) tool by Maarten Mulders is a mature CLI for querying Maven Central. It supports wildcard search, coordinate search, class search, and vulnerability scanning.

Option 1a: Native Installation

Requires mcs installed on the host system via SDKman, Homebrew, Snap, or Chocolatey.

Pros

  • Native GraalVM binaries (fast startup)

  • Simple integration via CLI wrapper

Cons

  • External dependency on the host system

  • CLI output parsing is fragile

  • Users must install mcs separately

Option 1b: Docker Image with mcs

Package mcs in a Docker container and integrate like other Docker-based MCPs.

Pros

  • No host installation required

  • Consistent environment across systems

  • Follows the same pattern as other Docker MCPs

Cons

  • Docker overhead for a simple CLI tool

  • Still requires parsing CLI output

  • Would need to build and maintain Docker image

Option 2: Direct Maven Central REST API

The official REST API at https://search.maven.org/solrsearch/select provides direct access.

Query Type Parameter Example

By groupId

q=g:org.apache.maven

By artifactId

q=a:maven-core

By class name

q=c:MavenProject

Fully-qualified class

q=fc:org.apache.maven.project.MavenProject

By SHA-1

q=1:<sha1>

Combined

q=g:org.apache.maven+AND+a:maven-core
Pros

  • No external dependencies

  • Full control over queries and responses

  • No documented rate limits

  • JSON/XML response formats

Cons

  • Requires implementing HTTP client and response parsing

  • Need to handle caching ourselves

Option 3: Existing Maven Central MCP Servers

Several third-party MCP servers already exist:

Project Language Approach

maven-tools-mcp

Java

Reads maven-metadata.xml directly; Spring Boot with Context7 integration

mcp-maven-central-search

Python

Uses search API

mvn-version-server

Python

Simple version queries

Decision

We will use the maven-tools-mcp external MCP server for Maven Central queries.

Rationale

Mature implementation

The maven-tools-mcp server is well-architected with Spring Boot 3.x, includes caching, and has comprehensive tooling (8 core tools plus Context7 integration).

Efficient approach

It reads maven-metadata.xml directly from Maven Central rather than using the search API, which is faster and more reliable for version lookups.

Build tool agnostic

Works with Maven, Gradle, SBT, Mill — any tool using Maven coordinates.

Docker deployment

Available as a pre-built Docker image (arvindand/maven-tools-mcp) with multi-arch support.

Minimal maintenance

As an external MCP, we consume it rather than maintaining the codebase.

Class Search Limitation

The maven-tools-mcp server focuses on artifact/version queries and does not support class name search (finding which artifacts contain a specific class).

For occasional class search, use the Maven Central REST API directly:

https://search.maven.org/solrsearch/select?q=fc:org.example.MyClass&wt=json

For extensive class search requirements, consider Option 1b (Docker image with mcs) as a complementary MCP:

mcs class-search -f org.example.MyClass

The mcs tool provides a richer class search experience with formatted output and vulnerability scanning.

Consequences

Positive

No development effort

Leveraging an existing, well-maintained MCP server.

Rich functionality

Access to dependency analysis, health checks, version comparison out of the box.

Easy deployment

Docker image works with both Claude Desktop and Claude Code.

Negative

External dependency

Reliant on third-party project maintenance.

Class search gap

Need alternative solution for class-based artifact discovery.

Docker requirement

Requires Docker for easiest deployment path.

Mitigations

Class search

For occasional needs, the REST API suffices. For extensive class search, implement Option 1b (Docker image with mcs) as a complementary MCP.

Fallback

If maven-tools-mcp becomes unmaintained, we can implement a simple MCP using the REST API directly (the API is stable and well-documented).

References